How to: Programmatically Back Up Content

Article
10/20/2016

Applies to: SharePoint Foundation 2010

This topic explains how to program a backup of a SharePoint Foundation content component. The topic assumes that you are familiar with Overview of Backing Up and Restoring Data in SharePoint Foundation and Programming with the SharePoint Foundation Backup/Restore Object Model.

To Back Up a Content Component

Add a reference to Microsoft.SharePoint to your Visual Studio project and add using statements for the Microsoft.SharePoint.Administration and Microsoft.SharePoint.Administration.Backup namespaces to you code file.

Inside the Main method, prompt the user to specify where the backup should be stored.

Console.Write("Enter full UNC path to the directory where the backup will be stored:");
String backupLocation = Console.ReadLine();

Console.Write("Enter full UNC path to the directory where the backup will be stored:")
Dim backupLocation As String = Console.ReadLine()

Inside the Main method, create a SPBackupSettings object by using the static GetBackupSettings method. For the first parameter pass the path where the backup should be stored. For the second parameter pass a string version of one of the values of SPBackupMethodType.
```
SPBackupSettings settings = SPBackupRestoreSettings.GetBackupSettings(backupLocation, "Full");
```
```
Dim settings As SPBackupSettings = SPBackupRestoreSettings.GetBackupSettings(backupLocation, "Full")
```
Prompt the user to specify the content component to back up and assign its name to the IndividualItem property. To see an itemization of the names of the components on your farm that can be the objects of backup operations, you can either run the command stsadm -o backup -showtree at the server command line or visit Operations > Perform a Backup 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 IndividualItem in all subsequent code to identify by name the component to be backed up, as you should. For an example, see the use of the FindItems() method in step 8.)
```
Console.Write("Enter name of component to backup (default is whole farm):");
settings.IndividualItem = Console.ReadLine();
```
```
Console.Write("Enter name of component to backup (default is whole farm):")
settings.IndividualItem = Console.ReadLine()
```

Optionally, set one or more of the IsVerbose, UpdateProgress, and BackupTheads() properties. (For details about these properties, see the reference topics for them.)

settings.IsVerbose = true;
settings.UpdateProgress = 10;
settings.BackupThreads = 2;

settings.IsVerbose = True
settings.UpdateProgress = 10
settings.BackupThreads = 2

Create the backup operation with the CreateBackupRestore() method. (A history object for the operation is also created. For more information, see SPBackupRestoreHistoryObject and SPBackupRestoreHistoryList.)
```
Guid backup = SPBackupRestoreConsole.CreateBackupRestore(settings);
```
```
Dim backup As Guid = SPBackupRestoreConsole.CreateBackupRestore(settings)
```
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.
```
SPBackupRestoreObject node = EnsureUniqueValidComponentName(settings, ref backup);
```
```
Dim node As SPBackupRestoreObject = EnsureUniqueValidComponentName(settings, backup)
```

Add the following implementation of your EnsureUniqueValidComponentName method. Use the 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.

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;

}

Private Shared Function EnsureUniqueValidComponentName(ByVal settings As SPBackupRestoreSettings, ByRef operationGUID As Guid) As SPBackupRestoreObject
    Dim list As SPBackupRestoreObjectCollection = SPBackupRestoreConsole.FindItems(operationGUID, settings.IndividualItem)
    Dim component As SPBackupRestoreObject = Nothing

    If list.Count <= 0 Then
        Console.WriteLine("There is no component with that name. Run again with a new name.")
        Console.WriteLine("Press Enter to continue.")
        Console.ReadLine()
    ElseIf list.Count > 1 Then ' 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 i As Integer = 0 To list.Count - 1
            Console.WriteLine(vbTab & "{0}", list(i).ToString())
        Next i
        Console.WriteLine("Press Enter to continue.")
        Console.ReadLine()
    Else
        component = list(0)
    End If

    Return component

End Function

In the Main method, create a Boolean flag that will signal whether there is sufficient space for the backup, and a conditional structure that will run only if your EnsureUniqueValidComponentName method has returned a valid node.

Boolean targetHasEnoughSpace = false;
if (node != null)
{
    targetHasEnoughSpace = EnsureEnoughDiskSpace(backupLocation, backup, node);
}

Dim targetHasEnoughSpace As Boolean = False
If node IsNot Nothing Then
    targetHasEnoughSpace = EnsureEnoughDiskSpace(backupLocation, backup, node)
End If

Add the following implementation of your EnsureEnoughDiskSpace method. Use the DiskSizeRequired() method to obtain the amount of space that is needed, and the DiskSize() method to determine how much free space is available on the destination disk.

private static Boolean EnsureEnoughDiskSpace(String location, Guid backup, SPBackupRestoreObject node)
{
    UInt64 backupSize = SPBackupRestoreConsole.DiskSizeRequired(backup, node);
    UInt64 diskFreeSize = 0;
    UInt64 diskSize = 0;
    Boolean hasEnoughSpace = true;

    try
    {
        SPBackupRestoreConsole.DiskSize(location, out diskFreeSize, out diskSize);
    }
    catch
    {
        diskFreeSize = diskSize = UInt64.MaxValue;
    }

    if (backupSize > diskFreeSize)
    {
        // Report through your UI that there is not enough disk space.
        Console.WriteLine("{0} bytes of space is needed but the disk hosting {1} has only {2}.", backupSize, location, diskFreeSize);
        Console.WriteLine("Please try again with a different backup location or a smaller component.");
        hasEnoughSpace = false;
    }
    else if (backupSize == UInt64.MaxValue || diskFreeSize == 0)
    {
        // Report through your UI that it cannot be determined whether there is enough disk space.
        Console.WriteLine("Cannot determine if that location has enough disk space.");
        Console.WriteLine("Please try again with a different backup location or a smaller component.");
        hasEnoughSpace = false;
    }
    return hasEnoughSpace;

}

Private Shared Function EnsureEnoughDiskSpace(ByVal location As String, ByVal backup As Guid, ByVal node As SPBackupRestoreObject) As Boolean
    Dim backupSize As UInt64 = SPBackupRestoreConsole.DiskSizeRequired(backup, node)
    Dim diskFreeSize As UInt64 = 0
    Dim diskSize As UInt64 = 0
    Dim hasEnoughSpace As Boolean = True

    Try
        SPBackupRestoreConsole.DiskSize(location, diskFreeSize, diskSize)
    Catch
        diskSize = UInt64.MaxValue
        diskFreeSize = diskSize
    End Try

    If backupSize > diskFreeSize Then
        ' Report through your UI that there is not enough disk space.
        Console.WriteLine("{0} bytes of space is needed but the disk hosting {1} has only {2}.", backupSize, location, diskFreeSize)
        Console.WriteLine("Please try again with a different backup location or a smaller component.")
        hasEnoughSpace = False
    ElseIf backupSize = UInt64.MaxValue OrElse diskFreeSize = 0 Then
        ' Report through your UI that it cannot be determined whether there is enough disk space.
        Console.WriteLine("Cannot determine if that location has enough disk space.")
        Console.WriteLine("Please try again with a different backup location or a smaller component.")
        hasEnoughSpace = False
    End If
    Return hasEnoughSpace

End Function

In the Main method, create a conditional structure that will run only if your EnsureEnoughDiskSpace returns true.

if (targetHasEnoughSpace)
{
    // TODO: Set the backup operation as the active operation
    // and run it.
}

If targetHasEnoughSpace Then
     ' TODO: Set the backup operation as the active operation
     ' and run it.
End If

Replace the "TODO" line in the previous step with the following code. This sets the operation to be the active operation with the 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.

if (SPBackupRestoreConsole.SetActive(backup) == 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.");
}

If SPBackupRestoreConsole.SetActive(backup) = True Then
     ' 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.")
End If

In the code branch that runs if the SetActive() call succeeds, run the operation with the 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.

if (SPBackupRestoreConsole.Run(backup, node) == false)
{
    // Report "error" through your UI.
    String error = SPBackupRestoreConsole.Get(backup).FailureMessage;
    Console.WriteLine(error);
}

If SPBackupRestoreConsole.Run(backup, node) = False Then
   ' Report "error" through your UI.
   Dim [error] As String = SPBackupRestoreConsole.Get(backup).FailureMessage
   Console.WriteLine([error])
End If

Clean up the restore with the Remove() method. Add the following code just before the closing brace you inserted in step 11.

// Clean up the operation.
SPBackupRestoreConsole.Remove(backup);

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

' Clean up the operation.
SPBackupRestoreConsole.Remove(backup)

Console.WriteLine("Backup attempt complete. Press Enter to continue.")
Console.ReadLine()

Example

The following code shows how to program a backup of a content component.

using System;
using Microsoft.SharePoint.Administration;
using Microsoft.SharePoint.Administration.Backup;

namespace MyCompany.SharePoint.Administration.Backup
{
    class Backup
    {
        static void Main(string[] args)
        {
            // Identify the location for the backup storage.
            Console.Write("Enter full UNC path to the directory where the backup will be stored:");
            String backupLocation = Console.ReadLine();
            
            // Create the backup settings.
            SPBackupSettings settings = SPBackupRestoreSettings.GetBackupSettings(backupLocation, "Full");

            // Identify the content component to backup.
            Console.Write("Enter name of component to backup (default is whole farm):");
            settings.IndividualItem = Console.ReadLine();
            
            // Set optional operation parameters.
            settings.IsVerbose = true;
            settings.UpdateProgress = 10;
            settings.BackupThreads = 10;

            // Create the backup operation and return its ID.
            Guid backup = SPBackupRestoreConsole.CreateBackupRestore(settings);

            // Ensure that user has identified a valid and unique component.
            SPBackupRestoreObject node = EnsureUniqueValidComponentName(settings, ref backup);

            // Ensure that there is enough space.
            Boolean targetHasEnoughSpace = false;
            if (node != null)
            {
                targetHasEnoughSpace = EnsureEnoughDiskSpace(backupLocation, backup, node);
            }

            // If there is enough space, attempt to run the backup.
            if (targetHasEnoughSpace)
            {
                // Set the backup as the active job and run it.
                if (SPBackupRestoreConsole.SetActive(backup) == true)
                {
                    if (SPBackupRestoreConsole.Run(backup, node) == false)
                    {
                        // Report "error" through your UI.
                        String error = SPBackupRestoreConsole.Get(backup).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(backup);

                Console.WriteLine("Backup 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

        private static Boolean EnsureEnoughDiskSpace(String location, Guid backup, SPBackupRestoreObject node)
        {
            UInt64 backupSize = SPBackupRestoreConsole.DiskSizeRequired(backup, node);
            UInt64 diskFreeSize = 0;
            UInt64 diskSize = 0;
            Boolean hasEnoughSpace = true;

            try
            {
                SPBackupRestoreConsole.DiskSize(location, out diskFreeSize, out diskSize);
            }
            catch
            {
                diskFreeSize = diskSize = UInt64.MaxValue;
            }

            if (backupSize > diskFreeSize)
            {
                // Report through your UI that there is not enough disk space.
                Console.WriteLine("{0} bytes of space is needed but the disk hosting {1} has only {2}.", backupSize, location, diskFreeSize);
                Console.WriteLine("Please try again with a different backup location or a smaller component.");
                hasEnoughSpace = false;
            }
            else if (backupSize == UInt64.MaxValue || diskFreeSize == 0)
            {
                // Report through your UI that it cannot be determined whether there is enough disk space.
                Console.WriteLine("Cannot determine if that location has enough disk space.");
                Console.WriteLine("Please try again with a different backup location or a smaller component.");
                hasEnoughSpace = false;
            }
            return hasEnoughSpace;

        }// end EnsureEnoughDiskSpace

    }// end Backup class
}// end namespace

Imports System
Imports Microsoft.SharePoint.Administration
Imports Microsoft.SharePoint.Administration.Backup

Namespace MyCompany.SharePoint.Administration.Backup
    Module Backup
        Sub Main(ByVal args() As String)
            ' Identify the location for the backup storage.
            Console.Write("Enter full UNC path to the directory where the backup will be stored:")
            Dim backupLocation As String = Console.ReadLine()

            ' Create the backup settings.
            Dim settings As SPBackupSettings = SPBackupRestoreSettings.GetBackupSettings(backupLocation, "Full")

            ' Identify the content component to backup.
            Console.Write("Enter name of component to backup (default is whole farm):")
            settings.IndividualItem = Console.ReadLine()

            ' Set optional operation parameters.
            settings.IsVerbose = True
            settings.UpdateProgress = 10
            settings.BackupThreads = 10

            ' Create the backup operation and return its ID.
            Dim backup As Guid = SPBackupRestoreConsole.CreateBackupRestore(settings)

            ' Ensure that user has identified a valid and unique component.
            Dim node As SPBackupRestoreObject = EnsureUniqueValidComponentName(settings, backup)

            ' Ensure that there is enough space.
            Dim targetHasEnoughSpace As Boolean = False
            If node IsNot Nothing Then
                targetHasEnoughSpace = EnsureEnoughDiskSpace(backupLocation, backup, node)
            End If

            ' If there is enough space, attempt to run the backup.
            If targetHasEnoughSpace Then
                ' Set the backup as the active job and run it.
                If SPBackupRestoreConsole.SetActive(backup) = True Then
                    If SPBackupRestoreConsole.Run(backup, node) = False Then
                        ' Report "error" through your UI.
                        Dim [error] As String = SPBackupRestoreConsole.Get(backup).FailureMessage
                        Console.WriteLine([error])
                    End If
                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.")
                End If

                ' Clean up the operation.
                SPBackupRestoreConsole.Remove(backup)

                Console.WriteLine("Backup attempt complete. Press Enter to continue.")
                Console.ReadLine()
            End If
        End Sub ' end Main

        Private Function EnsureUniqueValidComponentName(ByVal settings As SPBackupRestoreSettings, ByRef operationGUID As Guid) As SPBackupRestoreObject
            Dim list As SPBackupRestoreObjectCollection = SPBackupRestoreConsole.FindItems(operationGUID, settings.IndividualItem)
            Dim component As SPBackupRestoreObject = Nothing

            If list.Count <= 0 Then
                Console.WriteLine("There is no component with that name. Run again with a new name.")
                Console.WriteLine("Press Enter to continue.")
                Console.ReadLine()
            ElseIf list.Count > 1 Then ' 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 i As Integer = 0 To list.Count - 1
                    Console.WriteLine(vbTab & "{0}", list(i).ToString())
                Next i
                Console.WriteLine("Press Enter to continue.")
                Console.ReadLine()
            Else
                component = list(0)
            End If

            Return component

        End Function ' end EnsureUniqueValidComponentName

        Private Function EnsureEnoughDiskSpace(ByVal location As String, ByVal backup As Guid, ByVal node As SPBackupRestoreObject) As Boolean
            Dim backupSize As UInt64 = SPBackupRestoreConsole.DiskSizeRequired(backup, node)
            Dim diskFreeSize As UInt64 = 0
            Dim diskSize As UInt64 = 0
            Dim hasEnoughSpace As Boolean = True

            Try
                SPBackupRestoreConsole.DiskSize(location, diskFreeSize, diskSize)
            Catch
                diskSize = UInt64.MaxValue
                diskFreeSize = diskSize
            End Try

            If backupSize > diskFreeSize Then
                ' Report through your UI that there is not enough disk space.
                Console.WriteLine("{0} bytes of space is needed but the disk hosting {1} has only {2}.", backupSize, location, diskFreeSize)
                Console.WriteLine("Please try again with a different backup location or a smaller component.")
                hasEnoughSpace = False
            ElseIf backupSize = UInt64.MaxValue OrElse diskFreeSize = 0 Then
                ' Report through your UI that it cannot be determined whether there is enough disk space.
                Console.WriteLine("Cannot determine if that location has enough disk space.")
                Console.WriteLine("Please try again with a different backup location or a smaller component.")
                hasEnoughSpace = False
            End If
            Return hasEnoughSpace

        End Function ' end EnsureEnoughDiskSpace

    End Module ' end Backup class
End Namespace ' end namespace

How to: Programmatically Back Up Content

To Back Up a Content Component

Example

See Also

Tasks

Reference

Concepts

Other Resources

Additional resources