How to: Customize Deployment for Disconnected Scenarios in SharePoint Server 2010 (ECM)

Applies to: SharePoint Server 2010

Content deployment works well when a clear connection between the source farm and the destination farm is always available. However, a reliable, functional connection between a source authoring farm and a destination production farm is not always available. For example, geographic barriers, firewalls that prevent access, or network outages are all situations in which using a network connection to transport an export package to a destination production farm is not reliable. In these situations, Microsoft recommends that you work with the Microsoft SharePoint Server 2010 object model and the SharePoint Foundation Content Migration API to programmatically complete the export and import steps of content migration and find an alternative way to transport the export package to the destination production farm and then run the custom import code.

As described in Deploying Content Between Servers in SharePoint Server 2010 (ECM), every content deployment comprises three steps: export, transport, and import. In this scenario, transport is handled manually, not programmatically. For example, you might transport the exported content package on portable media or use an FTP client to upload the data to an independent file share from which you can import.

To export a content package by using the Content Migration API

  1. Call the Content Migration API with the options you want to specify.

  2. Store a change token.

  3. The application runs the export, checks for exceptions, and reports exceptions as needed. If the run is successful, the application creates the exported package with the name provided and stores it in the location provided.

Note

After export is complete and you create a content package, you can transport exported package by using FTP, portable media, and so forth. After you transport the data to a file location that the import process can access, you can begin importing.

To import a content package by using the Content Migration API

  1. Find the file you created by using the object model during export. If you are using the code example provided, the file name is export.cmp.

  2. Run the import code. The import code does the following:

    1. Creates an SPImportSettings object with properties set as defined in the code.

    2. Creates a new SPImport object and manages pre-import and post-import change tokens, content versioning, cache settings, and scheduling for newly deployed content.

    Note

    For performance reasons, SharePoint Server 2010 doesn't call event receivers by default. By default, listeners do not fire when content deployment creates content. However, if you are using third-party applications or custom code that requires event receivers to be fired during import, you can set the SuppressAfterEvents property to false. When this flag is set, you may experience significant performance loss, but all requirements specified in the import are received.

    Note

    You call the Content Migration API on the source server and set specific options, such as the RetainObjectIdentity property, to true.

Example

To help you use the SharePoint Foundation Content Migration API with the SharePoint Server 2010 content deployment feature, this topic includes a code sample that uses the Content Migration API with SharePoint Server 2010 content deployment. The sample shows how the content deployment feature interacts with the Content Migration API to create an export; concepts and syntax required when using the Content Migration API to complete the export, import, and path; and job definition and execution steps of SharePoint Server 2010 content deployment.

The sample code is divided into two smaller applications: an export application and an import application.

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.SharePoint.Deployment;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Publishing;
using Microsoft.SharePoint.Publishing.Administration;

/* Note: Before running this sample code, or any custom deployment solution, disable auto-spawning for the Variations feature
 * on your source site if it is enabled.
 **/
namespace CustomDeployment
{
    class Program
    {
        private static SavedCacheSettings savedCacheSettings;
        private static string sourceUrl = "http://samplesource/";
        private static string destinationUrl = "http://sampledestination/";
        private static string destinationRootWebUrl;

        static void Main(string[] args)
        {
            // This region defines content deployment export settings,
            // runs the export, and catches an exceptions during export
            // and outputs them.
            #region Export

            try
            {
                SPExportSettings exportSettings = new SPExportSettings();
                // Turn on extra output for testing
                exportSettings.CommandLineVerbose = true; 
                // The name of the file targeted by the export
                exportSettings.BaseFileName = "export.cmp"; 
                // The directory on the file system in which
                // to put the exported package
                exportSettings.FileLocation = @"%temp%"; 
                // If the file exists, overwrite it
                exportSettings.OverwriteExistingDataFile = true;
                // Export all security settings; change this if needed
                exportSettings.IncludeSecurity = SPIncludeSecurity.All;
                // The URL of the site being exported
                exportSettings.SiteUrl = sourceUrl;
                // The last major and minor versions
                exportSettings.IncludeVersions = SPIncludeVersions.LastMajorAndMinor;
                // Compress the exported file
                exportSettings.FileCompression = true; 
                // Create a new export object with the correct settings
                SPExport export = new SPExport(exportSettings); 
                // Optionally add event handlers to the export
                // object for:
                    // Started
                    // ProgressUpdated
                    // Completed
                    // Canceled
                    // Error
                    // Compressing
                // Run the export
                   export.Run(); 
                   }
                // Catch any exceptions during export and output them
                   catch (Exception ex) 
                   {
                   Console.Error.Write(ex.ToString());
                   throw;
                }
            #endregion //Export

            // This region defines import settings, creates a new
            // SPImportObject with those settings, manages versioning
            // and caching, and applies appropriate conditions if the
            // object is a Web site or root Web site
            #region Import
            try
            {
                SPImportSettings importSettings = new SPImportSettings();
                // Turn on extra output for testing
                importSettings.CommandLineVerbose = true; 
                // IMPORTANT: retains object IDs
                importSettings.RetainObjectIdentity = true; 
                // The directory of the file being imported
                importSettings.FileLocation = @"%temp%"; 
                // The name of the file being imported
                importSettings.BaseFileName = "export.cmp";
                // The URL of the site into which content is being imported
                importSettings.SiteUrl = destinationUrl; 
                //Import all the security settings from the package
                importSettings.IncludeSecurity = SPIncludeSecurity.All;
                // Retain author name during import; change if needed
                importSettings.UserInfoDateTime = SPImportUserInfoDateTimeOption.ImportAll;
                // Don't fire event receivers during import; 
                // change if needed
                importSettings.SuppressAfterEvents = true;
                // Add new versions when importing items that 
                // already exist
                importSettings.UpdateVersions = SPUpdateVersions.Append; 
                // Create a new import object with specified settings
                SPImport import = new SPImport(importSettings); 
                // Turn down caching during the import
                  SiteCacheSettingsWriter.UpdateCacheSettingsDuringImport(importSettings.SiteUrl, true); 
                // Save the cache settings to restore after 
                // the import finishes
                savedCacheSettings = SiteCacheSettingsWriter.SaveCacheSettingsBeforeImport(importSettings.SiteUrl);
                // Change tokens for pre-import and post-import
                SPChangeToken startChangeToken, endChangeToken; 
                using (SPSite destinationSite = new SPSite(importSettings.SiteUrl))
                {
                    // Get the change token from the destination site
                    startChangeToken = destinationSite.CurrentChangeToken; 
                    // Save the root Web URL for future use
                    destinationRootWebUrl = destinationSite.RootWeb.ServerRelativeUrl; 
                }

                import.ObjectImported += new EventHandler<SPObjectImportedEventArgs>(import_ObjectImported);
                // Optionally add event handlers to the 
                // import object for:
                    // Started
                    // ProgressUpdated
                    // Completed
                    // Cancelled
                    // Error
                    // Uncompressing

                // Run the import
                import.Run();

                using (SPSite destinationSite = new SPSite(importSettings.SiteUrl))
                {
                    // Get the change token from the
                    // destination site AFTER import
                    endChangeToken = destinationSite.CurrentChangeToken; 

                    // Enable scheduling of the items just deployed
                    ScheduledItem.EnableSchedulingOnDeployedItems(destinationSite, startChangeToken, endChangeToken, "Succeeded");
                }
            }
            // Catch any exceptions during import and output them
            catch (Exception ex) 
            {
                Console.Error.Write(ex.ToString());
                throw;
            }
            finally
            {
                // Update the cache settings because import is done
                SiteCacheSettingsWriter.UpdateCacheSettingsDuringImport(destinationUrl, false);
            }
            #endregion
        }

        private static void import_ObjectImported(object sender, SPObjectImportedEventArgs e)
        {
            // Is the imported object a Web site?
            if ((e != null) && (e.Type == SPDeploymentObjectType.Web))
            {
                // Is the imported object the root Web site?
                if (string.Compare(e.TargetUrl, destinationRootWebUrl, StringComparison.OrdinalIgnoreCase) == 0)
                {
                    // The root Web site is being imported, so restore
                    // the cache-related root Web site properties.
                    SiteCacheSettingsWriter.RestoreCacheSettingsOnImport(destinationUrl, savedCacheSettings);
                }
            }

            return;
        }
    }
}
Imports System
Imports System.Collections.Generic
Imports System.Text
Imports Microsoft.SharePoint.Deployment
Imports Microsoft.SharePoint
Imports Microsoft.SharePoint.Publishing
Imports Microsoft.SharePoint.Publishing.Administration

' Note: Before running this sample code, or any custom deployment solution, disable auto-spawning for the Variations feature
' * on your source site if it is enabled.
' *
Namespace CustomDeployment
    Friend Class Program
        Private Shared savedCacheSettings As SavedCacheSettings
        Private Shared sourceUrl As String = "http://samplesource/"
        Private Shared destinationUrl As String = "http://sampledestination/"
        Private Shared destinationRootWebUrl As String

        Shared Sub Main(ByVal args() As String)
            ' This region defines content deployment export settings,
            ' runs the export, and catches an exceptions during export
            ' and outputs them.
'            #Region "Export"

            Try
                Dim exportSettings As New SPExportSettings()
                ' Turn on extra output for testing
                exportSettings.CommandLineVerbose = True
                ' The name of the file targeted by the export
                exportSettings.BaseFileName = "export.cmp"
                ' The directory on the file system in which
                ' to put the exported package
                exportSettings.FileLocation = "%temp%"
                ' If the file exists, overwrite it
                exportSettings.OverwriteExistingDataFile = True
                ' Export all security settings; change this if needed
                exportSettings.IncludeSecurity = SPIncludeSecurity.All
                ' The URL of the site being exported
                exportSettings.SiteUrl = sourceUrl
                ' The last major and minor versions
                exportSettings.IncludeVersions = SPIncludeVersions.LastMajorAndMinor
                ' Compress the exported file
                exportSettings.FileCompression = True
                ' Create a new export object with the correct settings
                Dim export As New SPExport(exportSettings)
                ' Optionally add event handlers to the export
                ' object for:
                    ' Started
                    ' ProgressUpdated
                    ' Completed
                    ' Canceled
                    ' Error
                    ' Compressing
                ' Run the export
                   export.Run()
                ' Catch any exceptions during export and output them
                   Catch ex As Exception
                   Console.Error.Write(ex.ToString())
                   Throw
                   End Try
'            #End Region 'Export

            ' This region defines import settings, creates a new
            ' SPImportObject with those settings, manages versioning
            ' and caching, and applies appropriate conditions if the
            ' object is a Web site or root Web site
'            #Region "Import"
            Try
                Dim importSettings As New SPImportSettings()
                ' Turn on extra output for testing
                importSettings.CommandLineVerbose = True
                ' IMPORTANT: retains object IDs
                importSettings.RetainObjectIdentity = True
                ' The directory of the file being imported
                importSettings.FileLocation = "%temp%"
                ' The name of the file being imported
                importSettings.BaseFileName = "export.cmp"
                ' The URL of the site into which content is being imported
                importSettings.SiteUrl = destinationUrl
                'Import all the security settings from the package
                importSettings.IncludeSecurity = SPIncludeSecurity.All
                ' Retain author name during import; change if needed
                importSettings.UserInfoDateTime = SPImportUserInfoDateTimeOption.ImportAll
                ' Don't fire event receivers during import; 
                ' change if needed
                importSettings.SuppressAfterEvents = True
                ' Add new versions when importing items that 
                ' already exist
                importSettings.UpdateVersions = SPUpdateVersions.Append
                ' Create a new import object with specified settings
                Dim import As New SPImport(importSettings)
                ' Turn down caching during the import
                  SiteCacheSettingsWriter.UpdateCacheSettingsDuringImport(importSettings.SiteUrl, True)
                ' Save the cache settings to restore after 
                ' the import finishes
                savedCacheSettings = SiteCacheSettingsWriter.SaveCacheSettingsBeforeImport(importSettings.SiteUrl)
                ' Change tokens for pre-import and post-import
                Dim startChangeToken, endChangeToken As SPChangeToken
                Using destinationSite As New SPSite(importSettings.SiteUrl)
                    ' Get the change token from the destination site
                    startChangeToken = destinationSite.CurrentChangeToken
                    ' Save the root Web URL for future use
                    destinationRootWebUrl = destinationSite.RootWeb.ServerRelativeUrl
                End Using

                AddHandler import.ObjectImported, AddressOf import_ObjectImported
                ' Optionally add event handlers to the 
                ' import object for:
                    ' Started
                    ' ProgressUpdated
                    ' Completed
                    ' Cancelled
                    ' Error
                    ' Uncompressing

                ' Run the import
                import.Run()

                Using destinationSite As New SPSite(importSettings.SiteUrl)
                    ' Get the change token from the
                    ' destination site AFTER import
                    endChangeToken = destinationSite.CurrentChangeToken

                    ' Enable scheduling of the items just deployed
                    ScheduledItem.EnableSchedulingOnDeployedItems(destinationSite, startChangeToken, endChangeToken, "Succeeded")
                End Using
            ' Catch any exceptions during import and output them
            Catch ex As Exception
                Console.Error.Write(ex.ToString())
                Throw
            Finally
                ' Update the cache settings because import is done
                SiteCacheSettingsWriter.UpdateCacheSettingsDuringImport(destinationUrl, False)
            End Try
'            #End Region
        End Sub

        Private Shared Sub import_ObjectImported(ByVal sender As Object, ByVal e As SPObjectImportedEventArgs)
            ' Is the imported object a Web site?
            If (e IsNot Nothing) AndAlso (e.Type = SPDeploymentObjectType.Web) Then
                ' Is the imported object the root Web site?
                If String.Compare(e.TargetUrl, destinationRootWebUrl, StringComparison.OrdinalIgnoreCase) = 0 Then
                    ' The root Web site is being imported, so restore
                    ' the cache-related root Web site properties.
                    SiteCacheSettingsWriter.RestoreCacheSettingsOnImport(destinationUrl, savedCacheSettings)
                End If
            End If

            Return
        End Sub
    End Class
End Namespace

See Also

Tasks

How to: Deploy Content Between Servers in SharePoint Server 2010 (ECM)

Reference

Web

Concepts

Deploying Content Between Servers in SharePoint Server 2010 (ECM)