Content Migration: Exporting Content
Applies to: SharePoint Foundation 2010
Content migration is a two-step process. First, you export content from the source to a migration package, and then you import the migration package to the destination.
Overview of the Export Operation
The flowchart below illustrates the conceptual flow of a typical export operation using the migration APIs in the Deployment namespace (optionally, in conjunction with the Stsadm.exe tool). The flowchart illustrates how to support a scenario where an entire site collection is migrated to create a parallel, identical site (retaining object identity), and then subsequent selective migrations take place on a recurring schedule. These later, "selective" migrations provide export/import only on those objects that meet specified criteria (for example, have changed in the previous twenty-four hours).
Selective Migration: Export Flowchart
.gif "Export operations flowchart")
Notice that before running selective migrations, you must run a full migration in order to set up your destination server. When running this prepatory full migration, you must set the RetainObjectIdentity property on the SPImportSettings object to true.
Note, too, that your first decision is determining whether you intend a full or selective migration.
Export Settings (SPExportSettings) Properties
The SPDeploymentSettings class serves as the base class from which both SPExportSettings and SPImportSettings are derived. Its members, then, are inherited by both of the these derived classes; furthermore, each of the derived classes (export and import settings) contain specialized export- and import-related members.
Properties on the Microsoft.SharePoint.Deployment.SPExportSettings class, plus those of the base class, fall into four groups:
Required: Property settings that are required for export.
Important: Property settings that are of high importance and that you should consider in your export planning.
Selective-related: Property settings that are specifically related to selective migration export operations.
Minor: Minor or rarely used property settings.
Required export settings
-
Retrieves the export object collection object (SPExportObjectCollection)
BaseFileName (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Sets or retrieves the name of the content migration package (.cmp) file, or files. These consist of one or more .cab files (using the .cmp file extension). The value is taken from the baseFileName parameter on the SPDeploymentSettings class constructor (SPDeploymentSettings).
When there are multiple .cmp files, the file names are appended numerically. For example, where the baseFileName parameter is "MyWeb", and where the export operation produces multiple .cmp files, the migration packages are named "MyWeb1.cmp", "MyWeb2.cmp", and so forth.
SiteUrl (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Sets or retrieves the URL of site collection that contains the content that is being exported. The value is an absolute URL to the site. This value is provided in the siteUrl parameter of the SPDeploymentSettings class constructor (SPDeploymentSettings).
FileLocation (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Sets or retrieves the file path and directory location where the conten migration package (or packages) are placed on export. This value is provided in the fileLocation parameter of the SPDeploymentSettings class constructor (SPDeploymentSettings).
Important export settings
-
Sets or retrieves a value from the SPIncludeVersions enumeration that specifies, by version, what content is selected for export to the content migration package. There are four enumeration values:
All, which exports all existing versions of selected files;
CurrentVersion, which exports only the most recent version of selected files;
LastMajor, which exports only the last major version of selected files. This is the default value.
LastMajorAndMinor, which exports the last major version and its minor versions.
Note that LastMajor is the default value.
CommandLineVerbose (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Retrieves or sets a Boolean value that specifies whether migration information is outputted to a command line console. The default value is false.
FileCompression (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Retrieves or sets a Boolean value that specifies whether the content migration package is compressed using the CAB compression protocol. The default value is true; the default is for the content migration package to be compressed.
IncludeSecurity (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Retrieves or sets a SPIncludeSecurity enumeration value that specifies the amount of user security roles and role membership data to include in the migration package. The enumeration provide three values:
All: Specifies the export of user memberships and role assignments such as out of the box roles like Web Designer, plus any custom roles that extend from the out of the box roles. The ACL for each object is exported to the migration package, as well as user information defined in the DAP or LDAP servers.
None: No user role or security group information is exported. This is the default.
WssOnly: Specifies the export of user memberships and role assignments such as out of the box roles like Web Designer, plus any custom roles that extend from the out of the box roles. The ACL for each object is exported to the migration package; however, user information defined in the DAP or LDAP servers is not exported.
The default value is None.
LogFilePath (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Retrieves or sets a value that specifies the fully qualified path to the log file for the content migration operation.
Selective migration-related export settings
-
Retrieves a change token (string) that is found in the export operation change log. When doing a selective migration, the current change token specifies a starting point when retrieveing objects that have changed since the last export operation. These objects, then, are selected for migration.
After the selective migration operation is complete, save this value. Then, the next time a selective migration job runs, pass this value to the ExportChangeToken property.
-
Sets or retrieves the change token value that is passed from the CurrentChangeToken property that was saved when the last selective migration operation was performed.
Note that selective migration supports field deletion at the source and destination sites when (a) the ExportMethod property is set to ExportChanges, and (b) when the P:Microsoft.SharePoint.Deployment.SPImportSettings.RetainObjectIdentity property on the SPImportSettings object is set to true.
-
Provides a value from the SPExportMethodType enumeration that specifies whether to do a full migration, exporting all objects on the source site (ExportAll), or instaead an incremental, or a selective migration that only migrates objects that have changed since the last migration (ExportChanges).
Be sure to set this value to ExportChanges if you intend to perform a selective migration.
HaltOnWarning (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Sets or retrieves a Boolean value that specifies whether to suspend the migration when a warning is encountered. Set to false to ignore warnings and continue the migration. The default is false.
HaltOnNonfatalError (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Sets or retrieves a Boolean value that specifies whether to suspend the migration when an error (nonfatal) is encountered. Set this value to false to ignore nonfatal errors and continue the migration. The default is false.
Minor export settings
-
Sets or retrieves a Boolean value that specifies whether to the file name for the content migration package is generated automatically. Set to true to automatically generate the content migration package file name. The default is false.
When set to true, the file name value is taken from the baseFileName parameter on the SPDeploymentSettings class constructor (SPDeploymentSettings).
When the export generates multiple .cmp files, the file names are appended numerically. For example, where the baseFileName parameter is "MyWeb", and where the export operation produces multiple .cmp files, the migration packages are named "MyWeb1.cmp", "MyWeb2.cmp", and so forth.
-
Retrieves a read-only collection of export data files returned as an ArrayList (https://msdn.microsoft.com/en-us/library/system.collections.arraylist.aspx) object. The collection itself is populated by using the CleanUpAutoGeneratedDataFiles method on the SPExport class after the export operation is completed.
-
Sets or retrieves a Boolean value that specifies whether to exclude dependent objects from the content migration package (.cmp) file when exporting objects of type SPFile or SPListItem. Set to true to exclude dependencies; the default is false.
-
Sets or retrieves a Boolean value that specifies whether to use the format of the public schema when you export a list field. Set to true if the export uses the public schema format; returns false if the list item field collection is retrieved directly from the database. The defaulst is true.
While retrieving the fields collection directly from the database is more performant, you should note that the format schema that is stored in the database is internal and could change from one version to another.
-
Sets or retrieves and integer that specifies the maximum size of the content migration (.cmp) file in megabytes (MB). The default is 0 (zero) MB, which indicates there is no limit to the size of the migration package.
When you run the export operation, and if the compressed export file exceeds the specified maximum, then the migration is divided into muliple export files.
-
Sets or retrieves a Boolean value that specifes whether to copy the contents of the temporary table that contains export objects to the export log file. Set to true to write the export table to the log file. The default value is false.
You should only use this property when testing your export operation, of if you need to troubleshoot problems with the export, since logging the object table incurs a significant performance drag.
-
Sets or retrieves a Boolean value that specifes whether to overwrite a data file in a content migration package (.cmp) file when re-exporting a file of the same name. Set to true to overwrite existing files.
If you set this property to false, and if the data file already exists, the export operation throws an exception. Furthermore, if the property is set to true, and if the existing data file spans more than one migration package file, the entire file collection is deleted before the export generates new output files.
-
Sets or retrieves a Boolean value that specifes whether to perform a test run of the export operation. Set to true to perform a test run.
Example: Exporting a Complete Site Collection
There are two ways to export an entire site collection (that is, complete a full migration) using the APIs in the Microsoft.SharePoint.Deployment namespace. The first uses the SPExportSettings object, while the second uses the SPSite object.
Export using SPExportSettings Object
The first method for exporting a complete site collection requires that we create an SPExportSettings object to define the configuration settings for the export operations that we intend to perform. Because we do not select specific objects to export (which in fact we would do if this were a selective migration), the operation exports the entire site collection.
Then, we create an SPExport object that is based on the configuration setting that we've just set, and then we start the export operation by callingthe Run() method on the SPExport object.
SPExportSettings settings = new SPExportSettings();
settings.SiteUrl = "http://localhost:SourceSiteCollection";
settings.ExportMethod = SPExportMethodType.ExportAll;
settings.FileLocation = @"c:\export";
settings.FileCompression = false;
settings.CommandLineVerbose = true;
SPExport export = new SPExport(settings);
export.Run();
The export settings properties are documented fully in sections above. However, there are a few important points to note about some of these properties.
SiteUrl Property: |
Provide the absolute URL of the source site collection that you intend to export. Note that the migration APIs cannot access items that are in different site collections in a single export operation. |
ExportMethod Property |
We provided the ExportAll value because we are exporting the entire site collection. If we were performing a selective migration, we would instead provide the ExportChanges value; furthermore, we would need to provide an export change token in another property value. |
FileLocation Property |
Provides a path to the folder where the operation will store the exported content. This value should point to be an empty directory on the destination computer. If the directory does not exist it will be created during export. If you are using file compression, only the compressed files are stored at this location. Otherwise, uncompressed files are stored in the temporary directory specified by the system TMP environment variable. When exporting uncompressed files, you must ensure that this temporary directory has sufficient space available. |
FileCompression Property |
Specifies whether to export the site collection as one or more compressed migration package (.cmp) files. These are simply cabinet files. Because compressing the site collection can be time consuming, it is suggested that you opt to compresss your export file only when necessary - for example, when exporting archival files, or when moving an entire site collection to a new computer. If this is a selective migration, or a copy/move operation, for example, you can increase performance by electing not to compress the files. |
CommandVerbose Property |
This is a flag that enables logging of export operations, similar to the output provided when running stsadm -o export. |
Export Using an SPSite Object
The second method for exporting an entire site collection requires that we add the SPSite object for our site collection to the ExportObjects collection, SPExportObjectCollection. This approach gets us the same result as the previous approach, where the SPSite object was implicityly selected because we did not explicitly select any objects for export.
SPSite site = new SPSite("http://localhost:SourceSiteCollection ");
SPExportObject exportObject = new SPExportObject();
exportObject.Id = site.ID;
exportObject.Type = SPDeploymentObjectType.Site;
SPExportSettings settings = new SPExportSettings();
settings.SiteUrl = "http://localhost:SourceSiteCollection ";
settings.ExportMethod = SPExportMethodType.ExportAll;
settings.FileLocation = @"c:\export";
settings.FileCompression = false;
settings.ExportObjects.Add(exportObject);
SPExport export = new SPExport(settings);
export.Run();
site.dispose();
These export settings properties are documented fully in sections above, and from the examples here are discussed in the table above. However, there are a few important points to note about two properties not yet discussed.
SPExportObject.Id |
Provide the global unique identifier (GUID) of the object intended for export. |
SPExportObject.Type |
Specifies the type of the object to be exported. There are six available SharePoint object types: Site - SPSite object (the site collection) Web - SPWeb object (often referred to as the "site") List - SPList object File - SPFile object Folder - SPFolder object ListItem - SPListItem object |