Programming with the SharePoint Foundation Backup/Restore Object Model
Applies to: SharePoint Foundation 2010
This topic describes the architecture of the backup and restore object model in SharePoint Foundation and provides some advice about how to program against it. Your backup application can be an independent application or a custom Powershell cmdlet. For more information about how to create Powershell cmdlets for SharePoint, see Windows PowerShell in the SharePoint Management Shell.
Note
There is a variant backup and restore object model for custom Web services that implement the Service Application Framework. It is not discussed in this topic. For more information, see Backing Up and Restoring in the Service Application Framework.
The Backup and Restore Object Model
At the top of the object model is the SPBackupRestoreConsole class. (See callout 1 in Figure 1.) It provides an umbrella operations manager responsible for queuing backup and restore jobs, starting jobs, and persisting a history of jobs in the form of .xml files. An object of this class is "just underneath the surface" of the UI of a backup application. Its members are mainly static methods and properties that provide hooks for the UI of the backup application. Both the Central Administration application, PowerShell, and the stsadm.exe command-line tool use these hooks.
Only one object of this class exists in a farm, and it is created the first time one of its members is called. It remains in memory until the next time Internet Information Server (IIS) is reset; however, its memory footprint is small.
Figure 1. The primary objects in the backup/restore hierarchy.
.gif "The major classes in the backup object model.")
Each particular backup or restore operation is represented by an object of the class SPBackupRestoreConsoleObject that is created by the CreateBackupRestore(SPBackupRestoreSettings) method of the console object. (See callout 2 in Figure 1, the queued backup and restore operations.) The properties of one of these lightweight objects hold information about the operation, such as whether it is a backup or a restore, the location of the backup files, the backup or restore method, the current stage of the operation, and the tree of content components that is being backed up or restored. Each of these objects also has an Id property of type Guid that serves as a handle for the object that can be passed to the methods of SPBackupRestoreConsole. For example, Run(Guid, SPBackupRestoreObject) is passed the ID of the operation (that is, the SPBackupRestoreConsoleObject object) that the console is to run next. Finally, each SPBackupRestoreConsoleObject has a Settings property that holds a persisting object that contains a reusable pattern of backup or restore settings. This object also identifies the content component that the operation is to back up or restore. The settings objects are discussed in more detail near the end of this section.
Although the SPBackupRestoreConsoleObject objects represent operations, the content components themselves are represented by SPBackupRestoreObject objects. (See callout 3 in Figure 1.) These objects can be nested with the Children property. Therefore, each one represents a tree of one or more content components. For example, a Web application could be represented by an SPBackupRestoreObject object that has each of the Web application's content databases as child SPBackupRestoreObject objects. The tree of components that are the subject of a particular backup or restore operation are internally linked to the SPBackupRestoreConsoleObject object that represents the operation. You can get a reference to the topmost SPBackupRestoreObject object in the tree by passing the ID of the SPBackupRestoreConsoleObject object to the GetRoot(Guid) method.
An SPBackupRestoreObject object is a container for two critical types of objects:
In its Information property the SPBackupRestoreObject object holds either an SPBackupInformation or an SPRestoreInformation object. These kinds of objects hold information about how to back up or restore a particular component and methods that can be called internally by SPBackupRestoreConsoleObject and SPBackupRestoreObject as part of an operation. More specifically, these classes hold methods and properties whose implementation should never change regardless of what kind of content component is being represented. Hence, they are sealed; deriving a new class from their parent, SPBackupRestoreInformation, is not supported.
In its IBackupRestore property the SPBackupRestoreObject object holds an object that implements the IBackupRestore interface or the IBackupRestoreConfiguration object (which includes IBackupRestore), and might also inherit from SPPersistedObject. (See callout 4 in Figure 1.) Implementation of either of these interfaces turns an object into something that can potentially be backed up and restored. Like an SPBackupRestoreInformation object, an IBackupRestore object (or IBackupRestoreConfiguration object) contains members that provide information and methods needed for backups and restorations. But the members of these interfaces must be given different implementations depending on the kind of content component that is being represented. Most importantly, the implementation includes event handlers for an operation's events, such as OnBackup(Object, SPBackupInformation) and OnRestore(Object, SPRestoreInformation).
Besides acting as a container, SPBackupRestoreObject is a helper class that provides easier interaction between the operation objects (SPBackupRestoreConsoleObject), on the one hand, and the component information objects (SPBackupRestoreInformation, IBackupRestore and IBackupRestoreConfiguration), on the other.
The final major classes are SPBackupSettings and SPRestoreSettings. An object of one of these two types is passed to the CreateBackupRestore(SPBackupRestoreSettings) method when an operation is created. (See callout 5 in Figure 1.) Each of these objects holds settings for use in operations; most importantly, they identify, in their IndividualItem property, the content component (or configuration settings component) that is the subject of the backup or restore operation. (See callout 6 in Figure 1.)
Programming Advice
The following information may be helpful to the development of backup and restore solutions.
Ways of Customization
Most of the critical classes in the backup/restore object model are sealed (NotInheritable in Microsoft Visual Basic). Moreover, although the following classes are not sealed, deriving from them is not supported. In each case, you must use the existing derived classes:
SPBackupRestoreInformation Existing derived classes: SPBackupInformation and SPRestoreInformation
SPBackupRestoreSettings Existing derived classes: SPBackupSettings and SPRestoreSettings
Accordingly, there are just two primary points of customization:
You can create your own high-level application (and UI) that uses the static methods of the operations console—an SPBackupRestoreConsole object—to manage and run backup and restore jobs. For more information about how to do this, see How to: Programmatically Back Up Content and How to: Programmatically Restore Content.
You can create a class that implements the IBackupRestore interface or IBackupRestoreConfiguration interface (which includes IBackupRestore) and might or might not also derive the SPPersistedObject class and also implement the IDatabaseSnapshotRestore interface. For more information about how to create a custom content (or configuration settings) class, see How to: Create a Content Class That Can Be Backed Up and Restored and How to: Create a Class That Is Included in Configuration-Only Backups and Restorations.
Tip
Although these are the two primary ways of developing against the main SharePoint Foundation object model, you can also work programmatically with database snapshots and restorations from unattached databases. For more information on these topics, see Programmatic Administration of Database Snapshots, Fine-grained Data Restoration from Unattached Database, and How to: Create a Database Class That Can Be Restored From a Snapshot.
Permissions
Code that backs up content must run in the user context of a farm administrator. Code that restores must run in the context of a user who is both a farm administrator and an administrator on all the front-end servers. The user should also have read and write permissions for the backup location.
Failure Logging
If a backup or restore operation fails, details about the failure are logged in spbackup.log or sprestore.log in the backup location.
Backups and Restores of Site Collections
Except for custom content types that you create by implementing IBackupRestore, the smallest content object that you can back up and restore with the classes in the Microsoft.SharePoint.Administration.Backup namespace is a content database. To programmatically backup or restore individual site collections, use SPSiteCollection.Backup and SPSiteCollection.Restore. For more information on backing up and restoring site collections, see How to: Programmatically Back Up and Restore a Single Site Collection.
See Also
Tasks
How to: Programmatically Back Up Content
How to: Programmatically Restore Content
How to: Programmatically Back Up and Restore a Single Site Collection
How to: Create a Content Class That Can Be Backed Up and Restored
How to: Create a Database Class That Can Be Restored From a Snapshot
Code Sample: Creating a Content Class That Can Be Backed Up
Reference
Microsoft.SharePoint.Administration.Backup