Microsoft SharePoint Developer Documentation Team Blog : SharePoint

How to Add a Tab to the Ribbon in SharePoint Foundation

Andrew May — Tue, 08 Dec 2009 03:07:00 GMT

(Before he left for a week of laying on various tropical beaches with drinks in his hand, Dallas asked me to post this for him. Since I'm stuck in the rainy Northwest and had nothing better to do, I was happy to oblige him.)

The ribbon has unified the command surface inside of SharePoint. It is now the primary point of entry for working with items inside of SharePoint. As such the ribbon is extensible through the use of declarative XML in a Feature.

This post will cover how to add a new tab to the ribbon in Microsoft SharePoint Foundation 2010. It will also, by necessity, cover how to create a group, controls, template, and scaling behavior. I will build this solution in Visual Studio 2010 Beta 2 and as a sandboxed solution for the ease of deployment.

The following will appear in a future version of the SDK. It is preliminary documentation and subject to change.

First, you will want to create a new project. Click on File, New, and then Project.

Under Visual C#, choose Empty SharePoint Project and enter AddARibbonTab for the Name. Click OK.

In the SharePoint Customization Wizard, choose Deploy as a sandboxed solution. Click Finish.

In the Solution Explorer, right click on Features and choose Add Feature.

Change the Title of the Feature to Custom Ribbon Tab. Also, rename Feature1 in the Solution Explorer to CustomRibbonTab.

Right click on the AddARibbonTab project in the Solution Explorer and choose Add, New Item…

In the Add New Item dialog, choose the Empty Element template. Enter CustomRibbonTab as the Name.

In the Elements.xml file, insert the following CustomAction element. The Location attribute tells the CustomAction where to apply the customization. The following list explains the acceptable values.

Value	Description
CommandUI.Ribbon	Customization appears everywhere for the specified RegistrationId.
CommandUI.Ribbon.ListView	Customization appears when the list view Web Part is present.
CommandUI.Ribbon.EditForm	Customization appears on the edit form.
CommandUI.Ribbon.NewForm	Customization appears on the new form.
CommandUI.Ribbon.DisplayForm	Customization appears on the display form.

<?xml version="1.0" encoding="utf-8"?>

<CustomAction

Id="MyCustomRibbonTab"

Location="CommandUI.Ribbon.ListView"

RegistrationId="101"

RegistrationType="List">

</CustomAction>

</Elements>

Add the following elements to define the ribbon extension and tab. The Location on the CommandUIDefinition element defines where the controls inside of it will render. In this example, you reference the Tabs collection of the ribbon. The _children convention tells the ribbon to insert the following XML, whether it is a tab, group, or control, into the collection of tabs. The Sequence attribute on the Tab element defines where the tab will render in regards to other tabs. The default tabs use multiples of 100, so the Sequence attribute should not be a multiple of 100 to prevent collisions.

<CommandUIDefinition

Location="Ribbon.Tabs._children">

<Tab

Id="Ribbon.CustomTabExample"

Title="My Custom Tab"

Description="This holds my custom commands!"

Sequence="501">

When creating a custom tab, you must define how the tab will scale when controls are added. This is handled through the use of the Scaling element along with a GroupTemplate. The MaxSize element defines the maximum size of the controls in the group. The Scale element defines how the group will scale in different situations. The GroupId attribute associates a group with the scale size. The Size attribute is defined by the Layout element, which is defined later in this topic.

<Scaling

Id="Ribbon.CustomTabExample.Scaling">

<MaxSize

Id="Ribbon.CustomTabExample.MaxSize"

GroupId="Ribbon.CustomTabExample.CustomGroupExample"

Size="OneLargeTwoMedium"/>

<Scale

Id="Ribbon.CustomTabExample.Scaling.CustomTabScaling"

GroupId="Ribbon.CustomTabExample.CustomGroupExample"

Size="OneLargeTwoMedium" />

</Scaling>

Now, you will define the groups of controls that will appear on the tab. The Group element contains the usual attributes along with a Template attribute. The Template attribute references the GroupTemplate that is defined later in this topic. The Controls element contains the controls that will render in the group. These can be buttons, dropdowns, and other control types. You can find a list in the SDK at this address: http://msdn.microsoft.com/en-us/library/ee537017(office.14).aspx. The controls inside the group must define the TemplateAlias and Command attributes. Like tabs, each control has a Sequence attribute that defines where they will render in the group. The default controls are based on multiples of 10, so any custom controls should not use a multiple of 10 to avoid collisions. The Command attribute is used by the CommandUIHandler defined later in this topic but is required even if the CommandUIHandler is not specified. The TemplateAlias attribute defines where the control will render in relationship to the GroupTemplate.

<Group

Id="Ribbon.CustomTabExample.CustomGroupExample"

Description="This is a custom group!"

Title="Custom Group"

Sequence="52"

Template="Ribbon.Templates.CustomTemplateExample">

<Button

Id="Ribbon.CustomTabExample.CustomGroupExample.HelloWorld"

Command="CustomTabExample.HelloWorldCommand"

Sequence="15"

Description="Says Hello to the World!"

LabelText="Hello, World!"

TemplateAlias="cust1"/>

<Button

Id="Ribbon.CustomTabExample.CustomGroupExample.GoodbyeWorld"

Command="CustomTabExample.GoodbyeWorldCommand"

Sequence="17"

Description="Says Good-bye to the World!"

LabelText="Good-bye, World!"

TemplateAlias="cust2"/>

<Button

Id="Ribbon.CustomTabExample.CustomGroupExample.LoveWorld"

Command="CustomTabExample.LoveWorldCommand"

Sequence="19"

Description="Says I <3 the World!"

LabelText="I <3 you, World!"

TemplateAlias="cust3"/>

</Controls>

</Group>

</Groups>

</Tab>

</CommandUIDefinition>

With that code in place, you have finished the first CommandUIDefinition that includes the tab, groups, and controls. You need to define how the controls will render inside of the group. You do this using a GroupTemplate element in another CommandUIDefinition. The CommandUIDefinition will have a Location of Ribbon.Templates._children. This follows the pattern for Groups and Tabs.

The GroupTemplate element contains a Layout element with Section and Row elements. The Layout element has a LayoutTitle that is used for the Size attribute on the MaxSize and Scale elements. The Section elements define the position of the controls as well as how many rows will render inside that section. The Row element contains one or more ControlRef elements. ControlRef elements define how your controls will display. The DisplayMode attribute can have the following values:

Value	Description
Small	Renders as a small icon without label text.
Medium	Renders as a 16x16 icon with label text.
Large	Renders as a 32x32 icon with label text.
Text	Renders as text only.

The ControlRef elements also define the TemplateAlias values that you used for the TemplateAlias attribute on the buttons. Note that only one control per group can use this value. You cannot have two controls with the same TemplateAlias unless it is an OverflowArea. You can reuse the TemplateAlias across different groups though. There is also an OverflowArea element that defines how controls will render if there are too many controls in a group. The TemplateAlias attributes that refer to OverflowAreas in the GroupTemplate can be used on multiple controls.

In this example, you will define two sections for rendering the controls. One section will be a row of large buttons while the other section will contain two rows of medium-sized buttons.

<Layout

Title="OneLargeTwoMedium"

LayoutTitle="OneLargeTwoMedium">

<Row>

</Row>

</Section>

<Row>

</Row>

<Row>

</Row>

</Section>

</Layout>

</GroupTemplate>

</CommandUIDefinition>

</CommandUIDefinitions>

The final step is to write handlers for the buttons. These are inside CommandUIHandler elements. The Command attribute is a unique name for the command and used for the Command attribute on controls. The CommandAction attribute contains the action that is performed for the control. This can be JavaScript, an URL, or anything that was previously contained in an UrlAction element.

<CommandUIHandler

Command="CustomTabExample.HelloWorldCommand"

CommandAction="javascript:alert('Hello, world!');" />

<CommandUIHandler

Command="CustomTabExample.GoodbyeWorldCommand"

CommandAction="javascript:alert('Good-bye, world!');" />

<CommandUIHandler

Command="CustomTabExample.LoveWorldCommand"

CommandAction="javascript:alert('I love you, world!');" />

</CommandUIHandlers>

</CommandUIExtension>

With the addition of the CommandUIHandlers, you have finished your Elements.xml file. Press F5 to deploy your solution. Then, navigate to the Shared Documents folder. You should see the Custom Tab. Click on Custom Tab to open it. Click any of the buttons to show the associated alert.

Hopefully this walkthrough has been helpful! If you have any questions or concerns, please let me know in the comments.

Full Code Listing:

<?xml version="1.0" encoding="utf-8"?>

<CustomAction

Id="MyCustomRibbonTab"

Location="CommandUI.Ribbon.ListView"

RegistrationId="101"

RegistrationType="List">

<CommandUIDefinition

Location="Ribbon.Tabs._children">

<Tab

Id="Ribbon.CustomTabExample"

Title="My Custom Tab"

Description="This holds my custom commands!"

Sequence="501">

<Scaling

Id="Ribbon.CustomTabExample.Scaling">

<MaxSize

Id="Ribbon.CustomTabExample.MaxSize"

GroupId="Ribbon.CustomTabExample.CustomGroupExample"

Size="OneLargeTwoMedium"/>

<Scale

Id="Ribbon.CustomTabExample.Scaling.CustomTabScaling"

GroupId="Ribbon.CustomTabExample.CustomGroupExample"

Size="OneLargeTwoMedium" />

</Scaling>

<Group

Id="Ribbon.CustomTabExample.CustomGroupExample"

Description="This is a custom group!"

Title="Custom Group"

Sequence="52"

Template="Ribbon.Templates.CustomTemplateExample">

<Button

Id="Ribbon.CustomTabExample.CustomGroupExample.HelloWorld"

Command="CustomTabExample.HelloWorldCommand"

Sequence="15"

Description="Says hello to the World!"

LabelText="Hello, World!"

TemplateAlias="cust1"/>

<Button

Id="Ribbon.CustomTabExample.CustomGroupExample.GoodbyeWorld"

Command="CustomTabExample.GoodbyeWorldCommand"

Sequence="17"

Description="Says good-bye to the World!"

LabelText="Good-bye, World!"

TemplateAlias="cust2"/>

<Button

Id="Ribbon.CustomTabExample.CustomGroupExample.LoveWorld"

Command="CustomTabExample.LoveWorldCommand"

Sequence="19"

Description="Says I love the World!"

LabelText="I love you, World!"

TemplateAlias="cust3"/>

</Controls>

</Group>

</Groups>

</Tab>

</CommandUIDefinition>

<Layout

Title="OneLargeTwoMedium"

LayoutTitle="OneLargeTwoMedium">

<Row>

</Row>

</Section>

<Row>

</Row>

<Row>

</Row>

</Section>

</Layout>

</GroupTemplate>

</CommandUIDefinition>

</CommandUIDefinitions>

<CommandUIHandler

Command="CustomTabExample.HelloWorldCommand"

CommandAction="javascript:alert('Hello, world!');" />

<CommandUIHandler

Command="CustomTabExample.GoodbyeWorldCommand"

CommandAction="javascript:alert('Good-bye, world!');" />

<CommandUIHandler

Command="CustomTabExample.LoveWorldCommand"

CommandAction="javascript:alert('I love you, world!');" />

</CommandUIHandlers>

</CommandUIExtension>

</CustomAction>

</Elements>

First Look: SharePoint 2010 Developer Documentation Now Live on MSDN!

Andrew May — Mon, 19 Oct 2009 19:59:00 GMT

By now you’ve probably been hearing some of the big news coming out of the SharePoint Developer Conference being held this week in Las Vegas. Doubtlessly, there’ll be tons more great information coming out of the Conference over the next four days concerning what’s new and notable in SharePoint Foundation 2010 and SharePoint Server 2010. But if you weren’t lucky enough to make it to Vegas this year, or are there but can’t wait for the session on your favorite area of SharePoint development, then have we got something you’ll want to take a close look at:

Introducing the SharePoint 2010 (Beta) Developer Center

That’s right, this morning we launched the SharePoint 2010 (Beta) Developer Center on MSDN. We’re using this new, combined Developer Center to give you your first detailed, public technical information and instruction around both SharePoint Foundation and SharePoint Server 2010. This new sub-site of the revamped SharePoint Developer Center highlights some early videos, documentation, and hands-on lab walkthroughs to introduce you to the exciting developer features on both SharePoint Foundation 2010 and SharePoint Server 2010.

But that‘s not all: we’ve also published a Beta release of the combined SharePoint 2010 SDK!

You’ll definitely want to spend some time on the site, getting ramped up for when the SharePoint 2010 Betas are released in November.

Learn SharePoint from the Ground Up

Of particular interest to developers new to SharePoint will be the Get Started Developing on SharePoint 2010. We’ve put together a series of 10 modules to help you get your feet wet on some of the main areas of SharePoint development, including:

· Building Web Parts

· What Developers Need to Know About SharePoint 2010

· Building Blocks for Web Part Development

· Accessing Data and Objects with Server-Side APIs

· Accessing Data and Objects with Client-Side APIs

· Accessing External Data with Business Connectivity Services

· Developing Business Processes with Workflows

· Creating Silverlight User Interfaces

· Sandboxed Solutions for Web Parts

· Creating Dialog Boxes and Ribbon Controls

Each module includes multiple video lessons, as well as code samples and hands-on lab walkthroughs, to give you a firm grounding in the topics covered.

Even experienced SharePoint developers will want to take a look at the modules that cover brand new development areas, like the client-side APIs, Silverlight user interfaces, sandboxed solutions, and the new ribbon user interface.

Get Your First Look at What’s New for Developers in SharePoint 2010

For an even deeper look at what’s new and notable in SharePoint Foundation and Server 2010, we’ve posted a Beta version of the combined SharePoint 2010 SDK. It’s packed with conceptual, procedural and reference material covering the major developmental areas of both Foundation and Server. All in all, it’s almost half a million words detailing how to develop SharePoint solutions.

For example, take a look here for what’s new in SharePoint Foundation 2010, including:

· Alerts Enhancements

· Business Connectivity Services

· Client Object Model

· Events Improvements

· Microsoft Synch Framework

· Mobile Device Development Enhancements

· Query Enhancements

· Ribbon

· Sandboxed Solutions

· Service Application Framework

· Silverlight Integration and the Fluid Application Model

· UI Improvements

· Windows PowerShell for SharePoint

· Workflow Improvements

And take a look here for what’s new in SharePoint Server 2010, including:

· User Profiles and Social Data

· Business Connectivity Services (BCS)

· Enterprise Content Management (ECM)

· SharePoint Enterprise Search

· PerformancePoint Services

· Excel Services

Some other places you might want to start:

· If you’re newer to SharePoint development, you might want to spend some time in the Getting Started and Building Blocks sections of the SDK, getting a firm grounding in the basics.

· If you’re coming to SharePoint from an ASP.NET development background, but sure and check out the Glide Path for ASP.NET Developers section, which is specifically aimed at developers transitioning from ASP.NET development to development on the SharePoint Foundation platform.

Let Us Know What You Want

Now, this SDK is a Beta release, so you’ll likely see some rough edges. But we’ve combined this SDK to cover both SharePoint Foundation and Server, and restructured it to present the continuum of SharePoint development in as logical and intuitive a way as we could. We then packed it with new and updated conceptual, procedural, and reference material.

We’d love to hear what you think of what we’ve done. As always, as you read through the SDK, if you spot issues, don’t see the information you need, or have suggestions, please drop us a line and let us know how we can improve our developer documentation. It’s easy; just do one of the following:

· Enter a comment in the MSDN ratings box

· Email us directly at docthis (at) Microsoft.com

· Email us through this blog

Be sure and check back here often (or even better, subscribe to our RSS feed), as we plan on using the blog to preview draft versions of additional SDK content as it gets written.

How We Address Developer Documentation Comments

Andrew May — Mon, 09 Jun 2008 19:01:00 GMT

One of the things I've wanted to do on this blog is give people a clearer view into how we actually produce developer documentation for SharePoint; the processes we use, the decisions we make, and what factors influence those decisions. (The Office client developer docs team have done several great posts over on the Office Client Developer Content blog around similar topics.) With that in mind, when someone asked me the other day what we actually do with those comments people enter for our content on MSDN, I figured it was worth answering here.

The short answer is: we collect, classify, and prioritize them for action, pretty much like a software product team would triage bugs entered against their product.

And here's the long answer:

For each comment, when we initially receive it we assign a status, which is further broken down by a sub-status value as well. This enables us to separate out and focus on the comments for which some action can be taken, and group those comments in terms of what’s being requested. The status and sub-status values we use include:

· New

This is the status automatically assigned to comments that haven’t been classified yet.

· In progress

Comments that contain actionable content. The comment has been initially triaged and prioritized.

o Code sample

User wants a code sample to illustrate what the topic covers.

o Incorrect/Incomplete info

User points out that there is incorrect or incomplete information in the topic. (Not surprisingly, these are usually our first priority to fix.)

o More Info

User is asking for more information to be added to the topic.

o More Research Needed

We need to do more research on the comment before we can accurately categorize it.

o New Topic Requested

User is asking for a new topic, separate from the topic where they added the comment.

· No Action

o Negative

Comments that are negative but not specific enough to be actionable.

o Noise

Unintelligible comments, such as random typing.

o Positive

Positive comment for which no action is necessary.

· Off-topic

Comments that don't apply to the topic itself, but might be actionable at another level.

o MSDN Issue

Comment refers to a wider MSDN issue.

o Noise

Comments that are intelligible, but have nothing to do with the topic ("I like cheese, do you like cheese?")

o Product Issue

Comment refers to a product issue, such as whether the user likes the feature the topic describes, rather than the documentation itself.

o SDK Issue

Comment refers to a larger issue concerning our content set, that might be present in the topic.

· Spam

Exactly what you'd expect: foreign financial scams, discounted prescriptions, offers to refinance our property at 1 Microsoft Way.

· Fixed

The actionable content of the comment has been addressed. For sub-status, we leave the value at what is was when the comment was In progress.

Once we’ve got them classified, we can properly triage those comments that require action, prioritizing them along with the other content feedback we get from newsgroups, blogs, MVPs, MSDN Community Content comments, internal and external partner groups, and various other channels.

Now that I’ve outlined what we do with the comments users enter, let’s take a quick look at what those comments actually say. So what are people telling us about the WSS SDK? Taking a look at the comments entered for the WSS 3.0 SDK since its publication online, here's how they currently break out, according to status:

As you can see, 46% of the comments actually require no action beyond the initial triage. Of the actionable comments, about two-thirds are still in some state of being worked on. Like I said, these comments are prioritized in with all the content suggestions we receive from other channels as well, so that our documentation team is working on the highest priority work items, regardless of the path it took to get to us.

Looking a little closer at the comments still in progress, here's what you get when you break down those comments by sub-status:

Users are overwhelmingly (78% of the total) asking for more information (52%) or code samples (26%). This is in line with feedback we’ve been getting through other channels, and is something we’ve been actively working to address.

When you include the comments we've fixed, here are the classifications for all actionable comments we've received to date:

One other metric we periodically look at is the trend of the positive and negative comments over time. I'm really happy to see that as we periodically republish the SDK with new, expanded, and revised material, positive comments have tended to increase at a faster rate than negative ones:

We do some additional data analysis on comments, but that’s the basics. So next time you’re looking at developer documentation on MSDN, take a moment to enter a comment to let us know how we’re doing. I guarantee we’re on the other end, listening.

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

RickK — Fri, 08 Feb 2008 04:08:00 GMT

Introduction

If you have a custom content component that you want to be included in Windows SharePoint Server 3.0 backups and restores, you must represent the component with a class that implements the IBackupRestore interface. This post explains how to do that. There is a complete example following the procedures. This post assumes that you are familiar with my earlier post: Programming with the Windows SharePoint Services Backup/Restore Object Model.

Note: Unless explicitly stated otherwise, all classes and interfaces referred to in this post are in the Microsoft.SharePoint.Administration.Backup namespace. Classes that you will create are in bold pink. Also, this post refers at times to the “reference topic” for this or that method/property for supplementary information. As of the date of this posting these reference topics in the most recent versions of the WSS SDK (1.3), in either download or MSDN form, did not yet contain this new material. Look for another update soon. The additional information is not necessary for using this post as a learning exercise or implementing the example it contains.

Your class does not have to derive from Microsoft.SharePoint.Administration.SPPersistedObject but if your content is a database, we recommend that you derive your class from either Microsoft.SharePoint.Administration.SPDatabase or from Microsoft.SharePoint.Administration.SPContentDatabase. Both of the latter classes are derived from SPPersistedObject and both implement IBackupRestore. Therefore, you will have default implementations of members of IBackupRestore that you can use when appropriate.

You can create as many types of IBackupRestore classes you want and, if you want, they can be nested as a tree of component classes. But the highest class in any such tree must derive (directly or indirectly) from SPPersistedObject object and must be a child of Microsoft.SharePoint.Administration.SPFarm. If your content class is not a child of any other custom content class, it must derive (directly or indirectly) from SPPersistedObject object and must be a child of SPFarm.

If your class derives from a class that already implements IBackupRestore object (whether or not it derives from SPPersistedObject), and you want to replace an inherited implementation of an IBackupRestore member, your class declaration should explicitly reference IBackupRestore like this:

[C#]

public class MyClass : SPPersistedObject, IBackupRestore

Your "override" of any IBackupRestore member should explicitly include "IBackupRestore" in the member name and it should not include the public keyword. The following is an example:

[C#]

UInt64 IBackupRestore.DiskSizeRequired { ... }

Alternatively, if the implementation of the member in the parent class used the virtual or override keywords, you can use the override keyword in your implementation like this:

[C#]

public override UInt64 DiskSizeRequired { ... }

Warning: Do not hide the inherited member implementation by redeclaring the member either with or without the new keyword ([new] public UInt64 DiskSizeRequired { ... }). In the procedure below, the member signatures are written as they would be for a class that does not derive from a class that already implements IBackupRestore. Be sure to change them to the required pattern if your class does derive from such a parent.

If your class derives from SPPersistedObject, let the Id and Name properties of that class serve as the implementation of the IBackupRestore.Id and IBackupRestore.Name properties. You may override the properties, but do not create a second implementation of either of them. Your class should have just one Name and one Id property.

Procedures

To Implement the Members of IBackupRestore

1. Begin a new Class project in Visual Studio.

2. 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 your class file.

3. If your class does not derive from SPPersistedObject, implement the IBackupRestore.Name property. This will serve as the name of the content component in the UI of stsadm.exe, the Central Administration application and the UI of any custom backup and restore application. In most cases you implement the property by creating a private field for the name value and implement the public property as a wrapper around the field. For information on possible variant implementations, see the reference topic for the property.

[C#]

private String name;

public String Name

{

get {return name;}

set {name = value;}

}

4. If your class does not derive from SPPersistedObject, implement the IBackupRestore.Id property. In most cases, you implement the property by creating a private field for the name value and implement the public property as a wrapper around the field. For information on possible variant implementations, see the reference topic for the property.

[C#]

private Guid id;

public Guid Id

{

get {return id;}

set {id = value;}

}

5. Implement the IBackupRestore.DiskSizeRequired property. If your class is just a container for some child IBackupRestore classes, the property should return 0. Otherwise, the property should calculate the size of the content. (Include the size of any non-IBackupRestore child objects, but do not include the size of any child IBackupRestore objects. They each have their own IBackupRestore.DiskSizeRequired property and Windows SharePoint Server 3.0 will add those values in automatically.) The following example sums the sizes of all the files whose paths are contained in a collection called FrontEndFilePaths.

[C#]

public UInt64 DiskSizeRequired

{

get

{

UInt64 total = 0;

List<FileInfo> FrontEndFiles = new List<FileInfo>(NUMBER_OF_FILES_TO_BACK_UP);

foreach (String path in FrontEndFilePaths)

{

FileInfo file = new FileInfo(path);

FrontEndFiles.Add(file);

}

foreach (FileInfo file in FrontEndFiles)

{

total = total + (UInt64)file.Length;

}

return total;

}

6. Implement the IBackupRestore.CanSelectForBackup property. If users should never be able to backup objects of your class independently of a backup of the parent object, the get accessor should return false. If users should always be able to select any object of your class for independent backup, the get accessor should return true. In either case, the set accessor should be an empty pair of braces "{ }". If some objects of your class can be backed up independently of their parent, but some cannot be, implement the property as a wrapper around a private System.Boolean field.

7. Implement the IBackupRestore.CanSelectForRestore property. If users should never be able to restore objects of your custom component class independently of a restoration of the parent object, the get accessor should return false. If users should always be able to select any object of your class for independent restoration, the get accessor should return true. In either case, the set accessor should be an empty pair of braces "{ }". If some objects of your class can be restored independently of their parent, but some cannot be, implement the property as a wrapper around a private System.Boolean field.

8. Implement the IBackupRestore.CanRenameOnRestore property. If users should never be able to restore objects of your custom component class to a new location, the get accessor should return false. If users should be able to migrate any object of your class, the get accessor should return true. If objects of your class can sometimes be migrated, but not always, implement the property as a wrapper around a private System.Boolean field.

9. Implement the IBackupRestore.AddBackupObjects method.

a. Your implementation code should begin by throwing an exception if there is no valid parent to which the component can be added.

b. Use the SPBackupRestoreObject.AddChild method to add your component to the tree of objects that the backup or restore operation will process.

c. Use the SPBackupRestoreInformation.SetParameter method to specify a type name and description of the component that can be used by the UI of backup/restore applications.

d. If the component has child IBackupRestore objects, your implementation should iterate through them and recursively call the IBackupRestore.AddBackupObjects method of each child.

e. See the reference topic for the IBackupRestore.AddBackupObjects method for more ideas about implementations of it.

The following example code assumes that your content class has a ChildContentCollection of child IBackupRestore objects. If your class has more than one type of child component, you may have separate collections for each type and iterate through each collection.

[C#]

public void AddBackupObjects(SPBackupRestoreObject parent)

{

if (parent == null)

{

throw new ArgumentNullException("parent");

}

SPBackupRestoreObject self = parent.AddChild(this);

self.Information.SetParameter(SPBackupRestoreObject.SPTypeName, this.GetType());

self.Information.SetParameter(SPBackupRestoreObject.SPDescription,

"Description of custom content component");

foreach (ChildContent child in ChildContentCollection)

{

IBackupRestore childIBR = child as IBackupRestore;

childIBR.AddBackupObjects(self);

}

10. Implement the IBackupRestore.OnAbort method. It should always return true. In most cases it should do nothing more, but see the reference topic for IBackupRestore.OnAbort for information about exceptions to this general rule.

11. Implement the IBackupRestore.OnPrepareBackup method. At a minimum, you should use the SPBackupRestoreInformation.SetParameter method to specify a name for the content object. Beyond that, few generalizations can be made. See the reference topic for IBackupRestore.OnPrepareBackup for more information. The following example shows a minimal implementation of the method, which is often all that is needed.

[C#]

public Boolean OnPrepareBackup(Object sender, SPBackupInformation args)

{

if (args == null)

}

throw new ArgumentNullException("args");

}

args.SetParameter(SPBackupRestoreObject.SPName, this.Name);

return true;

}

12. Implement the IBackupRestore.OnBackup method. If your content class has no content outside of any IBackupRestore child objects it may have, your implementation should simply set the SPBackupRestoreInformation.CurrentProgess to a value that approximately represents the percentage of the total backup operation time that is consumed by the IBackupRestore.OnBackup and IBackupRestore.OnPrepareBackup methods. It should then return true as seen in the following example. Do not call the IBackupRestore.OnBackup method of any IBackupRestore child objects.

[C#]

public Boolean OnBackup(Object sender, SPBackupInformation args)

{

if (args == null)

{

throw new ArgumentNullException("args");

}

args.CurrentProgress = 50;

return true;

}

If your class does have content outside of any IBackupRestore child objects it may have, your implementation must copy this content to args.SPBackupRestoreInformation.Location and return false if the copy fails. You should include logic to backup any child objects that do not implement IBackupRestore, but you should not explicitly backup any child objects that do implement IBackupRestore. They will be backed up by their own IBackupRestore.OnBackup method, which the runtime will call. You should not call the IBackupRestore.OnBackup methods of the child objects in your own code. The following example shows the overall structure of a substantive implementation of IBackupRestore.OnBackup.

[C#]

public Boolean OnBackup(Object sender, SPBackupInformation args)

{

if (args == null)

{

throw new ArgumentNullException("args");

}

args.CurrentProgress = 50;

Boolean successSignal = true;

// TODO: Implement copying your content to args.Location

// If the copy fails, set successSignal to false.

return successSignal;

}

13. Implement the IBackupRestore.OnBackupComplete method. At a minimum, your implementation should set SPBackupRestoreInformation.CurrentProgess to 100 percent and return true as shown in the following example. This is typically all that is required. For information about other work your implementation may need to perform, see the reference topic for IBackupRestore.OnBackupComplete.

[C#]

public Boolean OnBackupComplete(Object sender, SPBackupInformation args)

{

if (args == null)

{

throw new ArgumentNullException("args");

}

args.CurrentProgress = 100;

return true;

}

14. Implement the IBackupRestore.OnPreRestore method. In most situations, a restoration operation requires no preparation and your implementation of IBackupRestore.OnPreRestore should just return true. For information about other work your implementation may need to perform, see the reference topic for IBackupRestore.OnPreRestore.

15. Implement the IBackupRestore.OnRestore method.

· If your content class can be migrated, your code should check to see what the restore method is and call SPBackupRestoreInformation.Rename if the method is New.

· If your content class has no content outside of any IBackupRestore child objects it may have, your implementation should simply set the SPBackupRestoreInformation.CurrentProgess to a value that approximately represents the percentage of the total restore operation time that is consumed by the IBackupRestore.OnRestore and the IBackupRestore.OnPreRestore methods. It should then return true as seen in the following example. Do not call the IBackupRestore.OnRestore method of any IBackupRestore child objects.

[C#]

public Boolean OnRestore(Object sender, SPRestoreInformation args)

{

if (args == null)

{

throw new ArgumentNullException("args");

}

if (args.RestoreMethod == SPRestoreMethodType.New)

{

args.Rename();

}

args.CurrentProgress = 50;

return true;

}

· If your class does have content outside of any IBackupRestore child objects it may have, your implementation must copy this content to the restoration destination. Return false, if for any reason the copy of content fails.

The following example shows the overall structure of a substantive implementation of IBackupRestore.OnRestore:

[C#]

public Boolean OnRestore(Object sender, SPRestoreInformation args)

{

if (args == null)

{

throw new ArgumentNullException("args");

}

if (args.RestoreMethod == SPRestoreMethodType.New)

{

args.Rename();

}

args.CurrentProgress = 50;

Boolean successSignal = true;

// TODO: Implement copying your content to the destination.

// If the copy fails, set successSignal to false.

return successSignal;

}

16. Implement the IBackupRestore.OnPostRestore method. At a minimum, your implementation should set SPBackupRestoreInformation.CurrentProgess to 100 percent and return true as shown in the following example. This is typically all that is required. For information about other work your implementation may need to perform, see the reference topic for IBackupRestore.OnPostRestore.

[C#]

public Boolean OnPostRestore(Object sender, SPRestoreInformation args)

{

if (args == null)

{

throw new ArgumentNullException("args");

}

args.CurrentProgress = 100;

return true;

}

Add other Members to Your Class As Needed

17. Add fields, properties, and helper methods as needed to complete your class. As you work, keep these points in mind:

· Use fields and properties to hold child content objects.

· If your class derives from Microsoft.SharePoint.Administration.SPPersistedObject, then the declaration of fields that you want to persist in the configuration database must be preceded with the [Persisted] attribute. However, you can only mark the following types of fields in this way: primitive types such as strings, integers, and GUIDs; other Microsoft.SharePoint.Administration.SPPersistedObject objects or Microsoft.SharePoint.Administration.SPAutoserializingObject objects; or collections of any of the above. For example, the class cannot have a System.IO.FileInfo field marked with the [Persisted] attribute. If the data you would like to persist is not of a persistable class, use a persistable substitute. The sample implementation above of the IBackupRestore.DiskSizeRequired property envisions a class that persists a collection of file names and uses them to create a temporary collection of System.IO.FileInfo objects at runtime.

· If your class can have multiple children of the same type, create a property or field of a collection type or other enumerable type to hold a collection of all children of a given type. This is particularly important if the child type itself implements IBackupRestore, because your implementation of the IBackupRestore.AddBackupObjects method should iterate through such children and call the IBackupRestore.AddBackupObjects method of each child. See the procedure step for implementing the IBackupRestore.AddBackupObjects method above, for more information.

18. Add constructors to your class to initialize its fields and properties as needed. If the class derives from SPPersistedObject, there must be at least one constructor that names the object and assigns it to a parent. Typically, such a constructor takes at least these two arguments:

· A String argument that will be the name of the content object.

· An SPPersistedObject argument that represents the parent of the content object.

This constructor must call the base constructor that takes the same two arguments. The following is an example:

[C#]

public MyContentComponent(String componentName, SPPersistedObject parent, SomeType someOtherArgument, ... )

: base(componentName, parent)

{

somePrivateField = someOtherArgument;

...

}

You must pass Microsoft.SharePoint.Administration.SPFarm.Local as the parent when the content object is the top most object in a tree of custom IBackupRestore objects. If your custom component type is always the top most object, then leave out the SPPersistedObject argument and hard code a reference to SPFarm.Local in the call to the base constructor. The following is an example:

[C#]

public MyContentComponent(String componentName, SomeType someOtherArgument, ... )

: base(componentName, SPFarm.Local)

{

somePrivateField = someOtherArgument;

...

}

If objects of your class always have the same name, you can leave out the String argument and hard code the name in the call to the base constructor. (If all objects of a given type have the same name, there should never be more than one child of that type for a given parent and; thus, no more than one object of that type on the entire farm if the object is a child of the farm.)

19. Compile your class project.

Warning: You must give the assembly a strong name and put the assembly in the General Assembly Cache (GAC).

To Create an Object of Your Class and Make it a Child of the Farm

20. Start a new console application project in Visual Studio.

21. Add a reference to the DLL of your custom component class to the project.

22. Add a using statement for Microsoft.SharePoint.Administration.

23. Add a using statement for the namespace that you used in your custom component class (or just use the same namespace in your console application).

24. Add to the Main method of your project a call to the constructor of your custom component class. If you created a hierarchy of custom types, call the constructor of the top most class.

25. If needed, precede the call to the constructor of the component with code that creates parameters for the constructor.

26. After the call to the constructor of your component, your code should call the component object's SPPersistedObject.Update method. The following is an example of what you should have in the Main method:

[C#]

MyContentComponent myContentObject = new MyContentComponent("component name", SPFarm.Local);

myContentObject.Update();

27. Compile and run the application.

28. In the Central Administration application navigate to Operations | Perform a Backup. Your object should appear as child of the farm on the Perform a Backup page.

Note: There is a sample console application for creating and deleting custom content objects in the Example section below.

Development Advice

The following tips may be helpful as you develop your custom content classes particularly because you will probably be creating objects and adding them to the farm multiple times as you work.

Points to Keep in Mind

1. If you need to delete your object from the configuration database, use SPPersistedObject.Delete.

2. An exception is thrown if you call obj.Update() and there is already an object of the same class as obj with the same SPPersistedObject.Name property value and the same parent in the configuration database. There is an overloaded version of SPPersistedObject.Update that may be preferable.

3. There is an example console application in the second Example section below that can be used to add or delete your custom objects from the configuration database.

4. Run iisreset at the command line after every recompile of your IBackupRestore class. You may need to reboot the server as well.

5. The various IBackupRestore.On* methods take either a SPBackupInformation parameter or a SPRestoreInformation parameter. You can use their members for debugging purposes. Particularly helpful is the SPBackupRestoreInformation.Log method.

Example

The following code implements a custom content component that represents a single Web.config file on a front end server. Replace the TestSite part of the file path in the constructor implementation with a directory name from your test server. The compiled assembly must be strong-named and installed in the GAC.

In the example following the class implementation, there is the code for a simple console application that will register the component as a child of the farm or delete it from the farm.

using System;

using System.IO;

using System.Collections.Generic;

using Microsoft.SharePoint.Administration;

using Microsoft.SharePoint.Administration.Backup;

namespace MyCompany.SharePoint.Administration

{

public class CriticalFiles : SPPersistedObject, IBackupRestore

{

public CriticalFiles() { }

public CriticalFiles(String componentName, SPPersistedObject parent)

: base(componentName, parent)

{

String pathOfFile = @"C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS\TestSite\Web.config";

FrontEndFilePaths.Add(pathOfFile);

}

[Persisted]

private const Int32 NUMBER_OF_FILES_TO_BACK_UP = 1;

[Persisted]

private List<String> FrontEndFilePaths = new List<String>(NUMBER_OF_FILES_TO_BACK_UP);

public Boolean CanSelectForBackup

{

get { return true; }

set { }

}

public Boolean CanSelectForRestore

{

get { return true; }

set { }

}

public Boolean CanRenameOnRestore

{

get { return false; }

}

public UInt64 DiskSizeRequired

{

get

{

UInt64 total = 0;

List<FileInfo> FrontEndFiles = new List<FileInfo>(NUMBER_OF_FILES_TO_BACK_UP);

foreach (String path in FrontEndFilePaths)

{

FileInfo file = new FileInfo(path);

FrontEndFiles.Add(file);

}

foreach (FileInfo file in FrontEndFiles)

{

total = total + (UInt64)file.Length;

}

return total;

}

public void AddBackupObjects(SPBackupRestoreObject parent)

{

if (parent == null)

{

throw new ArgumentNullException("parent");

}

SPBackupRestoreObject self = parent.AddChild(this);

self.Information.SetParameter(SPBackupRestoreObject.SPTypeName, this.GetType());

self.Information.SetParameter(SPBackupRestoreObject.SPDescription, "The critical files on all front end servers.");

}

public Boolean OnAbort(Object sender, SPBackupRestoreInformation args)

{

return true;

}

public Boolean OnPrepareBackup(Object sender, SPBackupInformation args)

{

if (args == null)

{

throw new ArgumentNullException("args");

}

args.SetParameter(SPBackupRestoreObject.SPName, this.Name);

return true;

}

public Boolean OnBackup(Object sender, SPBackupInformation args)

{

if (args == null)

{

throw new ArgumentNullException("args");

}

Boolean successSignal = true;

foreach (String path in FrontEndFilePaths)

{

FileInfo file = new FileInfo(path);

try

{

String mappedFileName = args.GenerateFileMapping(file.Name);

file.CopyTo(args.Location + @"\" + mappedFileName, true);

args.Log(SPBackupRestoreLogSeverity.Verbose, "Backed up " + file.Name + " in (" + mappedFileName + ")");

}

catch (Exception e)

{

args.Log(SPBackupRestoreLogSeverity.Verbose, file.Name + " not backed u " + e.Message);

successSignal = false;

}

args.CurrentProgress = 50;

return successSignal;

}

public Boolean OnBackupComplete(Object sender, SPBackupInformation args)

{

if (args == null)

{

throw new ArgumentNullException("args");

}

args.CurrentProgress = 100;

return true;

}

public Boolean OnPreRestore(Object sender, SPRestoreInformation args)

{

if (args == null)

{

throw new ArgumentNullException("args");

}

return true;

}

public Boolean OnRestore(Object sender, SPRestoreInformation args)

{

if (args == null)

{

throw new ArgumentNullException("args");

}

// If the CriticalFiles object was deleted from the farm after it was

// backed up, restore it to the configuration database.

CriticalFiles cf = SPFarm.Local.GetChild<CriticalFiles>(this.Name);

if (cf == null)

{

this.Update();

args.Log(SPBackupRestoreLogSeverity.Verbose, this.Name + " added back to configuration database.");

}

Boolean successSignal = true;

// TODO: The following loop restores files to the local server. If there are

// multiple front end servers, your code must iterate through all of

// SPFarm.Local.Servers and restore the same files to every server whose

// Role property is SPServerRole.WebFrontEnd

foreach (String path in FrontEndFilePaths)

{

FileInfo backupCopy = new FileInfo(path);

String mappedFileName = args.ReverseFileMapping(backupCopy.Name);

FileInfo file = new FileInfo(args.Location + @"\" + mappedFileName);

try

{

file.CopyTo(path, true);

args.Log(SPBackupRestoreLogSeverity.Verbose, "Restored " + backupCopy.Name);

}

catch (Exception e)

{

args.Log(SPBackupRestoreLogSeverity.Verbose, file.Name + " not restored: " + e.Message);

successSignal = false;

}

args.CurrentProgress = 50;

return successSignal;

}

public Boolean OnPostRestore(Object sender, SPRestoreInformation args)

{

if (args == null)

{

throw new ArgumentNullException("args");

}

args.CurrentProgress = 100;

return true;

}

Description

The following is a console application that will add or delete your content object from the configuration database.

using System;

using System.Collections.Generic;

using System.Text;

using Microsoft.SharePoint.Administration;

using Microsoft.SharePoint.Administration.Backup;

namespace MyCompany.SharePoint.Administration

{

class Program

{

static void Main(string[] args)

{

CriticalFiles cf = SPFarm.Local.GetChild<CriticalFiles>("Critical Front End Files");

if (cf == null)

{

Console.WriteLine("There is no CriticalFiles object in the configuration database.");

Console.Write("Enter 'A' to add it. Press Return to do nothing:");

String response = Console.ReadLine();

if (response == "A")

{

CriticalFiles myCriticalFiles = new CriticalFiles("Critical Front End Files", SPFarm.Local);

myCriticalFiles.Update();

}

else

{

Console.WriteLine("There is a CriticalFiles object in the configuration database.");

Console.Write("Enter 'D' to delete it. Press Return to do nothing:");

String response = Console.ReadLine();

if (response == "D")

{

cf.Delete();

}

}// end Main

}// end Program

}

How to: Programmatically Back Up and Restore a Single Site Collection

RickK — Fri, 08 Feb 2008 03:18:00 GMT

Introduction

This post describes how to back up and restore individual site collections programmatically.

Note: Unless explicitly stated otherwise, all classes referred to in this post are in the Microsoft.SharePoint.Administration or Microsoft.SharePoint namespaces (not Microsoft.SharePoint.Administration.Backup).

Procedures

To Back Up or Restore a Site Collection

1. Add to your Visual Studio project a reference to Windows SharePoint Services.

2. Add using statements for Microsoft.SharePoint and Microsoft.SharePoint.Administration.

3. Add the following lines to obtain a reference to the farm and its collection of services.

[C#]

SPFarm myFarm = SPFarm.Local;

SPServiceCollection myServices = myFarm.Services;

4. Obtain a reference to the Web service that publishes the Web application that hosts your site collection by using the service's System.Guid which is the value of its SPWebService.Id property.

[C#]

Guid serviceID = new Guid("21d91b29-5c5b-4893-9264-4e9c758618b4");

SPWebService webPubService = (SPWebService)myServices[serviceID];

If you do not know the SPWebService.Id of the application publishing Web service, you can iterate through all the services and report their SPWebService.Name, SPWebService.TypeName, and SPWebService.Id. The following is an example:

[C#]

foreach (SPService service in myServices)

{

if (service is SPWebService)

{

Console.WriteLine("Web service name:" + webService.Name);

Console.WriteLine("Web service type:" + webService.TypeName);

Console.WriteLine("Web service ID:" + webService.Id);

Console.WriteLine();

Console.Readline();

}

5. Obtain a reference to the Web application that hosts your site collection. If you know the URL of the Web application you can obtain a reference with the static SPWebApplication.Lookup method. Alternatively, you can use the application's System.Guid which is the value of its SPWebApplication.Id property. The following code shows the second method.

[C#]

SPWebApplicationCollection myApps = webPubService.WebApplications;

Guid appID = new Guid("10ea4e6f-ae37-4909-b04f-f516c066bc37");

SPWebApplication myApp = myApps[appID];

If you do not know the SPWebApplication.Id of the Web application that hosts your site collection, you can iterate through all the Web applications and report their SPWebApplication.Name, SPWebApplication.TypeName, and SPWebApplication.Id. The following is an example:

[C#]

foreach (SPWebApplication app in webApps)

{

Console.WriteLine("Web application name:" + app.Name);

Console.WriteLine("Web application type:" + app.TypeName);

Console.WriteLine("Web application ID:" + app.Id);

Console.WriteLine();

Console.Readline();

}

6. Get a reference to the Web application's collection of site collections.

[C#]

SPSiteCollection mySiteCols = myApp.Sites;

7. To back up a site collection, call the SPSiteCollection.Backup method. As parameters pass the following:

· The full URL of the site collection; that is, the full URL of its Top Level Web site.

· The full path and file name of the file that will hold the compressed content of the site collection.

· True, if the operation should overwrite an existing backup file of the same name; false, if it should not.

[C#]

mySiteCols.Backup(@"htt//Server/sites/MySiteCollection", @"\\OtherServer\WSSBackups\SiteCollections\BackupOfMySiteCollection", true);

8. To restore a site collection, call the SPSiteCollection.Restore method. It takes the same parameters as the SPSiteCollection.Backup method. The Boolean parameter indicates whether the site collection should be overwritten if it already exists at the specified URL.

[C#]

mySiteCols.Restore(@"htt//Server/sites/MySiteCollection", @"\\OtherServer\WSSBackups\SiteCollections\BackupOfMySiteCollection", true);

Example

The following example shows a simple way to programmatically back up or restore a site collection. You will need to replace all the System.Guid values with actual values from your deployment and replace the placeholder values in the Backup and Restore methods with actual URLs and paths from your deployment.

// Get a reference to the Web application publishing

// Web service.

SPFarm myFarm = SPFarm.Local;

SPServiceCollection myServices = myFarm.Services;

Guid serviceID = new Guid("21d91b29-5c5b-4893-9264-4e9c758618b4");

SPWebService webPubService = (SPWebService)myServices[serviceID];

// Get a reference to the Web application that hosts the

// site collection.

SPWebApplicationCollection myApps = webPubService.WebApplications;

Guid appID = new Guid("10ea4e6f-ae37-4909-b04f-f516c066bc37");

SPWebApplication myApp = myApps[appID];

// As alternative to the preceding three lines, you can use

// the following when you know the URL of the Web application:

// SPWebApplication myApp = SPWebApplication.Lookup(url_of_Web_app)

// Get a reference to the Web application's collection of

// site collections.

SPSiteCollection mySiteCols = myApp.Sites;

// Back up a specified site collection.

mySiteCols.Backup(@"htt//Server/sites/MySiteCollection", @"\\OtherServer\WSSBackups\SiteCollections\BackupOfMySiteCollection", true);

// Restoring the site collection is identical to the preceding

// code except that the "Restore" is used in place of "Backup".

// mySiteCols.Restore(@"htt//Server/sites/MySiteCollection", @"\\OtherServer\WSSBackups\SiteCollections\BackupOfMySiteCollection", true);

Comments

The Microsoft.SharePoint.SPSite class does not implement Backup.IBackupRestore and the SPSiteCollection.Backup and SPSiteCollection.Restore methods do not use the facilities of the Microsoft.SharePoint.Administration.Backup namespace. This means that records of backups and restorations of site collections are not kept in a history file (spbrtoc.xml) in the backup directory. Similarly, backup and restoration data is not stored in spbackup.xml or sprestore.xml files, neither are these site collection operations logged in spbackup.log or sprestore.log files.

If you want to do any kind of logging of backups and restorations of site collection operations, you will have to program your own system. Writing to the system-created spbrtoc.xml, spbackup.xml, sprestore.xml, spbackup.log, and sprestore.log files is not supported in Windows SharePoint Services 3.0. Neither is moving them, deleting them, or renaming them. However, you can create files that merge data from the system-created files with data from your site collection backups and restorations.

How to: Programmatically Restore Content

RickK — Fri, 08 Feb 2008 02:50:00 GMT

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

How to: Programmatically Back Up Content

RickK — Fri, 08 Feb 2008 02:22:00 GMT

Introduction

This post explains how to program a backup of a content component, including custom components, in 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 Back Up a Content Component

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

[C#]

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

String backupLocation = Console.ReadLine();

3. Inside the Main method, create a SPBackupSettings object by using the static SPBackupRestoreSettings.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.

[C#]

SPBackupSettings settings = SPBackupRestoreSettings.GetBackupSettings(backupLocation, "Full");

4. Prompt the user to specify the content component to back up and assign its name to the SPBackupRestoreSettings.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 SPBackupRestoreSettings.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 SPBackupRestoreConsole.FindItems method in step 8.)

[C#]

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

settings.IndividualItem = Console.ReadLine();

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

[C#]

settings.IsVerbose = true;

settings.UpdateProgress = 10;

settings.BackupThreads = 2;

6. Create the backup operation with the SPBackupRestoreConsole.CreateBackupRestore method. (A history object for the operation is also created. For more information, see SPBackupRestoreHistoryObject and SPBackupRestoreHistoryList.)

[C#]

Guid backup = SPBackupRestoreConsole.CreateBackupRestore(settings);

7. 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 backup);

8. 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;

}

9. 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.

[C#]

Boolean targetHasEnoughSpace = false;

if (node != null)

{

targetHasEnoughSpace = EnsureEnoughDiskSpace(backupLocation, backup, node);

}

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

[C#]

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;

}

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

[C#]

if (targetHasEnoughSpace)

{

// TODO: Set the backup operation as the active operation

// and run it.

}

12. 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(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.");

}

13. 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(backup, node) == false)

{

// Report "error" through your UI.

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

Console.WriteLine(error);

}

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

[C#]

// 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

Programming with the Windows SharePoint Services Backup/Restore Object Model

RickK — Fri, 08 Feb 2008 00:49:00 GMT

Introduction

This post 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.

Note: All classes in this post are in the Microsoft.SharePoint.Administration.Backup namespace unless specified otherwise.

The Backup and Restore Object Model

At the top of the object model is the SPBackupRestoreConsole class. (See ①, 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.

There is always just one object of this class 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.

Each particular backup or restore operation is represented by an object of the class SPBackupRestoreConsoleObject that is created by the SPBackupRestoreConsole.CreateBackupRestore method of the console object. (See ②, 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 his being backed up or restored. These objects also have an SPBackupRestoreConsoleObject.Id property of type System.Guid that serves as a handle for the object that can be passed to the methods of SPBackupRestoreConsole. For example, SPBackupRestoreConsole.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 SPBackupRestoreConsoleObject.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.

While the SPBackupRestoreConsoleObject objects represent operations, the content components themselves are represented by SPBackupRestoreObject objects. (See ③, in Figure 1.) These objects can be nested with the SPBackupRestoreObject.Children property. Therefore, each one represents a tree of one or more content components. For example, a Web application would be represented by a by SPBackupRestoreObject object that would have each of the Web application's content databases as child SPBackupRestoreObject objects. The tree of components that are the subject a particular backup or restore operation is 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 SPBackupRestoreConsole.GetRoot method.

A SPBackupRestoreObject object is a container for two critical types of objects:

· In its SPBackupRestoreObject.Information property the SPBackupRestoreObject object holds either a SPBackupInformation or a 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 and deriving a new class from their parent, SPBackupRestoreInformation, is not supported.

· In its SPBackupRestoreObject.IBackupRestore property the SPBackupRestoreObject object holds an object that implements the IBackupRestore interface (and might also inherit from Microsoft.SharePoint.Administration.SPPersistedObject). (See ④, 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 IBackupRestore.OnBackup and IBackupRestore.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 SPBackupRestoreConsole.CreateBackupRestore method when an operation is created. (See ⑤, in Figure 1.) Each of these objects holds settings for use in operations; most importantly, they identify, in their SPBackupRestoreSettings.IndividualItem property, the content component that is the subject of the backup or restore operation. (See ⑥, in Figure 1.)

Programming Advice

Ways of Customization

Most of the critical classes in the backup restore object model are sealed (NotInheritable in 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 will use 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 Microsoft.SharePoint.Administration.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 will be logged in spbackup.log or sprestore.log in the backup location.

Backups and Restores of Site Collections

Aside from 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 Microsoft.SharePoint.Administration.SPSiteCollection.Backup(System.String,System.String,System.Boolean) and Microsoft.SharePoint.Administration.SPSiteCollection.Restore(System.String,System.String,System.Boolean). For more information on backing up and restoring site collections, see How to: Programmatically Backup and Restore a Single Site Collection.

Overview of Backing Up and Restoring Data in Windows SharePoint Services

RickK — Thu, 24 Jan 2008 01:11:00 GMT

Introduction

This post provides some basic facts about backing up and restoring data in Windows SharePoint Services 3.0. It will serve as background information for several developer-oriented posts that I will create in the next couple of weeks.

Note: Unless explicitly stated otherwise, all classes and members referenced in this post are in the Microsoft.SharePoint.Administration.Backup namespace.

What Can Be Backed Up and What Can Be Restored

There are six types of content components built-in to Windows SharePoint Services 3.0 that can be backed up and restored through either the Central Administration application's UI, the Stsadm.exe Command-line Tool or a custom application that uses the Windows SharePoint Services 3.0 backup and restore object model.

· Site collections, each of which might contain multiple Web sites.

· Content databases, each of which might contain multiple site collections.

· Web applications, each of which might contain multiple content databases.

· Content publishing "Web services," each of which might contain multiple Web applications.

Note: This refers to content publishing "Web services" (which are really partitions of content) that are represented in the object model by Microsoft.SharePoint.Administration.SPWebService objects. It does not refer to the functional Web services in the more common sense of "Web service," such as the Alerts (websvcAlerts) service or the Meetings (websvcMeetings) service. For more information about content publishing "Web services," see Server and Site Architecture: Object Model Overview and The High Level Object Model of Windows SharePoint Sevices 3.0 (to be published on MSDN).

· Search Windows service including its databases and indexes.

Note: This does not refer to the Search Web service websvcSPSearch.

· A whole Windows SharePoint Services farm.

If an enhanced functionality product such as Office SharePoint Server 2007 has been installed in addition to Windows SharePoint Services 3.0 and that product includes Shared Service Providers, then they can also be backed up and restored with Windows SharePoint Services 3.0.

In addition, you can create new types of content objects that can be backed up and restored by implementing the IBackupRestore interface.

Limitations

There are some limitations on what can be backed up and restored through either the Central Administration application's UI, the stsadm command line utility or a custom application that uses the Windows SharePoint Services 3.0 backup and restore object model.

· You cannot backup (or restore) an individual Web site, list, or list item except by backing up (or restoring) the entire site collection to which it belongs.

· You cannot back up a Windows SharePoint Services farm's configuration database or the content database of the Central Administration application except by backing up the whole farm.

· You cannot restore a farm's configuration database or the content database of the Central Administration application. The backups of these components that are included in a backup of a farm provide a snapshot of these components at the time of the backup. Such snapshots might be useful for troubleshooting because they can be used to compare with the present state of the components using SQL Server tools. (There is an exception to this point: you can restore the configuration database and the content database of the Central Administration application if you are using the Volume Shadow Copy Service – VSS - of Windows Server 2003/2008).

· You cannot back up the Internet Information Server (IIS) metabase.

The following kinds of content cannot be backed up with either the Central Administration application's UI or the stsadm command line utility, but you can create custom backup solutions with the Windows SharePoint Services SDK that include these types of content.

· Registry keys.

· Files that live on the front-end servers; that is, outside any content database, such as certain master pages, .ascx files, web.config files, and other configuration files.

Types of Backups and Restorations

Backups of a given component can be either full or incremental. In the latter case, only parts of the component that have changed since the last full backup are backed up.

Note: A Windows SharePoint Services Search index cannot be incrementally backed up. If a search index is included in an incremental backup job, the index will get a full backup.

Restorations can either overwrite the original backup source or they can be to a new location. This means that the backup and restore functionality in Windows SharePoint Services 3.0 can also be used as a method of migrating content components.

Two Kinds of Custom Backup Applications

There are two ways to use the Windows SharePoint Services object model to create custom backup applications.

The Main Backup and Restore Object Model

You can create a backup and restore application by using the main backup and restore object model, sometimes called "catastrophic" backup/restore. This is located mainly in the Microsoft.SharePoint.Administration.Backup namespace; but backups and restores of individual site collections are performed with the Microsoft.SharePoint.Administration.SPSiteCollection.Backup() and Microsoft.SharePoint.Administration.SPSiteCollection.Restore() methods.

Interface to the Volume Shadow Copy Service

Windows SharePoint Services 3.0 deployments can also take advantage of the Volume Shadow Copy Service (VSS) in Windows Server 2003/2008. Windows SharePoint Services 3.0 includes a Windows SharePoint Services VSS Writer service that will create shadow copies of native and custom content in the deployment. The service contains a VSS writer that will write shadow copies of all native Windows SharePoint Services 3.0 databases and all custom databases. Non-database custom components can also be registered with the service by using the SPVssComponentDefinition and SPVssDiscoveryHelper classes. It is also necessary that you create a VSS writer for any such non-database custom components.

Note: With the VSS service, you can target only the whole farm or individual content databases for database shadow copy. Individual Web applications and individual content publishing "Web services" cannot be set for shadow copying independently of making a shadow copy of the whole farm. (For information about the meaning of "content publishing Web service" see the first note of this post.)

SharePoint SDKs (and Other Documentation Resources) Now Updated for SP1

Andrew May — Wed, 12 Dec 2007 05:54:00 GMT

By now you’ve no doubt heard that SP1 for Windows SharePoint Services 3.0, Office SharePoint Server 2007, and Office SharePoint Designer are now available. (And if you haven’t heard, go here to get all the important details before you download and install the Service Packs.)

For a complete listing of the documentation available for SharePoint SP1, check out the What’s New in SharePoint Server 2007 Service Pack 1 page on MSDN, which includes information resources for both WSS and MOSS SP1.

I’m happy to announce that as part of the SP1 push, we’ve again updated the WSS and MOSS SDKs on MSDN:

· Windows SharePoint Services 3.0 SDK (December 2007 Refresh)

· Office SharePoint Server 2007 SDK (December 2007 Refresh)

Here’s a quick run-down of additions and updates we’ve made to the WSS SDK:

New and Updated Material in the Windows SharePoint Services 3.0 SP1 SDK

New conceptual sections and topics that detail new features in Windows SharePoint Services 3.0 SP1 include:

· ASP.NET AJAX in Windows SharePoint Services

This section provides overview information, installation instructions, and programming examples that introduce you to how Microsoft ASP.NET AJAX interacts with Web Parts. Topics include:

· Overview: ASP.NET AJAX and Web Parts in Windows SharePoint Services 3.0

· Installing ASP.NET 2.0 AJAX Extensions 1.0 in Windows SharePoint Services Version 3.0

· Walkthrough: Creating a Basic ASP.NET AJAX-enabled Web Part

Other new conceptual sections and topics include:

· Workflow Actions Schema Overview

The section discusses how to use the Workflow Actions schema to create and deploy custom workflow actions. The section includes reference topics for each of the 14 elements in the schema, as well as an example .ACTIONS file:

· .ACTIONS File Example (WorkflowActions)

· Alerts in Windows SharePoint Services

This section provides 8 new topics of overview information and programming tasks to help you work with Windows SharePoint Services 3.0 Alerts.

Significantly revised sections and topics include:

· Custom Field Types

This section has been expanded with nine new topics, including the following new walkthrough:

· Walkthrough: Creating a Custom Field Type

In addition, reference material for all base field-rendering control types, and most derived types, in Microsoft.SharePoint.WebControls has been expanded.

· Mobile Development

This section has been expanded with 6 new conceptual topics, including the following new procedural and walkthrough topics:

· How to: Customize Mobile Home Pages

· How to: Customize Mobile List View and Form Pages

· How to: Customize Field Rendering on Mobile Pages

· Walkthrough: Customizing Item Titles on a Mobile Display Form

· Walkthrough: Creating a Custom Field Rendering Control for Mobile Pages

In addition, reference material for all types in the Microsoft.SharePoint.MobileControls namespace has been added or expanded. The types in this namespace are now fully documented.

· Working with Site Templates and Definitions

Several topics have been expanded.

· All types in the Microsoft.SharePoint namespace that connected to auditing are now fully documented.

· More than 80 code samples rewritten to adhere to the best coding practices as described in the following articles:

· Best Practices: Common Coding Issues When Using the SharePoint Object Model

· Best Practices: Using Disposable Windows SharePoint Services Objects

· Greatly expanded reference material for 39 types in the Microsoft.SharePoint.Utilities namespace.

This update also includes numerous other updates and revisions to existing SDK content.

And as for the SharePoint Server 2007 SDK, we’ve added and revised quite a bit of material there as well:

New and Updated Material in the SharePoint Server 2007 SP1 SDK

New and Improved Features in Office SharePoint Server 2007 SP1

· Support for Custom HTTP and SOAP Headers

New Conceptual Topics and How Tos

· SharePoint Products and Technologies Customization Best Practices

· Modeling Web Service Systems

· Modeling Database Systems

· Document Converter Framework Sample

· Working with Menus and Navigation Objects

· Modifying Navigation Settings Through the UI

· Customizing Navigation Controls and Providers

New Web Services and Class Library Reference Topics

· Microsoft.SharePoint.UserProfiles (56 classes)

· User Profile Web Service (14 classes)

· User Profile Change Web Service (2 classes)

· Exception classes (multiple classes in various namespaces)

· Internal only classes (multiple classes in various namespaces)

New Tools/Samples

· WCM Document Converters Code sample

· Workflow Collect Feedback ASPX sample

Check it out, and as always, let us know what you think—either through rating our content, entering a comment on the topic online, or pinging us with an email through our blog.

Content Migration in SharePoint (Post 2):

NickG (msft) — Thu, 06 Dec 2007 02:40:00 GMT

Key Concepts in Selective Migration

Picking up where the first post left off, today's foray explores the basic concepts of SharePoint content migration. Most of these concepts come into play in nearly every migration scenario where you use the SharePoint.Deployment namespace APIs. This post covers the following concents:

Content selection (also known as "cherry picking")
The content migration package (.cmp) file
Object identity (that is, retaining object identity on import)
Reparenting objects
Handling content types when migrating a site collection
Handling workflows when migrating

Content selection for export

Once the initial full migration has occurred and the source and destination sites are established, selective migration relies on logic in your custom code for selection criteria that determines which items are selected for migration, and when. Also known as "cherry picking," this is the process through which specific items on the source site collection are migrated to the destination site collection based on selection criteria that is specified in the custom code.

In the basic scenario, logic in a code module associated with a timer job runs on a recurring schedule (for example, every 24 hours at 3:00 a.m.); the module examines date stamps or change logs (or both), then selects and exports only those files that have changed since the last migration.

The operation relies on the identity of objects in the source and destination site collections. At import time, the destination recognizes objects by GUID identifiers and then updates their corresponding files accordingly.

Content migration package (.cmp) file

The content migration package is a compressed cabinet (.cab) file that uses the .cmp file extension. The migration package (.cmp) file aggregates data for export from the source site, along with site structure and dependency data, and stores it as compressed, serialized XML files.

While the export operation compresses site data by default, you can override this behavior and export uncompressed files by changing the SPDeploymentSettings.FileCompression property to false. This property is on the SPDeploymentSettings object.

When using file compression, you must must specify the name of the compressed content migration (.cmp) file using the BaseFileName property on the SPExportSettings object. The FileLocation property specifies where the compressed file is located on the source server.

By default, the .cmp files are limited to 24 MB in size, although you can change this using the FileMaxSize property. When site data exceeds the 24 MB limit, your site data is separated in to two or more migration files. However, where a single file exceeds the maximum file size, the operation resizes the .cmp file to accommodate the file. You can have any number of .cmp files.

Object identity

SharePoint objects are identified by GUID on the source server. Upon import, by default, the objects are assigned new GUIDs on import to the destination. To support selective migration scenarios, however, you must change the default and retain the identity of the object that you are exporting. This is very important, because the only way that files can successfully update their corresponding versions on the destination site is for the destination to recognize the object by its identifying GUID.

You can retain object identity by setting the RetainObjectIdentity property on the SPImportSettings object to true.

Note To use the RetainObjectIdentity property to support selective migrations, you must also set the ExportMethod property to the value ExportChanges.

Retaining object identity should be used carefully, and in limited scenarios. It most commonly supports a publishing scenario in which source and one or more destination servers are mirror images — for example, where a development or test server is migrating updates to one or more production servers.

If you are creating a new site that you know in advance will receive file updates on a regular basis (for example, from a development or test server), you can enable a smooth link between the two by first doing a full migration from the source to a completely blank site, but with RetainObjectIdentity property set to true. It is very important, then, that you never modifythe destination. The initial migration established the mirrored hierarchy and mappings; any modifications to the destination can break the linkage. If this relationship gets broken, your only recourse is to delete the destination and then reestablish the linkage as originally done.

Note In the scenario described above, you can use Stsadm.exe to complete the export portion of the migration, since it does not support the retention of object identity. However, you must use the migration APIs to complete the import portion of the migration in order to retain object identity.

SharePoint content databases do not permit duplicate GUIDs or file names, so you must be careful when implementing this property. You should not retain object identity when you are simply updating files on the destination server, because the import operation cannot determine whether a file is new or an update, and will therefore place a duplicate copy of the file on the destination.

This happens because the migration process uses GUID identifiers, but only down to the level of the item collection. Beneath that level, that is, for individual files, the system uses the file name. Consequently, the import simply copies over the updated version of the existing file and leaves the original intact, potentially creating duplicates. When the destination server then encounters duplicate file names, it cannot resolve the ambiguity and becomes unstable.

Important When deleting files, it is very important to delete the files on both the source and destination servers. Not doing so can cause duplicate files names and an unstable site.

To support field deletion (a feature that deletes previous versions of items on the source server when the migration updates and deletes the same file on the destination), the RetainObjectIdentity property must be set to true.

Reparenting

Now let's consider a much different scenario. Instead of a publishing scenario, in which objects on the source server have to map to their equivalent files on the destination server, consider instead a scenario in which a specific subweb or list item is migrated and you want to place it at a different place in the destination hierarchy. This is a very common requirement and you handle this by reparenting the object (or objects) on import.

It's important to note that, as discussed in the section on retaining object identity, any time that you do not retain object identity, a migrated object will need a new parent specified on import. It doesn't matter if the destination site collection is the same site collection as the source or even if it is in the same database as the source site collection. It also doesn't matter if the destination site collection is in the same or a different farm as the source site collection.

If you export an item from a database without exporting its parent, then the item that you've exported will become orphaned in the content migration package, but that's not necessarily a problem. A package can contain multiple orphaned objects.

Having orphaned objects in the migration package is not a problem because the import method allows us to define a new parent for each of these orphaned objects. This is what is meant by "reparenting." However, objects that are exported with their parent objects keep their relationships during migration. So, for example, if you export Web A and Web B is a sub web of web A, then you can only change the parent of web A. The parent of Web B will remain as Web A, because Web B.

There are two ways to reparent orphaned objects when importing. In the first, you import all of your orphaned objects into the same subweb, while in the other method you assign parent objects individually to each orphaned object.

Reparent by importing all orphans to the same subweb

You can reparent your orphan objects by simply importing all of them into the same subweb. However, this only works if all of the orphan objects are destined for the same subweb. For example, this is the preferred method if you have exported two or more list or document library objects and you want to import them all into the same subweb. This works even if the export objects are from different source sites. Here is some sample code for doing this. Of particular note are the WebUrl and RetainObjectIdentity properties.

SPImportSettings settings = new SPImportSettings();

settings.SiteUrl = "http://localhost:2001";

settings.WebUrl = "http://localhost:2001/MyDestinationWeb";

settings.FileLocation = @"c:\export";

settings.FileCompression = false;

settings.RetainObjectIdentity = false;

SPImport import = new SPImport(settings);

import.Run();

In the above example, the WebUrl property defines the site (the SPWeb) that becomes the new parent for all orphaned objects in the export package.

Note You cannot use this method to reparent orphaned objects if the migration package contains orphaned documents; SharePoint site cannot become the parent of a document document object (only list or folder objects can parent documents).

Note, too, that the RetainObjectIdentity property is set to false. This is important because keeping this property as false (which is the default) cases the operation to assign a new GUID to the orphaned objects, which is essential for reparenting those objects.

Reparent by assigning new parent objects individually

Assigning new parents to orphaned objects individually is much more flexible than the previous method, but also requires more coding. In this approch, you must intercept the import operation to assign a new parent to each orphaned object after the operation has accumulated a list of all orphaned objects in the migration package. You can do this by implementing a custom event handler, as in the following example:

static void OnImportStarted(object sender, SPDeploymentEventArgs args)

{

SPSite site = new SPSite("http://localhost:2001");

SPWeb web = site.RootWeb;

SPImportObjectCollection rootObjects = args.RootObjects;

foreach (SPImportObject io in rootObjects)

{

io.TargetParentUrl = web.Url;

}

web.dispose();

site.dispose();

}

This approach uses the RootObject collection of the event arguments to aggregate all and then reparent all of the orphan objects. Actually, we do much the same thing that we did when we imported all of the objects to the same subweb, that is, we defined a specific site (SPWeb) as the new parent of all included orphaned objects. However, notice how you can extend the logic in the event handler to, for example, assign different parents to different orphans based on object type, as shown here:

static void OnImportStarted(object sender, SPDeploymentEventArgs args)

{

SPSite site = new SPSite("http://localhost:2001");

SPWeb web = site.RootWeb;

SPList list = web.Lists["MyDocLib"];

SPImportObjectCollection rootObjects = args.RootObjects;

foreach (SPImportObject io in rootObjects)

{

if (io.Type == SPDeploymentObjectType.ListItem)

{

io.TargetParentUrl = list.RootFolder.ServerRelativeUrl;

}

if (io.Type == SPDeploymentObjectType.List)

{

io.TargetParentUrl = web.Url;

}

...

}

web.dispose();

site.dispose();

}

There is a great deal of flexibility here. In addition to reparenting based on the object type, you could instead look at the original TargetParentUrl, for example, to obtain the location of the source and then include that as part of your reparenting logic.

The code example below shows us how to hook up the event handler to the import operation. You can do this as follows:

static void ImportDocLibItem()

{

SPImportSettings settings = new SPImportSettings();

settings.SiteUrl = "http://localhost:2001";

settings.FileLocation = @"c:\deployment5";

settings.FileCompression = false;

settings.RetainObjectIdentity = false;

SPImport import = new SPImport(settings);

EventHandler<SPDeploymentEventArgs> eventHandler = new EventHandler<SPDeploymentEventArgs>(OnImportStarted);

import.Started += eventHandler;

import.Run();

}

Notice that you need to register the event handler with the import class before you start the import operation.

There are several more event handlers that you can register and use during import; these are explained in more details at help topics for SPImportEvents and for SPExportEvents. Similar events can also be registered for export, if required:

Content types (handling)

Migration operations that use the export and import commands include your content type definition schema files in the export package. However, in cases where content type definitions hold references to custom SharePoint features, you must manually install and configure on the destination compute the feature for which the content type holds a reference. Features that are native to the SharePoint server environment will have their type definition references restored automatically.

On starting the import operation, you will receive a warning message that alerts you with the identity of custom features for which references must be recreated. You must resolve these references after completing the import.

For more information about content types, see Content Types. For more information about SharePoint features, see Working with Features.

Workflows

Workflows are not included in export packages so when you initially set up a migration target, you must copy any custom workflows that you have onto the destination server and reconfigure the workflow association table. This includes creating (or restoring on the destination) the workflow definitions files.

Of course, manually restoring your custom workflows on the migration destination is only necessary when you initially set up your destination server. Subsequently, when doing selective migrations in a publishing scenario, it is advantageous that workflows are excluded from the migration package.

For more information about managing workflows, see the following:

· Introduction to Workflows in Windows SharePoint Services

· Workflows in Windows SharePoint Services

Content Migration in SharePoint

NickG (msft) — Sat, 01 Dec 2007 01:20:00 GMT

Around the time work started on a long whitepaper about migrating content files from SharePoint server "A" to SharePoint server "B" using the migration and deployment APIs in the Microsoft.SharePoint.Deployment namespace, I came across a series of blog posts by Stefan Goβner that covered the subject matter in detail. Many of you have probably seen Stefan's work: Deep Dive into the SharePoint Content Deployment and Migration API, Parts 1-5.

I contacted Stefan and he agreed to collaborate. He's allowed me to use some of his code examples, and to expand on some of his points. Additionally, I've collaborated with the feature PM and lead developer on the migration/deployment APIs here at Microsoft, Patrick Simek, so the whitepaper treats the subject quite a bit more broadly than does Stefan's blog posts.

I'll chunk this article up into segments for posting to this blog. Comments are DEFINITELY welcome. I'll be converting much of the content of this article (and these posts) into Help content in the SharePoint SDK documentation, so anything that helps to improve the quality of the content is highly desired. Here's the first section:

The ABCs of Content Migration (Post 1)

Many scenarios require moving content from one SharePoint site to another. When the scenario calls for a full migration (that is, moving the entire contents of a SharePoint site or site collection), the task is relatively simple. Typically, you use either of two main approaches:

Use the export and import operations in the Stsadm.exe utility to migrate data from one site to another.
Alternatively, use SOAP calls to the Sites.ExportWeb and Sites.ImportWeb methods that are implemented on the Sites Web service to migrate data.

However, both of these methods have limitations. Both limit you to migrating only a full SharePoint site, or site collection. In addition, neither allows you to retain object identity during the migration operation. Retaining object identity is an essential feature of selective migration. Using Stsadm.exe and Sites Web service have other limitations as well.

Consequently, content migration scenarios that require you to export only selected content, or that require you to automate or customize migration operations, there is only one approach: you must write a custom solution that uses the APIs in the Microsoft.SharePoint.Deployment namespace.

Note Selective migration operates when there is an established source and a recognized destination for a known quantity of content. That is, selective migration requires that a full migration was initially performed so that the destination is a mirror image of the source.

Selective migration applies, typically, to content that needs to be migrated from server to server based on factors such as content version (current vs. future), time stamp, and content state (approved vs. in review, for example). Selection criteria provides a high degree of granularity from the scope of the site collection down; that is, you have selection control at the scope of the Web, the list, folder, and list item.

You can have any number of .cmp files in a migration operation, and you can also have multiple destinations. However, the objects contained in a given content migration package (.cmp) file must originate from a single site collection.

Typical Migration Scenarios

The APIs in the Microsoft.SharePoint.Deployment namespace provide a rich migration toolbox that gives you an enormous degree of flexibility to support wide ranging migration scenarios. Following is a list of migration and deployment features that are supported in Windows SharePoint Services 3.0. This list is only a high-level, generalized summary of supported migration scenarios. The Deployment APIs are sufficiently rich to support any number of special circumstances that you might face.

Export an entire site collection (that is, do a full migration).
Export a specific site inside a site collection, including or excluding content in subsites as needed. The deployment APIs allow you to include or exclude dependencies.
Export a SharePoint list or document library, or even of a specific folder inside a document library.
Export a single list item or document from a document library. This provides the extreme migration granularity that enables so much flexibility.
Export object dependencies like images or attached files.
Generate your export file as a compressed export (.cmp) package, or as uncompressed files.
Throttle exports by specifying a maximum size for the compressed export package file (multiple export files will be created if required).
Support incremental exports of items that are selected for export based on change tokens. This allows you to automate exporting all items that have been created, changed, or deleted after the timestamp specified in the change token.
Import the exported content with or without preserving object identity—that is, you can configure objects in the export package to retain their object GUID. This is a requirement for selective migrations.
Import the migration content under the same or a different parent in the destination content database. Moving items to a different position in the site hierarchy is an operation is known as reparenting.
Do link fixup during import.

In my next post we'll continue with this high-altitude look at the subject of content migration. There, we'll talk extensively about key concepts in the migration/deployment feature area.

SharePoint SDKs Machine Translation Pilot

Andrew May — Wed, 28 Nov 2007 05:32:00 GMT

Erika Ehrli has the scoop on Office’s participation in the MSDN machine translation pilot project. As part of the pilot, you can try out beta versions of the machine-translated Windows SharePoint Services 3.0 and Office SharePoint Server 2007 SDKs in Portuguese. You can also test out beta versions of the machine-translated Office SharePoint Server TechNet materials in Spanish and Portuguese, side-by-side view with the original English content.

Erika has all the details here.

SharePoint Resource Center Pages Now Live

Andrew May — Wed, 28 Nov 2007 05:14:00 GMT

Last week we added five new Resource Center pages to the Windows SharePoint Services developer portal on MSDN. Each Resource Center page focuses on a specific area of developer functionality in SharePoint, and contains links to information and resources from around the web, be it any source (Microsoft sites, sure, but also partners, consultants, MVPs, or anyone else who’s got useful information to share) and in any format (technical articles, blogs, Web casts, video downloads, you name it). Think of them as one-stop-shops for developer information around specific areas of interest.

Here are the five areas for which we added Resource Center pages:

· Administration

· Pages and User Interface

· Provisioning

· Security

· Web Parts

These are in addition to the Resource Center pages already up on the Office SharePoint Server developer portal:

· Business Data Catalog

· Enterprise Content Management

· Enterprise Search

· Excel Services

· Web Content Management

· Workflow

In the near future, we plan on adding more Resource Centers for areas such as upgrade and migration, deployment, email and alerts, and content management.

So what would you like to see in our Resource Centers?

If you’ve know of resources you think should be added to our existing Resource Center pages, or have areas you think warrant Resource Centers of their own, let us know! Just add a comment to this post, or email the blog directly. We’d love to hear from you.

Welcome

Andrew May — Fri, 09 Nov 2007 02:34:00 GMT

Welcome to the official blog of the SharePoint Products and Technologies developer documentation team. My name is Andrew May; I’m a Content Publishing Manager for Windows SharePoint Services. My team produces the Windows SharePoint Services SDK, along with the developer help for SharePoint Designer. We also manage the Windows SharePoint Services and SharePoint Designer developer portals. My cohort, Randall Isenhour, manages the team responsible for the Office SharePoint Server and Project SDKs, along with the Office SharePoint Server and Project developer portals.

We created this blog in order to be able to:

· Present “draft” versions of SDK content before it’s available in the SDKs themselves. These drafts are tech-reviewed content that will end up in the SDKS; this is just our way of getting the information out to you as quick as we can.

· Promote content that we publish on MSDN. This includes giving you the latest news on new technical articles, SDK updates, code samples or tools downloads, and anything else new and noteworthy we think you’ll want to take a look at.

· Blog about the developer documentation we produce, and why. Ever wonder why we document what we do, in the way we do? In future posts we’ll explore the decisions we make when planning SharePoint developer documentation, and the data we base those decisions on.

· Engage with users, and find out just how developers are using (or would like to use) the documentation we produce.

· Experiment with presenting developer documentation in new and different formats.

So stay tuned. Over the next few days we plan introduce some of the writer on our teams, and to give you a first look at some documentation that’ll be included in the next updates of the WSS and MOSS SDKs.

And if you’ve got anything you want to talk about regarding SharePoint developer documentation, post a comment or drop us an email. We’d love to hear from you.

Microsoft SharePoint Developer Documentation Team Blog : SharePoint

How to Add a Tab to the Ribbon in SharePoint Foundation

First Look: SharePoint 2010 Developer Documentation Now Live on MSDN!

How We Address Developer Documentation Comments

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

Introduction

Procedures

Development Advice

Example

Description

See Also

How to: Programmatically Back Up and Restore a Single Site Collection

Introduction

Procedures

Example

Comments

See Also

How to: Programmatically Restore Content

Introduction

Procedures

Example

See Also

How to: Programmatically Back Up Content

Introduction

Procedures

Example

See Also

Programming with the Windows SharePoint Services Backup/Restore Object Model

Introduction

The Backup and Restore Object Model

Programming Advice

Ways of Customization

Permissions

Failure Logging

Backups and Restores of Site Collections

Overview of Backing Up and Restoring Data in Windows SharePoint Services

Introduction

What Can Be Backed Up and What Can Be Restored

Limitations

Types of Backups and Restorations

Two Kinds of Custom Backup Applications

The Main Backup and Restore Object Model

Interface to the Volume Shadow Copy Service

SharePoint SDKs (and Other Documentation Resources) Now Updated for SP1

Content Migration in SharePoint (Post 2):

Content selection for export

Content migration package (.cmp) file

Object identity

Reparenting

Reparent by importing all orphans to the same subweb

Reparent by assigning new parent objects individually

Content types (handling)

Workflows

Content Migration in SharePoint

The ABCs of Content Migration (Post 1)

SharePoint SDKs Machine Translation Pilot

SharePoint Resource Center Pages Now Live

Welcome