SharePoint 2010 : The SharePoint Object Model (part 1) - Extending Catastrophic Backup and Restore Through the SharePoint API

This section explores some of the more logical disaster recovery extension points for the Share-Point object model and how you might utilize them. This article employs numerous domain-specific concepts and a significant degree of development terminology, so some fluency with .NET development, object model hierarchies, and object-oriented programming is a definite plus. Even without this knowledge, though, there is content in each section that can boost your understanding of how SharePoint carries out its backup/recovery and export/import operations.

Extending Catastrophic Backup and Restore Through the SharePoint API

When you are interested in working with farm-level backup and recovery operations, the most logical place to focus your attention is on SharePoint’s catastrophic backup and restore types. Catastrophic backup and restore operations focus on the components of a SharePoint farm that reside at the content database level and higher in SharePoint’s logical hierarchy. This includes the farm itself, Service Applications, Web applications, and additional objects that are either associated with or the direct children of these components.

The Central Administration site exposes an interface to these types through its Farm Backup and Restore functions. SharePoint 2010 also exposes these types through a variety of cmdlets such as Backup-SPFarm, Restore-SPFarm, Get-SPBackupHistory, Backup-SPConfigurationData-base, and several others.

SPBackupRestoreConsole and Related Types

When SharePoint backups are configured and executed, whether through PowerShell or the Central Administration site, they leverage the SPBackupRestoreConsole class within the SharePoint object model and the types with which it is associated. Custom applications seeking to orchestrate backup and restore operations for SharePoint direct most of their calls through the SPBackupRestoreConsole class in some fashion.

Although not a true static class, SPBackupRestoreConsole largely behaves like one. Only one instance of the class exists at any given time within the scope of the SharePoint farm, and the bulk of its members and properties are static. Backup and restore operations, job history operations, and informational requests such as the amount of disk space a particular backup operation may consume all begin with calls to the SPBackupRestoreConsole.

You can find the SPBackupRestoreConsole and primary related types in the Microsoft. SharePoint.Admininstration.Backup namespace within the Microsoft.SharePoint.dll assembly. The relationship of key types within the namespace to one another is represented by the Unified Modeling Language (UML) diagram shown in Figure 1.

Figure 1. Relationships between the SPBackupRestoreConsole and associated types.

The circled numbers within the diagram represent several types, patterns, and interactions worthy of mention:

An example demonstrating the basics of how to orchestrate a full-farm catastrophic backup using the types and techniques described appears in Listing 1. Although functional, the example is just a starting point and omits a number of steps such as backup location free space checking, subfarm component selection, and other items that are important in a production implementation.

Listing 1.

public static void ExecuteFarmBackup()
{
  // They are set through code in this example, but normally you should give
  // users the option to specify the backup location and method (whether full
  // or differential).
  String BACKUP_LOCATION = @"\\BackupHost\SPFarmBackups\";
  String BACKUP_METHOD = SPBackupMethodType.Full.ToString();

  // This creates a usable set of backup settings needed to get a backup operation
  // going. The resultant settings object is a combination of the assigned
  // values for location and method plus default values for backup thread
  // count, content + configuration backup, and so on.
  SPBackupSettings backupSettings = SPBackupRestoreSettings.GetBackupSettings
    (BACKUP_LOCATION, BACKUP_METHOD);

  // Actually create (but don't start) the backup job. This registers the job with
  // the SPBackupRestoreConsole. Future references to the job are done using the
  // GUID that is returned.
  Guid backupGuid = SPBackupRestoreConsole.CreateBackupRestore(backupSettings);
  try
  {
     // The SPBackupRestoreConsole can execute only one job at a time, so
     // this call is a way of bringing the SPBackupRestoreConsole to focus
     // on the new backup job. If another job is running, the call fails
     // and an exception is thrown.
     if (!SPBackupRestoreConsole.SetActive(backupGuid))
     {
        throw new Exception("Backup or restore already in progress.");
     }

     // Actually execute a full-farm backup synchronously. The call won't
     // return until the backup is complete.
     if (!SPBackupRestoreConsole.Run(backupGuid, null))
     {
        throw new Exception("Full farm backup failed. Check spbackup.log.");
     }
  }

  finally
  {
    // The backup job completed in some form, so the associated job GUID should
    // be removed for "good SharePoint hygiene."
    SPBackupRestoreConsole.Remove(backupGuid);
  }
}


					  

It’s worth explicitly stating that the full-farm catastrophic backup set that is the output of this backup code sample is completely interoperable with both Central Administration’s farm-level restore capabilities and SharePoint’s Restore-SPFarm PowerShell cmdlet.

One potential application that might leverage this portion of the SharePoint object model jumps out immediately: a new user interface (UI) for SharePoint’s catastrophic backup and restore operations. Although the Central Administration site and PowerShell cmdlets provide mechanisms for full farm backups and restores, they are limited in both their UI and reporting. You could develop an application that delivers a rich user experience and does significantly more monitoring and reporting than the built-in tools. Such an application could also offer greater control and access to reports regarding previous backup and restore attempts. In addition, the hypothetical application could interface with scheduling systems such as Windows Task Scheduler to manage scheduled farm backups that operate outside the realm of SharePoint. In essence, you could create a more robust, more interactive experience for farm-level SharePoint backups and restores.

Content Components and Implementing IBackupRestore

By default, SharePoint is capable of backing up and restoring a variety of component types: entire farms, Service Applications, Web applications, and more. Each of these objects that can be backed up and restored is known as a content component and is represented by an SPBackupRestoreObject instance, as shown in Figure 1.

As shown in Figure 1, an SPBackupRestoreObject content component references additional types that drive its backup and restore behavior. One required type in all cases is an object that derives from the abstract SPBackupRestoreInformation class—either an SPBackupInformation instance or an SPRestoreInformation instance. Both of these types convey information about the backup or restore that is being conducted, such as the backup location that is in use, the parent of the current content component (an SPBackupRestoreObject instance itself), and other relevant properties. The information in these SPBackupRestoreInformation-derived objects provides the content component with the data it needs to understand and properly carry out the requested backup or restore operation.

The second object that an SPBackupRestoreObject references is another object that implements the IBackupRestore interface. This IBackupRestore implementer contains the custom code that is executed during the various stages of both the backup and restore life cycles for the content component. In the case of a backup, for instance, the object must provide implementation logic for methods such as OnPrepareBackup, AddBackupObjects, and OnBackup.

Under normal operations, a one-to-one mapping exists between a derived type of the SPBackupRestoreInformation class and an associated IBackupRestore implementation for any given SPBackupRestoreObject. Because both SPBackupInformation and SPRestoreInformation are sealed types, and the SPBackupRestoreObject itself is a sealed type, your ability to customize and extend the backup and restore capabilities of SharePoint to include custom objects lies with the IBackupRestore interface and types that implement it.

To understand how this could be useful, consider a couple of examples:

• Web.config files. You must implement a strategy for the backup and restore of critical system files alongside SharePoint’s own backup and restore mechanisms to ensure complete coverage of all critical and dependent SharePoint farm targets. Web.config files are so closely tied to SharePoint Web applications that many would prefer a mechanism that couples web.config files to their Web applications when SharePoint backup and restore operations are performed.

• Associated databases. In some environments, it is not uncommon to find additional SQL Server databases that are both used by SharePoint and housed in the SQL Server instances supporting SharePoint. Such databases could be critical to some facet of farm operations, but custom databases (that is, those that are not SharePoint content databases) are not included within SharePoint’s backup and restore operations by default.

In both of the examples just cited, creation of a content component that implements IBackup-Restore can be an avenue to the inclusion of the desired items (web.config files and custom databases) in SharePoint’s catastrophic backup and restore operations.

Microsoft provides an informative walk-through on the creation of these types in the SharePoint Foundation 2010 SDK, though. Look for the “How to: Create a Content Class That Can Be Backed Up and Restored” section in either the online or downloadable version of the SDK for more information.

Configuration-Only Backup and Restore

New to SharePoint 2010 is the concept of configuration-only backup and restore. In essence, this process allows you to capture the portable configuration and settings that are present in one farm and apply them in another farm as a sort of template. Technically, a configuration-only restore can also be performed to the same farm from which the backup was performed to roll back affected settings to an earlier point in time.

From a development standpoint, the creation of types that support configuration-only backup and restore is similar to the creation of custom content components for backup and restore. Much like the creation of a custom content component, an SPBackupRestoreObject and an SPBackupRestoreInformation-derived type are in play when a custom configuration component is backed up and restored. As you might guess from looking at Figure 1, the major difference rests with the IBackupRestoreConfiguration interface.

Custom configuration components implement the IBackupRestoreConfiguration interface instead of the IBackupRestore interface, and it is through the CanBackupRestoreAsConfiguration property on the interface that they signal their ability to participate in configuration-only backup and restore operations.

Classes that implement IBackupRestoreConfiguration must represent truly portable configuration data and other information that is not specific to a particular server, farm topology, or other similar aspect of a SharePoint environment. In addition, even though IBackupRestore-Configuration implementers participate in both configuration-only and standard configuration-with-content backups and restores, they themselves must not contain anything that represents farm content, such as site collections, lists, list items, supplemental databases, nonconfiguration files, and so on.

The Special Case of Web Service Applications

Web Service Applications (derived from SPIisWebServiceApplication) and Web Service Application proxies (derived from SPIisWebServiceApplicationProxy) are new to SharePoint 2010 and represent a special case when it comes to catastrophic backup and restore. Support for backup and restore operations isn’t supplied by the standard catastrophic types that reside in the Microsoft.SharePoint.Administration.Backup namespace, but rather through a few specific types in the Microsoft.SharePoint.Administration namespace that are part of the Service Application Framework.

If you create your own Web Service Applications and proxies and want to include them in backup and restore operations, know that the creators of the Service Application Framework have already done most of the heavy lifting for you. Unlike the process of implementing the IBackupRestore interface for custom content components, Web Service Applications and their proxies can be included in backup and restore operations with the assignment of one of the following attributes at the application class level:

• IisWebServiceApplicationBackupBehaviorAttribute for Web Service Applications

• IisWebServiceApplicationProxyBackupBehaviorAttribute for Web Service Application proxies

When you use these attributes, the Service Application Framework automatically takes care of backing up and restoring the following resource types that are tied to your Web Service Applications and proxies:

• Persisted objects

• Platform-level access control lists

• Service endpoints

• Associated application pools

• Topology service-based load balancers

• Databases and round-robin load balancers referenced through SPDatabase-derived classes

If your Web Service Applications or proxies maintain custom resources that should be backed up and restored, such as load balancers that don’t derive from the SPDatabase type, you need to do some custom coding. Neither the IisWebServiceApplicationBackupBehaviorAttribute nor the IisWebServiceApplicationProxyBackupBehaviorAttribute type is sealed, and you can extend them to support the inclusion of custom resources in the backup and restore process.

Both of these attributes derive from the IisWebServiceBackupBehaviorAttribute abstract type. As shown in Figure 2, the IisWebServiceBackupBehaviorAttribute includes many of the methods and properties that the IBackupRestore interface uses for custom content component protection. When you execute backups and restores, interactions with protected Web Service Applications and proxies occur in much the same way that custom content components are engaged through the IBackupRestore interface.

Figure 2. Similarities between IisWebServiceBackupBehaviorAttribute and IBackupRestore.

It is worth noting that backups for Web Service Applications and proxies are supported by Microsoft only when they’re done through the use of the IisWebServiceApplicationBackupBehaviorAttribute and IisWebServiceApplicationProxyBackupBehaviorAttribute attributes. It is only through the use of these attributes that certain elements, such as service-related application pools, can be properly backed up and restored.