Around the time work started on a long whitepaper about migrating content files from SharePoint server “A” to SharePoint server “B” using the migration and deployment APIs in the Microsoft.SharePoint.Deployment namespace, I came across a series of blog posts by Stefan Goβner that covered the subject matter in detail. Many of you have probably seen Stefan’s work: Deep Dive into the SharePoint Content Deployment and Migration API, Parts 1-5.
I contacted Stefan and he agreed to collaborate. He’s allowed me to use some of his code examples, and to expand on some of his points. Additionally, I’ve collaborated with the feature PM and lead developer on the migration/deployment APIs here at Microsoft, Patrick Simek, so the whitepaper treats the subject quite a bit more broadly than does Stefan’s blog posts.
I’ll chunk this article up into segments for posting to this blog. Comments are DEFINITELY welcome. I’ll be converting much of the content of this article (and these posts) into Help content in the SharePoint SDK documentation, so anything that helps to improve the quality of the content is highly desired. Here’s the first section:
The ABCs of Content Migration (Post 1)
Many scenarios require moving content from one SharePoint site to another. When the scenario calls for a full migration (that is, moving the entire contents of a SharePoint site or site collection), the task is relatively simple. Typically, you use either of two main approaches:
Use the export and import operations in the Stsadm.exe utility to migrate data from one site to another.
Alternatively, use SOAP calls to the Sites.ExportWeb and Sites.ImportWeb methods that are implemented on the Sites Web service to migrate data.
However, both of these methods have limitations. Both limit you to migrating only a full SharePoint site, or site collection. In addition, neither 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.
Note Selective migration operates when there is an established source and a recognized destination for a known quantity of content. That is, selective migration requires that a full migration was initially performed so that the destination is a mirror image of the source.
Selective migration applies, typically, to content that needs to be migrated from server to server based on factors such as content version (current vs. future), time stamp, and content state (approved vs. in review, for example). Selection criteria provides a high degree of granularity 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.
You can have any number of .cmp files in a migration operation, and you can also have multiple destinations. However, the objects contained in a given content migration package (.cmp) file must originate from a single site collection.
Typical 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. This list is only a high-level, generalized summary of supported migration scenarios. The Deployment APIs are sufficiently rich to support any number of special circumstances that you might face.
Export an entire site collection (that is, do a full migration).
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 a SharePoint list or document library, or even of a specific folder inside a document library.
Export a single list item or document from a document library. This provides the extreme migration granularity that enables so much flexibility.
Export object dependencies like images or attached files.
Generate your export file as a compressed export (.cmp) package, or as uncompressed files.
Throttle exports by specifying a maximum size for the compressed export package file (multiple export files will be created if required).
Support incremental exports of items that are selected for export based on change tokens. This allows you to automate exporting all items that have been created, changed, or deleted after the timestamp specified in the change token.
Import the exported content with or without preserving object identity—that is, you can configure objects in the export package to retain their object GUID. This is a requirement for selective migrations.
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 is known as reparenting.
Do link fixup during import.
In my next post we’ll continue with this high-altitude look at the subject of content migration. There, we’ll talk extensively about key concepts in the migration/deployment feature area.