Content Migration: Exporting Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

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

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

• ExportObjects

  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

• IncludeVersions

  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 you want migration information to be 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

• CurrentChangeToken

  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.

• ExportChangeToken

  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.

• ExportMethod

  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 to false to ignore nonfatal errors and continue the migration. The default is false.

Minor export settings

• AutoGenerateDataFileName

  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.

• DataFiles

  Retrieves a read-only collection of export data files returned as an ArrayList (http://msdn2.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.

• ExcludeDependencies

  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.

• ExportPublicSchema

  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.

• FileMaxSize

  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.

• LogExportObjectsTable

  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.

• OverwriteExistingDataFile

  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.

• TestRun

  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 (SPSite) 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.

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.

See Also

Concepts

Selective Content Migration