Architectural Approaches to Upgrading a Site Definition

Applies to: SharePoint Foundation 2010

In SharePoint Foundation 2010 there are two fundamental ways to upgrade custom site definitions from one version to another: Either modify customizations in the previous version so that they function in the new version, or create a site definition based on the current version and subsequently upgrade the site definition of the previous version. In other words, you can either change your previous definition so that it resembles a new site, or you can make a copy of an installed SharePoint Foundation 2010 site definition and modify this copy to match your previous definition.

First Approach: Modify Existing Customizations to Work in the New Version

Starting with Windows SharePoint Services 3.0, there have been two supported means to customize a site definition—by copying and then modifying a site definition that is installed by default in the setup directory, or by creating a custom Feature and activating it within a deployment.

The first way to customize a site definition requires working from a copy of a site definition (never from the default files that are installed in the setup directory). It also requires that site definition names and template numbers be unique and that they do not conflict with other templates (for example, template numbers must be greater than 10000 to not conflict with default template numbers). For information about how to create a custom site definition through this approach, see Overview of Creating Custom Site Definitions. For upgrade, you then use an upgrade definition file to map previous files to the new ones.

The preferred approach for adding content and capabilities to a site definition is through Features, and SharePoint Foundation 2010 introduces Feature versioning and the capacity to upgrade Features that you created for the previous version. For information about Features and how to upgrade them, see Using Features in SharePoint Foundation.

Second Approach: Design the Site and Create a Site Definition in the New Version

To make a customized Web site based on a previous version work with full functionality, you can instead create an equivalent current site definition that matches your previous site as closely as possible. This was the preferred approach to upgrading site definitions from Windows SharePoint Services 2.0 to Windows SharePoint Services 3.0, which involves starting with a new site definition and customizing it to replace the previous site definition.

With the second approach, you undertake an investigation of all the new functionalities and attempt to incorporate these features as much as possible into your site (for example, use content types for lists, master pages for custom pages, and so on). You test the site definition of the current version to determine whether it creates site instances and performs behaviors appropriately. If it does, the next step is to create an upgrade definition that can be used for moving sites from the previous version to the current one. Keep in mind that, if you choose to discontinue particular previous site features, you may need to provide a replacement in the current version. For example, even if you discontinue a particular custom list type, you may need to create list templates to support, at a minimum, their upgrade. You therefore start this upgrade approach by using 2010 site definitions, first designing an experience that is appropriate to the current version, and then using the upgrade process as a means to bring previous customizations to the desired result in the current context.

See Also

Concepts

Using Features in SharePoint Foundation

Other Resources

Upgrading SharePoint Foundation