SharePoint 2010 : The SharePoint Object Model (part 2) - Export, Import, and Associated Types & Site Collection Backup and Restore

Export, Import, and Associated Types

Catastrophic backup and restore types aren’t the only options available to you when you’re trying to capture SharePoint data programmatically. Export and import types are also available, but they operate in a significantly different fashion.

The Content Deployment API

SharePoint’s Content Deployment API, also known as the PRIME API (internally at Microsoft), offers another set of tools and approaches for preserving and migrating SharePoint content and structure. The bulk of the Content Deployment API types live in the Microsoft.SharePoint. Deployment namespace. The UML shown in Figure 3 represents the key types within the namespace:

Figure 3. Relationships between key Content Deployment types.

Out of the box, the SharePoint platform leverages the Content Deployment API in different ways and areas. Here are just a few:

• PowerShell. Both the Export-SPWeb and Import-SPWeb cmdlets leverage the Content Deployment API to carry out their export and import operations.

• SharePoint Server Content Deployment. Available as a feature within SharePoint Server (not SharePoint Foundation), Content Deployment permits administrators to define deployment paths (sources and destinations) and jobs (scheduled executions) for the movement of site content from one site collection to another. This is commonly used in publishing scenarios to push content from an authoring farm to a production farm.

• Central Administration Granular Backup. The ability to export site collections, sites, and lists from within the Central Administration site relies on the Content Deployment API.

As implied by the descriptions thus far, the Content Deployment API does not operate from the classic perspective of backup and restore; rather, the content deployment classes approach site persistence with the goal of copying from one site and importing into (or merging with) another. It is easier to think of backup and restore as a cloning process: that which is restored matches that which was backed up. That isn’t the case with the Content Deployment API. Depending on how an export and import are run, how associated dependencies are handled, whether or not content already exists in the destination site, and so on, the results on the import side of an export/import operation set may differ significantly from the export source. This tends to make the Content Deployment API less suited to full-fidelity backups and more useful for exporting portions of a site, merging content on import, and more.

For basic export and import functionality, though, the Content Deployment API is relatively easy to use. An example demonstrating the export of a single SharePoint site (that is, an SPWeb) is shown in Listing 2.

Listing 2.

public static void ExecuteSiteExport()
{
  // Establish values to cover the basics of the export operation that is going
  // to be performed. The site and location variables are fairly self-explanatory.
  // Because content exports can result in the creation of more than one file, the
  // current variable value (below) may yield FreshNewsExport.cmp, FreshNewsEmport2.cmp,
  // FreshNewsExport3.cmp, etc., series depending on how much content exists for export.
  Uri siteToExport = new Uri("http://spdev:18380/freshnews");
  String exportLocation = @"\\BackupHost\SPSiteExports\";
  String exportFilenameBase = @"FreshNewsExport";

  // The SPExportSettings object defines the export operation to perform. You can exercise
  // a great deal of control over the export operation with the SPExportSettings'
  // collection of properties.
  SPExportSettings baseSettings = new SPExportSettings(siteToExport, exportLocation,
exportFilenameBase);
  baseSettings.ExportMethod = SPExportMethodType.ExportAll;
  baseSettings.FileCompression = true;
  baseSettings.FileMaxSize = 256;
  baseSettings.IncludeSecurity = SPIncludeSecurity.All;
  baseSettings.IncludeVersions = SPIncludeVersions.All;
  // SPExport actually carries out the export operation. The type raises a number of
  // events that can be tapped, if desired, to respond to export changes and progress
  // notifications. Because SPExport implements IDisposable, it needs to be disposed of
  // properly with either a using block (as seen below) or with an explicit Dispose call.
  using (SPExport exporter = new SPExport(baseSettings))
  {
    exporter.Run();
  }
}


					  

The result of running the code shown in Listing 2 is a single FreshNewsExport.cmp file at the selected export location provided the content in the http://spdev:18380/freshnews site is less than roughly 256MB following compression. The FileMaxSize property defines how big each .cmp file is allowed to get before the file is closed and a new one is opened for export. If the FileMaxSize property were assigned a value of 32 and a total of 100MB of content (post-compression) existed in the site to be exported, approximately three files would be created at the export location: FreshNewsExport.cmp, FreshNewsExport2.cmp, and FreshNewsExport3.cmp. “Approximately” is specified because SharePoint’s ability to break an export into chunks of the desired size depends on the content that’s actually going into the files. The total number of files and their size can vary from export to export.

You can leverage the Content Deployment API in other ways as well. You can use it to execute incremental exports, support path updating on imports, export with compression to produce loose file sets, and more. In specific situations, it may be of greater use and application than the catastrophic backup and restore types of the Microsoft.SharePoint.Administration. Backup namespace.

You can use exports that are created using the types in the Microsoft. SharePoint.Deployment namespace with the Import-SPWeb PowerShell cmdlet without issue. You can import the site collection, site, and list exports that you generate using Central Administrations granular backup capabilities into a site using types that reside within the Microsoft. SharePoint.Deployment namespace. This also holds true for imports that are generated using the Export-SPWeb PowerShell cmdlet.

Site Collection Backup and Restore

Thus far you have been introduced to two different approaches that the SharePoint object model offers for data capture and protection. At one end of the spectrum sits the catastrophic backup and restore capabilities that are provided by types that reside primarily within the Microsoft. SharePoint.Administration.Backup namespace. At the other end of the spectrum are the content duplication and migration functions that are exposed by the types in the Microsoft. SharePoint.Deployment namespace. Sitting somewhere in between both of these is the SPSiteCollection type.

The Somewhat Unusual Case of the SPSiteCollection Type

The Backup and Restore methods of the SPSiteCollection type are responsible for carrying out the site collection backup and restore operations you might expect them to. Microsoft considers these operations part of the SharePoint granular backup and export architecture, but they don’t quite fit the modus operandi of the other export and import types in the Deployment namespace. In fact, the SPSiteCollection type resides within the Microsoft. SharePoint.Administration namespace and doesn’t interact at all with the Content Deployment API.

At the same time, the SPSiteCollection type doesn’t interact with the catastrophic backup and restore types in the Microsoft.SharePoint.Administration.Backup namespace. This lack of coupling to catastrophic backup and restore is further evidenced by the fact that the SPSite-Collection type doesn’t implement the IBackupRestore interface, which is the hallmark of a content component.

If you dig deep enough into the SharePoint object model, you find that the SPSiteCollection Backup and Restore methods drill through to the BackupSite and RestoreSite methods on SharePoint’s core SPRequest type. The BackupSite and RestoreSite methods are basically nothing but thin wrappers around external calls to SharePoint’s legacy component object model (COM) infrastructure, meaning the actual site collection backup and restore operations are handled in opaque (and basically untouchable) unmanaged code.

Leveraging Site Collection Backup and Restore

Although the underpinnings of the site collection backup and restore operations are based in COM, you can still employ these operations through the SPSiteCollection type. In fact, site collection backups and restores are the easiest of all backup and restore operations to run. Each only involves a single method call and no dependent objects, as demonstrated in Listing 3.

Listing 3.

public static void ExecuteSiteCollectionBackup()
{
  // Establish the variables that are used to drive the backup operation. The
  // variables are assigned directly here, but a more practical application of
  // the Backup method involves values being passed into the method.
  String backupFilename = @"\\BackupHost\SPSiteBackups\SampleSiteBackup.bak";
  String siteCollectionUrl = @"http://spdev:18380";
  Boolean overwriteIfExisting = true;

  // The Web application that hosts the site collection of interest isn't known
  // directly, so it is looked up. The code then uses that Web application's
  // SPSiteCollection (from the Sites property) for the Backup operation.
  SPWebApplication hostingWebApp = SPWebApplication.Lookup(new Uri(siteCollectionUrl));
  SPSiteCollection associatedSPSites = hostingWebApp.Sites;

  // Execute the actual backup operation to generate the backup file.
  associatedSPSites.Backup(siteCollectionUrl, backupFilename, overwriteIfExisting);
}


					  

Restoring a site collection backed up in this fashion is as simple as changing the Backup method call to a Restore method call. Even the method parameters and their ordering remain the same between calls.

Backups created in this fashion are written out as a single file, which further drives home the differences between backups performed in this fashion and those that are performed through the Microsoft.SharePoint.Administration.Backup namespace; specifically, no backup and restore history is maintained for operations carried out through the SPSiteCollection type. Logging of backup and restore operations is not performed, either, making use of the SPSite-Collection type more of a lightweight approach to backup and restore operations.

Use of the SPSiteCollection.Backup generates the same type of file output as that which is generated when running a site collection backup from Central Administration or a site collection backup using the SharePoint Backup-SPSite PowerShell cmdlet. You can restore site collections generated using the code in Listing 11.3 with the Restore-SPSite cmdlet. By the same token, you can restore site collection backups that are created using Central Administration’s site collection backup operation or the Backup-SPSite PowerShell cmdlet with the SPSiteCollection.Restore method.

As an example of where you could leverage the SPSiteCollection type particularly effectively, consider the following scenario. Out of the box, only farm administrators or those who possess administrative-level access to the servers that SharePoint runs on can execute SharePoint backups. Because you can easily execute site collection backups from within a SharePoint site through custom code leveraging the SPSiteCollection type, you can develop a solution to give site administrators the capability to execute on-demand backups for site collections for which they have some responsibility. Such a solution might take the form of a custom administrative action, user control, or Web Part, and you can enable or disable it for specific groups and individuals as governance policies demand.