Selective Content Migration in Windows SharePoint Services 3.0

  • Article

Summary: Learn how to perform a "selective" content migration in Windows SharePoint Services 3.0, which allows you to migrate items that are selected by using specific criteria and custom logic. (23 printed pages)

Nick Gattuccio, Microsoft Corporation

Patrick Simek, Microsoft Corporation

Stefan Goβner, Microsoft Corporation

March 2008

Applies to:

Windows SharePoint Services 3.0, Microsoft Office SharePoint Server 2007

Contents

  • Content Migration: Full vs. Selective

  • Full Migration Overview

  • Selective Migration Overview

  • Migration Scenarios

  • Key Concepts in Selective Migration

  • Migration Planning

  • Planning for Performance

  • Exporting Content

  • Export Settings Properties (SPExportSettings)

  • Importing Content

  • Conclusion

  • Additional Resources

Content Migration: Full vs. Selective

Content migration in Windows SharePoint Services 3.0 supports moving content from one SharePoint Web site to another. This process is sometimes referred to as content deployment. However, you can use selective migration during recurring programmatic file transfer operations that occur on a set schedule, or that respond to triggering events.

A "full" content migration is an operation that moves an entire site collection from a source server to one or more destination servers. The outcome is reproducing a mirror image of the source site collection on the specified target or targets.

Selective migration, on the other hand, refers to any of several content migration scenarios in which items on the source site collection are selected for migration on the basis of specified criteria and custom logic that are introduced by using the content deployment and migration APIs located in the Microsoft.SharePoint.Deployment namespace.

Full Migration Overview

Many scenarios require moving content from one SharePoint site to another.The SharePoint Services administrative tool, Stsadm.exe, provides an easy way to move the contents of an entire site collection to a new destination. However, if you need to move only a specific number of files, or if you need to customize or automate the migration in any way, you must create a custom solution by using classes in the Microsoft.SharePoint.Deployment namespace.

You can perform a full migration by using either of two main approaches:

However, both of these methods have limitations. Both limit you to migrating only a full SharePoint site or site collection. In addition, neither approach allows you to retain object identity during the migration operation. Retaining object identity is an essential feature of selective migration. Using Stsadm.exe and Sites Web service have other limitations as well.

Consequently, content migration scenarios that require you to export only selected content, or that require you to automate or customize migration operations, there is only one approach: You must write a custom solution that uses the APIs in the Microsoft.SharePoint.Deployment namespace. This selective migration is the focus of this article.

Selective Migration Overview

Selective migration applies, typically, to content you need to migrate from server to server based on factors such as content version (current versus future), time stamp, and content state (approved versus in review, for example). Selection migration criteria provide a high degree of detail from the scope of the site collection down; that is, you have selection control at the scope of the Web, the list, folder, and list item.

Important

You can perform a selective migration only when there is an established source and a recognized destination for a known quantity of content. Selective content migration requires that you have already performed a full migration so that the destination is a mirror image of the source. After the source and destination are in sync, you can then perform selective migration operations to move selected content from the source to the destination.

You can have any number of content migration package (.cmp) files in a migration operation, and you can also have multiple destinations. However, the objects that are contained in a specific .cmp file must originate from a single site collection.

Migration Scenarios

The APIs in the Microsoft.SharePoint.Deployment namespace provide a rich migration toolbox that gives you an enormous degree of flexibility to support wide ranging migration scenarios. Following is a list of migration and deployment features that are supported in Windows SharePoint Services 3.0. The Deployment APIs are sufficiently rich to support any number of special circumstances that you might face. The following list is a high-level, generalized summary of supported migration scenarios.

Supported Activity

Scenario

Export site collection

Export an entire site collection (that is, perform a full migration)

Export specific site

Export a specific site inside a site collection, including or excluding content in subsites as needed. The deployment APIs allow you to include or exclude dependencies.

Export list or library

Export a SharePoint list or document library, or even a specific folder inside a document library.

Export list item or document

Export a single list item or document from a document library. This allows for maximum migration granularity that gives you extensive flexibility in your migration plan.

Export dependencies

Export object dependencies, such as images or attached files.

Choose export format

Generate your export file as a compressed .cmp package file or as uncompressed files.

Limit export file size

Throttle exports by specifying a maximum size for the compressed export package file. If the export contents exceed the maximum package size, multiple export package files are created.

Export in increments

Supports incremental export of items that are selected for export based on change tokens. This allows you to automate the export of all items that have been created, changed, or deleted after the time stamp that is specified in the change token.

Import with or without object identity

Import the exported content with or without preserving object identity—that is, you can configure objects in the export package to retain their object GUIDs. This is a requirement for selective migrations.

Import with same or different parent

Import the migration content under the same or a different parent in the destination content database. Moving items to a different position in the site hierarchy is an operation known as reparenting.

Import with link fixup

Do link fixup during import.

Key Concepts in Selective Migration

A large number of scenarios meet the criteria for selective migration. Following are important content migration concepts that frequently occur in selective migration scenarios.

Content Selection for Export

After the initial full migration occurs and the source and destination sites are established, selective migration relies on logic in your custom code for selection criteria to determine which items are selected for migration. This is the process through which specific items on the source site collection are migrated to the destination site collection based on selection criteria that is specified in your custom code.

In the basic scenario, logic in a code module associated with a timer job runs on a recurring schedule—for example, every 24 hours at 3:00 A.M. The module examines date stamps or change logs (or both), and then selects and exports only those files that changed since the last migration.

The operation relies on the identity of objects in the source and destination site collections. At import time, the destination recognizes objects by GUIDs and then updates their corresponding files accordingly.

Content Migration Package (.cmp) File

The content migration package is simply a cabinet (.cab) file that uses the .cmp file extension. The migration package (.cmp) file aggregates data for export from the source site, along with site structure and dependency data, and stores it as compressed, serialized XML files.

Although the export operation compresses site data by default, you can override this behavior and export uncompressed files by changing the FileCompression property to false. This property is set on the SPDeploymentSettings object.

When using file compression, you must must specify the name of the compressed content migration (.cmp) file by using the BaseFileName property on the SPExportSettings object. The FileLocation property specifies where the compressed file is located on the source server.

By default, the .cmp files are limited to 24 MB in size, although you can change this by using the FileMaxSize property. When site data exceeds the 24-MB limit, your site data is separated into two or more migration files. However, when a single file exceeds the maximum file size, the operation resizes the .cmp file to accommodate the file. You can have any number of .cmp files.

Object Identity

SharePoint objects are identified by GUID on the source server, but at the destination the objects are assigned new GUIDs. This is the default behavior. However, when you are doing selective migration operations where the souce and destination servers need to be synchronized, it is essential that the objects retain their original identity when they are imported, because this is the only way to map object from the source to destination.

You can change the default behavior to retain object identity by setting the RRetainObjectIdentity property on the SPImportSettings object to true.

Note

To use the RetainObjectIdentityproperty to support selective migrations, you must also set the ExportMethod property to the value ExportChanges.

You should use retaining object identity carefully, and in limited scenarios. It most commonly supports a publishing scenario in which source and one or more destination servers are mirror images. When you create a new site that you know receives file updates on a regular basis (for example, from a development or test server), you can enable a smooth link between the two by first doing a full migration from the source to a completely blank site, but with the RetainObjectIdentity property on the SPImportSettings object set to true. This effectively synchronizes the source and destination servers.

It is very important, then, that you do not change or edit files on the destination after synchronizing source and destinations. The initial migration established the mirrored hierarchy and mappings; any modifications to the destination can break the linkage. If this relationship gets broken, your only recourse is to delete the destination site and then recreate it as a mirror image of the source by performing another full migration.

SharePoint content databases do not permit duplicate GUIDs or file names, so you must be careful when implementing the RetainObjectIdentity property. You should not retain object identity when you are simply updating files on the destination server, because the import operation cannot determine whether a file is new or an update, and therefore places a duplicate copy of the file on the destination site.

This occurs because the migration process uses GUIDs, but only down to the level of the item collection. Beneath that level (that is, for individual files) the system uses the file name. Consequently, the import operation simply copies the updated version of the existing file and leaves the original intact, potentially creating duplicates. When the destination server then encounters duplicate file names, it cannot resolve the ambiguity and becomes unstable.

Important

When deleting files, it is very important to delete the files on both the source and destination servers. If you do not do this it can cause duplicate file names and cause the site to be unstable.

To support field deletion (a feature that deletes previous versions of items on the source server when the migration updates and deletes the same file on the destination), the RetainObjectIdentityproperty must be set to true.

Reparenting Objects on Import

Now, let's consider a much different scenario. Instead of a publishing scenario, in which objects on the source server are mapped to their equivalent files on the destination server, consider instead a scenario in which a specific subweb or list item is migrated and you want to place it at a different location in in the destination hierarchy. This is a very common requirement, and you handle this by reparenting the object (or objects) on import.

Note that any time that you do not retain object identity, you must specify a new parent when you import the object. It does not matter if the destination site collection is the same site collection as the source, nor even if it is in the same database as the source site collection. It also does not matter if the destination site collection is in the same server farm or a different server farm as the source site collection.

If you export an item from a database without exporting its parent, the item becomes orphaned in the content migration package, but that is not necessarily a problem. A package can contain multiple orphaned objects.

Orphaned objects in the migration package are not a problem because the import method allows you to define a new parent for each of these orphaned objects. This is what is meant by "reparenting." However, objects that are exported with their parent objects keep their relationships during migration. So, for example, if you export Web A and Web B is a subweb of Web A, you can change only the parent of Web A. The parent of Web B remains Web A, because Web B remains a subweb of A.

There are two ways to reparent orphaned objects when importing. You can import all of your orphaned objects into the same subweb, or you can assign parent objects individually to each orphaned object.

Reparenting by Importing All Orphans to the Same Subweb

You can reparent your orphan objects by simply importing all of them into the same subweb. However, this works only if all orphan objects are destined for the same subweb. For example, this is the preferred method if you have exported two or more list or document library objects and you want to import them all into the same subweb. This works even if the export objects are from different source sites. Here is some sample code that demonstrates how to reparent orphan objects. Of particular note are the WebUrl and RetainObjectIdentityproperties.

SPImportSettings settings = new SPImportSettings(); 
settings.SiteUrl = "http://localhost:2001"; 
settings.WebUrl = "http://localhost:2001/MyDestinationWeb"; 
settings.FileLocation = @"c:\export"; 
settings.FileCompression = false; 
settings.RetainObjectIdentity = false; 

SPImport import = new SPImport(settings); 
import.Run();

In the preceding example, the WebUrl property defines the site (SPWeb) that becomes the new parent for all orphaned objects in the export package.

Note

You cannot use this method to reparent orphaned objects if the migration package contains orphaned documents; that is, a SharePoint site cannot become the parent of a document object. Only list or folder objects can be the parent object of document objects.

Note, too, that the default setting for the RetainObjectIdentity property is false. This is important to know because the false setting causes the assignment of new GUIDs to the orphaned objects, which is essential for reparenting them.

Reparenting by Assigning New Parent Objects Individually

Assigning new parents to orphaned objects individually is much more flexible than reparenting all orphan objects at the same time, but this approach also requires you to write more code. To assign a new parent to objects individually, you must intercept the import operation and assign a new parent to each orphaned object; this is done after the operation creates a list of all orphaned objects in the migration package. You can do this by implementing a custom event handler, as shown in the following code sample.

static void OnImportStarted(object sender, SPDeploymentEventArgs args) 
{ 
   SPSite site = new SPSite("http://localhost:2001"); 
   SPWeb web = site.RootWeb; 

   SPImportObjectCollection rootObjects = args.RootObjects; 
   foreach (SPImportObject io in rootObjects) 
   { 
      io.TargetParentUrl = web.Url; 
   } 

   web.dispose();
   site.dispose();
}

This approach uses the RootObject collection of the event arguments to aggregate all orphan objects and then reparent them. Actually, this is very similar to the process where you import all of the objects to the same subweb, such as the example where a specific site (SPWeb) is defined as the new parent of all included orphaned objects. However, notice how you can extend the logic in the event handler to, for example, assign different parents to different orphans based on object type, as shown in the following code sample.

static void OnImportStarted(object sender, SPDeploymentEventArgs args) 
{ 
   SPSite site = new SPSite("http://localhost:2001"); 
   SPWeb web = site.RootWeb; 
   SPList list = web.Lists["MyDocLib"]; 

   SPImportObjectCollection rootObjects = args.RootObjects; 
   foreach (SPImportObject io in rootObjects) 
   { 
      if (io.Type == SPDeploymentObjectType.ListItem) 
      { 
         io.TargetParentUrl = list.RootFolder.ServerRelativeUrl;
      } 
      if (io.Type == SPDeploymentObjectType.List) 
      { 
         io.TargetParentUrl = web.Url; 
      } 
      ... 
   } 
 
   web.dispose();
   site.dispose();
}

There is a great deal of flexibility here. In addition to reparenting based on the object type, you can instead look at the original TargetParentUrl, for example, to obtain the location of the source and then include that as part of your reparenting logic.

The code example below shows how to connect the event handler to the import operation.

static void ImportDocLibItem() 
{ 
   SPImportSettings settings = new SPImportSettings(); 
   settings.SiteUrl = "http://localhost:2001"; 
   settings.FileLocation = @"c:\deployment5"; 
   settings.FileCompression = false; 
   settings.RetainObjectIdentity = false; 

   SPImport import = new SPImport(settings); 

   EventHandler<SPDeploymentEventArgs> eventHandler = 
      new EventHandler<SPDeploymentEventArgs>(OnImportStarted); 
   import.Started += eventHandler; 

   import.Run(); 
}

Notice that you need to register the event handler with the import class before you start the import operation.

There are several additional event handlers that you can register and use during import; these are described in the Windows SharePoint Services 3.0 Software Development Kit (SDK) in the MSDN Library:

http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.deployment.spimport_events.aspx

Similar events can also be registered for export, if required:

http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.deployment.spexport_events.aspx

Content Types

Migration operations that use the export and import commands include your content type definition schema files in the export package. However, in cases where content type definitions maintain references to custom SharePoint Features, you must manually install and configure the feature for which the content type holds a reference on the destination computer. Features that are native to Windows SharePoint Services have their type definition references restored automatically.

When the import operation starts, you receive a warning message that alerts you by providing the identity of custom features that you need to recreate references for. You must resolve these references after completing the import.

For more information about content types, see Content Types. For more information about SharePoint Features, see Working with Features.

Creating Workflows

Workflows are not included in export packages, so when you initially set up a migration target, you must copy custom workflows to the destination server and reconfigure the workflow association table. This includes creating or restoring the workflow definitions files on the destination site.

You need to manually restore your custom workflows on the migration destination site only one time: when you initially set up your destination server. Subsequently, when performing a selective migration in a publishing scenario, it is recommended that you exclude workflows from the migration package.

For more information about managing workflows, see the following topics:

Migration Planning

It is very important that you plan your selective migration job in advance. When you structure your selective migrations, here are some key questions to ask that help clarify exactly what data you need to migrate:

  • What site objects need to be migrated?

  • How often should these objects be migrated?

  • Do some content objects need to be migrated on a different schedule than other objects?

  • Should some items be excluded from the migration?

  • What contingencies and unexpected scenarios could affect planning assumptions?

Most migration plans require that you set values on the export settings (SPExportSettings) object. Considerations that can affect your migration include versioning, security groups, and roles.

Versions

Specify how the migration operation manages version information by using the IncludeVersions property on the SPExportSettings object.

Decide whether your migration is going to export only the latest major version of the specified file (this is the default), or whether instead to export only the current version, all versions, or only the last major and its minor versions. Following are the allowable values for the IncludeVersions property.

Values allowed with IncludeVersions

Description

All

Exports all existing versions of selected file.

CurrentVersion

Exports only the most recent version of selected files.

LastMajor

Default value. Exports only the last major version of selected files.

LastMajorAndMinor

Exports the last major version and its minor versions.

Your application requirements dictate which value is appropriate. However, if the migration is on a recurring schedule, and if performance is a consideration, the best option may be CurrentVersion. Setting the value to All causes a performance drag.

Security Groups and Roles

It is generally not necessary, to include security group and roles data in a selective migration scenario. Although migrating this data during the initial setup and migration of the destination site is appropriate, exporting this data when running selective migrations slows the migration.

The exception, of course, is when changes to security data are detected. Your application logic should detect this and configure this property appropriately. Note that the IncludeSecurity property calls into the SPIncludeSecurity enumeration, which provides three allowable values. The default is None, which specifies that no security data is migrated.

Values allowed with SPIncludeSecurity

Description

All

Specifies the export of user memberships and role assignments of roles that are standard with the product, such as Web Designer, plus any custom roles that extend from the standard roles. The access control list (ACL) for each object is exported to the migration package, as well as the user information that is defined in the Directory Access Protocol (DAP) or the Lightweight Directory Access Protocol (LDAP) servers.

None

Default value. No user role or security group information is exported.

WssOnly

Specifies the export of user memberships and role assignments such as standard roles like Web Designer, plus any custom roles that extend from the standard 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.

Planning for Performance

Several of the export and import settings can potentially affect the performance of your migration operations. Although fine-tuning for performance might not provide large performance gains, in the case of very large migrations you might realize significant improvements by being aware of the following information.

  • By migrating uncompressed files, you can potentially improve the performance of your export and import oprations by roughly thirty percent. File compression is enabled by default, so you need to explicitly change the FileCompression property on both SPExportSettings and SPImportSettings (both derived from the FileCompression property of the SPDeploymentSettingsclass).

  • Setting SuppressAfterEvents on the SPImportSettings object to true (the default is false) causes the import operation to ignore After events. This can provide a minor performance gain.

  • Setting the IncludeVersions property to false on the SPExportSettings object also provides a minor performance gain. There is also a performance gain by setting the SPImportSettings object property to false, but by comparison, it is less of a performance gain than setting the same property on the SPExportSettings object.

  • Setting the IncludeSecurity property to false on the SPExportSettings object provides a performance gain. Again, there is less of a performance gain by setting the same property on the SPExportSettings object. Note, however, that you should never set this property to false when user data is exported (although this is generally not the case during selective migrations).

  • During selective migrations, a large part of performance potential is consumed by the process of selecting export objects. If your export includes a large number of export objects, you will see a decline in performance.

  • You can also obtain minor performance gains if on import you set the CommandLineVerbose and the LogFilePath properties to false. This is particularly true on the SPImportSettings object.

Exporting Content

The flowchart in Figure 1 illustrates the conceptual flow of a typical export operation that uses 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.

Figure 1. Flowchart of full and selective export operations

Notice that before running selective migrations, you must run a full migration to set up your destination server. When running this preparatory full migration, you must set the RetainObjectIdentityproperty on the SPImportSettings object to true.

Export Settings Properties (SPExportSettings)

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 members that specialize in either export or import operations.

SPExportSettings

Properties of the SPExportSettings class, plus those of the base class, fall into four groups:

  • Required export settings: Property settings that are required for export.

  • Important export settings: Property settings that are very important and that you should consider using in your export planning.

  • Selective migration-related export settings: Property settings that are related to specific selective migration export operations.

  • Minor export settings: Minor or rarely used property settings.

Required Export Settings

Property

Description

ExportObjects

Retrieves the export object collection object (SPExportObjectCollection).

BaseFileName (inherited from 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 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.

FileLocation (inherited from 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.

Important Export Settings

Property

Description

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.

CommandLineVerbose (inherited from SPDeploymentSettings)

Retrieves or sets a Boolean value that specifies whether you want migration information to be sent to a command-line console. The default value is false.

FileCompression (inherited from 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; this means that the content migration package is compressed by default.

IncludeSecurity (inherited from SPDeploymentSettings)

Retrieves or sets an IncludeSecurity enumeration value that specifies the amount of user security roles and role membership data to include in the migration package. The enumeration provides three values:

  • All: Specifies the export of user memberships and role assignments such as Web Designer, plus any custom roles that extend from the built-in 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.

LogFilePath (inherited from 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

Property

Description

CurrentChangeToken

Retrieves a change token (string) that is found in the export operation change log. During a selective migration, the current change token specifies a starting point when retrieving 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 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 instead an incremental, or a selective migration that migrates only 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 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 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

Property

Description

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.

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 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 default 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 can 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 that the size of the migration package has no limit.

When you run the export operation, and if the compressed export file exceeds the specified maximum, 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 use this property only when testing your export operation, or if you need to troubleshoot problems with the export, because 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 specifies 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) by using the APIs in the Microsoft.SharePoint.Deployment namespace. The first uses the SPExportSettings object; 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 just set, and then we start the export operation by calling the 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 the preceding sections. However, there are a few important points to note about some of these properties.

Property

Description

SiteUrl

Provides 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

Setting the ExportMethod property to ExportAll specifies that you are exporting the entire site collection. Alternatively, when performing a selective migration, change this value to ExportChanges. In addition, you must provide an export change token when performing a selective migration.

FileLocation

Provides a path to the folder where the operation stores the exported content. This value should point to be an empty directory on the destination computer. If the directory does not exist it is 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

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 compress your export file only when necessary—for example, when exporting archival files or when moving an entire site collection to a new computer. If you are performing a selective migration, or a copy/move operation, for example, you can increase performance by electing not to compress the files.

CommandVerbose

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 you add the [T.Microsoft.SharePoint.SPSite] object for your site collection to the collection, SPExportObjectCollection. This approach provides the same result as the previous approach, where the SPSite object was implicitly selected because we did not explicitly select any objects for export.

[C#]

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.

Property

Description

SPExportObject.Id

Provide the GUID of the object intended for export.

SPExportObject.Type

Specifies the type of the object to be exported. Six SharePoint object types are available:

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

Importing Content

The flowchart in Figure 2 illustrates the conceptual flow of a typical import operation that uses the migration APIs in the Deployment namespace. On the surface, importing content is simply the reverse of the export. But the import operation has a more complex flow and a greater number of decision points.

Figure 2. Flowchart of full and selective import operations

When specifying your import settings (SPImportSettings), ensure that you match the corresponding export settings (SPExportSettings). For example, if the FileCompression property on the SPExportSettings object is set to true, the corresponding FileCompression property on the SPImportSettings object must also be set to true.

The process flow presents decision points at which the flow branches. The first decision point is whether to retain the identity of your objects. This property setting determines whether the import object is located by object GUID (if retaining object identity) or by URL.

The next decision point pertains to reparenting. If the object is a top-level object in the hierarchy, and if you are not retaining object identity, you must reassign a parent object. If, however, this is not a top-level object and you are not retaining object identity, reparenting is not required.

If the operation fails to locate the import object, a new one is created. However, if the object is located, and if you simply moving the object (as in a copy/move operation), the operation assigns the object a new URL. If this is an update (a file update, for example), the operation keeps the original URL.

Import Settings Properties

The SPExportSettings and SPImportSettingsare derived from the SPDeploymentSettings base class. Its members, then, are inherited by both of the these derived classes, and the SPImportSettings class contains specialized import-related members.

SPImportSettings

Properties on SPImportSettings class, plus those of the base class, fall into four groups:

  • Required import settings: Property settings required for import.

  • Important import settings: Property settings of importance and that you should consider in your import planning.

  • Specific import settings: Property settings that are related to specific import operations in a selective migration.

  • Minor import settings: Minor or rarely used property settings.

Required Import Settings

Property

Description

WebId

Sets or retrieves a GUID that identifies the import destination site.

WebUrl

Sets or retrieves a URL that locates the import destination site.

BaseFileName (inherited from 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.

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 SPDeploymentSettings)

Sets or retrieves the URL of the destination site collection on import. The value is an absolute URL to the site. This value is provided in the siteUrl parameter of the SPDeploymentSettings class constructor.

FileLocation (inherited from SPDeploymentSettings)

Sets or retrieves the file path and directory location where the content migration package (or packages) are placed on the import destination. This value is provided in the fileLocation parameter of the SPDeploymentSettings class constructor.

Important Import Settings

Property

Description

UserInfoDateTime

Sets or retrieves a value from the SPImportUserInfoDateTimeOption enumeration that specifies the level of user information to retain on import. Following are the allowable values:

  • ImportAll: Retains all of the original author and editor information, including date/time stamp and user lookup values.

  • None: (Default) Replaces the author and editor data with the System Account; creates a current (time of import) date/time stamp, and replaces user lookup values with an empty string ("").

  • ReplaceUserWithSystemAccount: Retains the original date/time stamp, but replaces the author and editor data with the System Account, and replaces user lookup values with an empty string ("").

  • The default falue is None.

UpdateVersions

Sets or retrieves a value from the SPUpdateVersions enumeration that specifies the handling of versioning information on import:

  • Append: Appends versioned items during import.

  • Overwrite: Deletes the existing item during import, then reinserts the imported version.

  • Ignore: Ignores versioning.

CommandLineVerbose (inherited from SPDeploymentSettings)

Retrieves or sets a Boolean value that specifies whether you want migration information outputted to a command line console. The default value is false.

FileCompression (inherited from 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.

The import setting for this property must match the value set on the FileCompression property.

IncludeSecurity (inherited from 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 provides three options: All, None, and WssOnly. The value selected must match the value that is provided on the IncludeSecurity property.

LogFilePath (inherited from SPDeploymentSettings)

Retrieves or sets a value that specifies the fully qualified path to the log file for the content migration operation.

Selective Migration–Specific Import Settings

Property

Description

RetainObjectIdentity

Sets or retrieves a Boolean value that specifies whether to retain identifying object GUIDs during import. Setting this to true directs the import to retain object GUIDs; the default value is false.

RetainObjectIdentity is an important property setting to be aware of when performing a selective migration, because the core concept is importing updated versions of existing files. The only way for updates to be verified as the latest update at the destination site is through a process that compares object identity using object GUIDs.

Because databases do not permit duplicate GUIDs, you should be careful when implementing the RetainObjectIdentity property. It is only useful in specific selective migration scenarios. Furthermore, to support field deletion (which deletes previous versions of items at the export source when the same content at the import destination is updated or deleted), this value must be set to true. Note, too, that to support selective migrations you must set the ExportMethod property to a field value of ExportChanges.

Minor Import Settings

Property

Description

IgnoreWebParts

Sets or retrieves a Boolean value that determines whether the import operation ignores Web Parts that are associated with a file. Set to true to disable importing Web Parts; the default value is false.

Note that this property is used primarily to support the Variations feature in Microsoft Office SharePoint Server 2007.

SuppressAfterEvents

Sets or retrieves a Boolean value that determines whether the migration operation ignores After events that are fired when files or list items are created or modified. Set this property to true to ignore After events; the default value is false.

Suppressing the handling of After events can increase performance slightly during import. Furthermore, even if performance is not a concern, setting this value to true helps avoid potential problems resulting from event handler errors.

HaltOnWarning (inherited from SPDeploymentSettings)

Sets or retrieves a Boolean value that specifies whether to suspend the migration operation when a warning is encountered. The default setting is false, which causes warnings to be ignored and the migration continued.

HaltOnNonfatalError (inherited from SPDeploymentSettings)

Sets or retrieves a Boolean value that specifies whether to suspend the migration when an error (nonfatal) is encountered. The default setting is false, which causes nonfatal errors to be ignored and the migration continued.

Conclusion

The object model provided in the SharePoint.Deployment namespace, in addition to tools provided with the SDK, provide an enormous degree of flexibility to support an extensive range of content migration scenarios.

Additional Resources

Content Migration Overview

Using Stsadm.exe to Migrate Site Data

Content Types

Working with Features