How to: Programmatically Restore Content

 

Introduction

This post explains how to create an application that restores from a backup a content component, including a custom content component, of a Windows SharePoint Services 3.0 farm. The post assumes that you are familiar with my previous posts Overview of Backing Up and Restoring Data in Windows SharePoint Services and Programming with the Windows SharePoint Services Backup/Restore Object Model.

Note: Unless specified otherwise, all classes referred to in this post are in the Microsoft.SharePoint.Administration.Backup namespace. Classes that you create are in bold pink.

Procedures

 

To Restore a Content Component

1. Add a reference to Windows SharePoint Services to your Visual Studio project and add using statements for the Microsoft.SharePoint.Administration and Microsoft.SharePoint.Administration.Backup namespaces to you code file. 2. Inside the Main method, create a SPRestoreSettings object by using the static SPBackupRestoreSettings.GetRestoreSettings method. For the first parameter pass the path where the backup is stored. For the second parameter pass a string version of one of the values of SPRestoreMethodType. [C#] SPRestoreSettings settings = SPBackupRestoreSettings.GetRestoreSettings((@"\\Server\WSSBackups", "Overwrite"); 3. Prompt the user to specify the content component that is to be restored and assign its name to the SPBackupRestoreSettings.IndividualItem property. To see an itemization of the names of the components on your farm that were included in the last full backup and that can be the objects of restore operations, you can either run the command stsadm -o restore -showtree at the server command line. To specify a different full backup package, use the -backupid parameter. Alternatively, you can visit Operations > Perform a Restore in the Central Administration application. To specify the whole farm, use "Farm" as the name. (Setting the property to null also selects the whole farm for backup assuming that you use SPBackupRestoreSettings.IndividualItem in all subsequent code to identify by name the component to be restored, as you should. For an example, see the use of the SPBackupRestoreConsole.FindItems method in step 9.) [C#] Console.Write("Enter name of component to restore (default is whole farm):"); settings.IndividualItem = Console.ReadLine(); 4. If you want to restore from a backup other than the most recent, identify the backup package by assigning its GUID to the SPRestoreSettings.BackupId property. A record of each backup operation for a particular backup location is stored in spbrtoc.xml in the root of the location. Each backup and restore operation is represented in the file by an <SPHistoryObject> element. If the operation is a backup, the <IsBackup> child of the <SPHistoryObject> element is "True". The <SPId> element of the <SPHistoryObject> element contains the GUID of the backup. Note: To programmatically obtain the list of all backup and restore operations, use the SPBackupRestoreConsole.GetHistory method. This method returns an SPBackupRestoreHistoryList object that contains SPBackupRestoreHistoryObject objects. Each of the latter represents an operation and holds its GUID in the SPBackupRestoreHistoryObject.SelfId property. [C#] settings.BackupId = new Guid("GUID"); 5. Optionally, set one or both of the SPBackupRestoreSettings.IsVerbose and SPBackupRestoreSettings.UpdateProgress properties. (For details about these properties, see the reference topics for them.) [C#] settings.IsVerbose = true; settings.UpdateProgress = 10; 6. If necessary, set the SPRestoreSettings.FarmAdminLoginName and SPRestoreSettings.FarmAdminLoginPassword properties. [C#] settings.FarmAdminLoginName = "Bob"; settings.FarmAdminPassword = "7*j2U"; 7. Create the restore operation with the SPBackupRestoreConsole.CreateBackupRestore method. (A history object for the operation is also created.) [C#] Guid restore = SPBackupRestoreConsole.CreateBackupRestore(settings); 8. If your UI has users type a component name instead of pick one from a list, you must make sure that the name entered matches exactly one component. Add the following line to your Main method. [C#] SPBackupRestoreObject node = EnsureUniqueValidComponentName(settings, ref restore); 9. Add the following declaration and implementation of your EnsureUniqueValidComponentName method. Use the SPBackupRestoreConsole.FindItems method to retrieve a collection of content objects whose names match the user-entered name. If there is no match, prompt the user to try again. If there is more than one, prompt the user to be more specific. If the component name that the user entered is valid and not ambiguous, get a reference to the SPBackupRestoreObject object that represents the component that the user wants to restore. [C#] private static SPBackupRestoreObject EnsureUniqueValidComponentName(SPBackupRestoreSettings settings, ref Guid operationGUID) {     SPBackupRestoreObjectCollection list = SPBackupRestoreConsole.FindItems(operationGUID, settings.IndividualItem);     SPBackupRestoreObject component = null;       if (list.Count <= 0)     {         Console.WriteLine("There is no component with that name. Run again with a new name.");         Console.WriteLine("Press Enter to continue.");         Console.ReadLine();     }     else if (list.Count > 1) // The component name specified is ambiguous. Prompt user to be more specific.     {         Console.WriteLine("More than one component matches the name you entered.");         Console.WriteLine("Run again with one of the following:");         for (int i = 0; i < list.Count; i++)         {             Console.WriteLine("\t{0}", list[i].ToString());         }         Console.WriteLine("Press Enter to continue.");         Console.ReadLine();     }     else     {         component = list[0];     }       return component;   } 10. In the Main method, create a conditional structure that will run only if your EnsureUniqueValidComponentName method has returned a valid node. [C#] if (node != null) {     // TODO: Set the restore operation as the active operation     // and run it. } 11. Replace the "TODO" line in the previous step with the following code. This sets the operation to be the active operation with the SPBackupRestoreConsole.SetActive method and tests to verify that it succeeded. If it fails, which it will if another backup or restore operation is already underway, report an error to the UI of your application. [C#] if (SPBackupRestoreConsole.SetActive(restore) == true) {     // TODO: Run the operation. See next step. } else {     // Report through your UI that another backup   // or restore operation is underway.   Console.WriteLine("Another backup or restore operation is already underway. Try again when it ends."); } 12. In the code branch that runs if the SPBackupRestoreConsole.SetActive call succeeds, run the operation with the SPBackupRestoreConsole.Run method. Test that the operation succeeds. If it fails, report the operation's failure message to your UI. The following code replaces the "TODO" line in the previous step. [C#] if (SPBackupRestoreConsole.Run(restore, node) == false) {    // Report "error" through your UI.     String error = SPBackupRestoreConsole.Get(restore).FailureMessage;     Console.WriteLine(error); } 13. Clean up the restore with the SPBackupRestoreConsole.Remove method. Add the following code just before the closing brace you inserted in step 10. [C#] // Clean up the operation. SPBackupRestoreConsole.Remove(restore);   Console.WriteLine("Restore attempt complete. Press Enter to continue."); Console.ReadLine();

 

 

Example

The following code shows how to program a restoration of a content component. Replace the placeholder \\Server\WSSBackups with the path of your backup location. The runtime will automatically find the most recent backup at that location.

 

using System;

using Microsoft.SharePoint.Administration;

using Microsoft.SharePoint.Administration.Backup;

 

namespace MyCompany.SharePoint.Administration.Backup

{

    class Restore

    {

        static void Main(string[] args)

        {

            // Create the restore settings.

            SPRestoreSettings settings = SPBackupRestoreSettings.GetRestoreSettings(@"\\Server\WSSBackups", "Overwrite");

 

            // Identify the content component to restore.

            Console.Write("Enter name of component to restore (default is whole farm):");

            settings.IndividualItem = Console.ReadLine();

           

            // Set optional operation parameters.

            settings.IsVerbose = true;

            settings.UpdateProgress = 10;

           

            // Create the restore operation and return its ID.

            Guid restore = SPBackupRestoreConsole.CreateBackupRestore(settings);

 

            SPBackupRestoreObject node = EnsureUniqueValidComponentName(settings, ref restore);

 

            if (node != null)

            {

                // Set the restore as the active job and run it.

                if (SPBackupRestoreConsole.SetActive(restore) == true)

                {

                    if (SPBackupRestoreConsole.Run(restore, node) == false)

                    {

                        // Report "error" through your UI.

                        String error = SPBackupRestoreConsole.Get(restore).FailureMessage;

                        Console.WriteLine(error);

                    }

                }

                else

                {

                    // Report through your UI that another backup

                    // or restore operation is underway.

                    Console.WriteLine("Another backup or restore operation is already underway. Try again when it ends.");

                }

 

                // Clean up the operation.

                SPBackupRestoreConsole.Remove(restore);

 

                Console.WriteLine("Restore attempt complete. Press Enter to continue.");

                Console.ReadLine();

            }

        }// end Main

 

        private static SPBackupRestoreObject EnsureUniqueValidComponentName(SPBackupRestoreSettings settings, ref Guid operationGUID)

        {

            SPBackupRestoreObjectCollection list = SPBackupRestoreConsole.FindItems(operationGUID, settings.IndividualItem);

            SPBackupRestoreObject component = null;

 

            if (list.Count <= 0)

            {

                Console.WriteLine("There is no component with that name. Run again with a new name.");

                Console.WriteLine("Press Enter to continue.");

               Console.ReadLine();

            }

            else if (list.Count > 1) // The component name specified is ambiguous. Prompt user to be more specific.

            {

                Console.WriteLine("More than one component matches the name you entered.");

                Console.WriteLine("Run again with one of the following:");

                for (int i = 0; i < list.Count; i++)

                {

                    Console.WriteLine("\t{0}", list[i].ToString());

                }

                Console.WriteLine("Press Enter to continue.");

                Console.ReadLine();

            }

            else

            {

                component = list[0];

            }

 

            return component;

 

        }// end EnsureUniqueValidComponentName

 

    }// end Restore class

}// end namespace

 See Also

Programming with the Windows SharePoint Services Backup/Restore Object Model

How to: Programmatically Back Up Content

How to: Create a Content Class That Can Be Backed Up and Restored

Comments

• Anonymous
  February 07, 2008
  Introduction This post describes how to back up and restore individual site collections programmatically.

• Anonymous
  February 07, 2008
  The comment has been removed