Deep Dive into the SharePoint Content Deployment and Migration API - Part 2
[Part 1 - Part 2 - Part 3 - Part 4 - Part 5 - Part 6]
Providing some real world samples for export
To demonstrate how powerful the Content Deployment and Migration API is I will now provide some real world examples:
-
Export a complete Site Collection
-
Export a specific sub web
-
Exporting other elements like lists, document libraries, list items or documents from a document library
-
Exporting using compression
-
Incremental Export
The examples below assume that the source site collection is on the local server on port 2000.
Lets start with a scenario that can also be covered by using stsadm.exe:
1) Export a complete Site Collection
Actually there are two different methods to export a complete site collection.
Method 1)
SPExportSettings settings = new SPExportSettings();
settings.SiteUrl = "http://localhost:2000";
settings.ExportMethod = SPExportMethodType.ExportAll;
settings.FileLocation = @"c:\export";
settings.FileCompression = false;
settings.CommandLineVerbose = true;
SPExport export = new SPExport(settings);
export.Run();
So what did we actually do here? First we created a SPExportSettings object to define the general configuration settings for the export we would like to perform. As we did not select a specific object to export the configured site collection will be selected for export. Then we created the SPExport object based on the configured settings and started the export by calling the Run method.
Here is a short explanation about the settings being used in the code above:
-
SiteUrl - this property defines which site collection the export should use. All objects being exported always have to be in the same site collection. The Content Deployment and Migration API cannot access items in different site collections in a single operation.
-
ExportMethod - this property allows to define whether to perform an incremental export (value = ExportChanges) or everything (value = ExportAll). Be aware that ExportChanges would require to provide an Export Change Token in a separate property.
-
FileLocation - this property defines where to store the exported content. The value should point to be an empty directory. If the directory does not exist it will be created during export. If file compression is being used, then only the compressed files will be stored on this location. The uncompressed files will be stored in the directory identified by the value of the system wide TMP environment variable. So you need to ensure that the directory the TMP environment variable points to also needs to have sufficient space available.
-
FileCompression - this property defines whether the content should be compressed into a CAB file. If you need to archive the exported content or need to transfer it to a different machine you should choose to compress. If you only export the content to import it afterwards using code on the same machine and don't need to archive (e.g. a copy or move operation) then you should decide to disable the compression as this is significantly quicker.
-
CommandLineVerbose - this parameter allows to control if the API should provide some verbose output. If you have ever seen the generated output when running STSADM -o export: this is exactly the flag the generates this output. If the value is false no output is generated.
Method 2)
SPSite site = new SPSite("http://localhost:2000");
SPExportObject exportObject = new SPExportObject();
exportObject.Id = site.ID;
exportObject.Type = SPDeploymentObjectType.Site;
SPExportSettings settings = new SPExportSettings();
settings.SiteUrl = "http://localhost:2000";
settings.ExportMethod = SPExportMethodType.ExportAll;
settings.FileLocation = @"c:\export";
settings.FileCompression = false;
settings.ExportObjects.Add(exportObject);
SPExport export = new SPExport(settings);
export.Run();
site.Dispose();
What did we actually do here? In this method we explicitly add a specific object to the ExportObjects collection - the SPSite object defining the site collection. This leads to the same result as the first method where the SPSite object was implicitly selected as no explicit object was selected for export.
Here is a short explanation about the settings being used in the code above:
-
SPExportObject.Id - GUID of the object that should be exported
-
SPExportObject.Type - The type of the object to be exported. This can be one of the following:
-
Site = SPSite object (the site collection)
-
Web = SPWeb object (often referred to as site)
-
List = SPList object
-
File = SPFile object
-
Folder = SPFolder object
-
ListItem = SPListItem object
-
for the other properties see Method 1
2) Export a specific sub web
The code to export a specific subweb is very similar to the code used in method 2 to export the complete site collection:
SPSite site = new SPSite("http://localhost:2000");
SPWeb web = site.OpenWeb("/SomeWeb");
SPExportObject exportObject = new SPExportObject();
exportObject.Id = web.ID;
exportObject.IncludeDescendants = SPIncludeDescendants.All;
exportObject.Type = SPDeploymentObjectType.Web;
SPExportSettings settings = new SPExportSettings();
settings.SiteUrl = "http://localhost:2000";
settings.ExportMethod = SPExportMethodType.ExportAll;
settings.FileLocation = @"c:\export";
settings.FileCompression = false;
settings.ExcludeDependencies = false;
settings.ExportObjects.Add(exportObject);
SPExport export = new SPExport(settings);
export.Run();
web.Dispose();
site.Dispose();
Be aware that when exporting a specific sub web using the method above might also export objects outside the specific subweb as not only the objects in the sub web are exported but also dependent objects like images referenced in pages by this sub web and the master page assigned to the sub web.
Whether such dependent objects should be exported or not can be controlled by the ExcludeDependencies property of the SPExportSettings. Whether child objects of an object are exported can be controlled using the IncludeDecendents property of the SPExportObject object:
3) Exporting other elements like lists, document libraries, list items or documents from a document library
Other objects or containers can be exported in the same way by adding them to the ExportObjects collection.
SPSite site = new SPSite("http://localhost:2000");
SPWeb web = site.OpenWeb("/SomeWeb");
SPList list = web.Lists["MyList"];
SPListItem listItem = list.Items[0]; // select the first list item
SPExportObject exportObject = new SPExportObject();
exportObject.Id = list.ID;
exportObject.Type = SPDeploymentObjectType.List;
SPExportObject exportObject = new SPExportObject();
exportObject.Id = listItem.UniqueId;
exportObject.Type = SPDeploymentObjectType.ListItem;
...
Exporting document libraries can be done using the same code as exporting a list as internally a document library is implemented as a list. And a document in a document library can be exported using the same method as exporting any other list item. The SPFile object of the document will automatically be automatically exported together with the SPListItem object.
4) Exporting using compression
When exporting using compression additional settings in the SPExportSettings object need to be adjusted:
SPExportSettings settings = new SPExportSettings();
settings.FileLocation =
@"c:\export";
settings.FileCompression = true;
settings.FileMaxSize = 10; // defines the maximum filesize as 10 MB
settings.BaseFileName = "ExportedItems.cmp";
...
Here is an explanation about the two properties:
-
FileCompression - this property defines whether the content should be compressed into a CAB file. If you need to archive the exported content or need to transfer it to a different machine you should choose to compress. If you only export the content to import it afterwards using code on the same machine and don't need to archive (e.g. a copy or move operation) then you should decide to disable the compression as this is significantly quicker.
-
FileLocation - this property defines where to place the export files. If compression is used it defines the location of the generated compressed content migration pack.
-
FileMaxSize - this property defines the maximum size of the created content migration pack.
-
BaseFileName - this property is only used if compression is enabled. It defines the name of the compressed content migration pack file. The default extension (if not specified) is ".cmp". If the size of FileMaxSize is exceeded a new file is created with the BaseFileName and an integer number. E.g. with the above configuration the next file would be ExportedItems1.cmp
5) Incremental Export
If incremental export should be done it is required to save the Change Token of the last full or incremental export. This change token needs then be provided in the ExportSettings to allow the Content Deployment and Migration API to determine which items have changed.
So after a previous export the change token can be retrieved using the following code:
SPExportSettings settings = new SPExportSettings();
...
SPExport export = new SPExport(settings);
export.Run();
string ChangeToken = settings.CurrentChangeToken;
Explanation:
-
CurrentChangeToken - this property is a read-only parameter populated during export. It contains the Change Token right after the export. So doing an incremental export providing this change token in the future will export all items that have been created, changed or deleted in the configured scope after the change token was generated.
To start an incremental export using this change token would then be done using the following code:
SPExportSettings settings = new SPExportSettings();
settings.ExportMethod = SPExportMethodType.ExportChanges;
settings.ExportChangeToken = oldChangeToken;
...
Explanation:
-
ExportMethod - this property allows to define whether to perform an incremental export (value = ExportChanges) or everything (value = ExportAll).
-
ExportChangeToken - this property defines which items to export when using incremental deployment. the incremental export will only export items that have been created, changed or deleted in the configured scope after the change token was generated.
Now after we have seen how to export items the
Part 3 of this article series will cover the import part.
