Programming with the Windows SharePoint Services Backup/Restore Object Model
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
This topic describes the architecture of the backup and restore object model in Windows SharePoint Services 3.0 and provides some advice about how to program against it. Your backup application can be an independent application or an extension of the stsadm.exe command-line tool. For more information about how to extend stsadm, see How to: Extend the STSADM Utility.
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 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)
Each particular backup or restore operation is represented by an object of the class SPBackupRestoreConsoleObject that is created by the [M:Microsoft.SharePoint.Administration.Backup.SPBackupRestoreConsole.CreateBackupRestore()] 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 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 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 (and might also inherit from SPPersistedObject). (See callout 4 in Figure 1.) Implementation of the latter interface turns an object into something that can potentially be backed up and restored. Like an SPBackupRestoreInformation object, an IBackupRestore object contains members that provide information and methods needed for backups and restorations. But the members of IBackupRestore 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 and OnRestore.
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 and IBackupRestore), on the other.
The final major classes are SPBackupSettings and SPRestoreSettings. An object of one of these two types is passed to the [M:Microsoft.SharePoint.Administration.Backup.SPBackupRestoreConsole.CreateBackupRestore()] 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 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 and might or might not also derive the SPPersistedObject class. For more information about how to create a custom content class, see How to: Create a Content Class That Can Be Backed Up and Restored.
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 Backup and 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: Extend the STSADM Utility
Reference
Microsoft.SharePoint.Administration.Backup