Share via

Develop new custom site definitions and create upgrade definition files (Office SharePoint Server)

  • Article

Applies To: Office SharePoint Server 2007

This Office product will reach end of support on October 10, 2017. To stay supported, you will need to upgrade. For more information, see , Resources to help you upgrade your Office 2007 servers and clients.

 

Topic Last Modified: 2016-11-14

In this article:

  • Before you develop new custom site definitions

  • Develop new custom site definitions

  • About upgrade definition files

  • Create upgrade definition files

  • Record upgrade definition file information on a worksheet

Before you develop new custom site definitions

Before you upgrade sites based on custom site definitions, you must take the following steps to ensure that each list and page that is derived from your custom site definitions will continue working after upgrade.

Note

If you are not yet ready to upgrade the sites based on a custom site definition (for example, if you obtained the site definition from a solution provider and a new version of that site definition is not yet available), you can use a gradual upgrade to upgrade other sites, and leave the sites based on the previous custom site definition running in the previous environment. Later, when you have a new custom site definition, you can create the upgrade definition file and upgrade only the sites that are based on the new custom site definition.

  1. **Obtain or develop new custom site definitions and custom elements   **If you want to retain the functionality of sites that are based on a custom site definition, you need a new custom site definition that includes all of the functionality you need, plus any of the new capabilities you want to use. If you obtained a custom site definition or custom elements from a solution provider, check to see if the provider has a new version. If your solution provider does not provide a new version, you might need to develop your own.

  2. **Create a site upgrade definition file   **You also need to create a file that maps the custom elements from your old custom site definition to the new custom site definition, so that each element in your site (for example, a custom page) can upgrade to the appropriate new element.

  3. **Create page template upgrade definition files   **For Microsoft Office SharePoint Portal Server 2003, you also need to create upgrade definition files for translating the page templates, such as the Home page template, into new page layouts. Page layouts in Microsoft Office SharePoint Server 2007 replace page templates in SharePoint Portal Server 2003, and you need to specify which page layout to use for each page type. For more information about page layouts, see Plan Web pages.

Important

If you create a site template that is based on one of the predefined site definitions in SharePoint Portal Server 2003, the upgrade process may overwrite some of the files or customizations that are contained in the site template. You must recreate any site template that has been created from a SharePoint Portal Server 2003 site definition. You must recreate the template from an equivalent Office SharePoint Server 2007 site definition to provision new sites after upgrade.

During the pre-upgrade process, you copy the new custom site definition and any upgrade definition files to the installation directory so that they are available when you upgrade the site collections.

Develop new custom site definitions

Use this process to create custom site definitions in a development environment. For more information, see the Windows SharePoint Services Software Development Kit (SDK) on MSDN.

  1. Create custom site definitions by starting from a site definition provided with the new environment.

    • Site definitions are stored in the following folder:

      %COMMONPROGRAMFILES%\Microsoft Shared\web server extensions\12\TEMPLATE\SiteTemplates\NAME

      Where NAME matches the site definition name (for example, ACTION). Create a folder for your new site definition, and name the new folder using all uppercase letters.

    • The XML files used to register the site templates are stored in the following location:

      %COMMONPROGRAMFILES%\Microsoft Shared\web server extensions\12\TEMPLATE\LCID\XML\webtempname.xml

      Where name matches the site definition name, except that it is in lowercase letters, (for example, action), and where LCID is the locale identifier for the language of the template, (for example, 1033 for United States English).

  2. Create a new version of the webtempname.xml file for each custom site definition you have in SharePoint Portal Server 2003, where name is the name of the site definition. You can create webtempname.xml files from the files for the standard site definitions provided with the new product (environment).

  3. After you successfully complete the upgrade process, copy the page templates that you used for SharePoint Portal Server 2003 to the master page gallery folder at the root of an upgraded site collection. For more information, see Plan Web pages.

    Also, create page layouts by using your corresponding customized landing pages from SharePoint Portal Server 2003 as is. Before upgrading, save a copy of your customized landing pages. After you successfully complete the upgrade process, upload these layout pages to the master page gallery folder at the root of a site collection.

  4. Test your site definitions in the development environment by creating a new site based on the site definition.

After you have created and tested your new site definitions, you can create the upgrade definition files that map your previous site definitions to the new site definitions.

About upgrade definition files

A site upgrade definition file describes how to map a previous custom site definition to a new site definition. The goal of a site upgrade definition file is to give developers a tool to transform their previous sites into new equivalents that take advantage of all the improvements the new environment has to offer.

For Microsoft Office SharePoint Server 2007, there are upgrade definition files for specific page templates. A page template is an Active Server Page Extension (ASPX) file that defines the structure of a page. The benefit of page templates is that you can create new pages based on the page template, rather than create the pages in a Web page editor that is compatible with Office SharePoint Server 2007. Page templates are stored at the root of the site collection and are shared across the site collection.

In Office SharePoint Server 2007, page templates are used for most pages on the portal site. In other words, all new site definitions for Office SharePoint Server 2007 include page templates, and many portal pages that were based on the standard portal site definition in the previous product (environment) are based on different page layouts in the new product. The upgrade process moves portal pages from the previous product to pages that use page layouts in the new product. Page templates from the previous product are moved to the default set of page layouts provided with the new product. If the default set of page layouts does not suit your needs, you can create a custom set and provide an upgrade definition file to map the old portal pages to the new page layouts.

An upgrade definition file for a site definition has the following sections:

  • **WebTemplate   **Specifies upgrade information for the Web template as a whole. In this section, you need one WebTemplate tag per upgrade definition file.

  • **Lists   **Specifies upgrade information for each list or library in the template. In the Lists section, you need one List tag per list or library.

  • **Files   **Specifies upgrade information for the individual pages in the template. In the Files section, you need one File tag for each ghosted (uncustomized) page in the template.

  • **AppliedSiteFeature   **Specifies upgrade information for any site collection-level or subsite-level features included in the template. In the AppliedSiteFeature and AppliedWebFeature sections, you need one Feature tag for each feature at that level in the template.

  • **AppliedWebFeature   **Specifies upgrade information for any subsite-level features included in the template. In the AppliedWebFeature section, you need one Feature tag for each feature at that level in the template.

The following example, taken from one of the files installed in Office SharePoint Server 2007, outlines the format for a page template upgrade definition file.

<SPSSiteUpgraderConfig>
    <PublishingPageLayoutMappings>
        <PublishingPageLayoutMapping WebTemplateId="20" PublishingPageLayout="/_catalogs/masterpage/defaultlayout.aspx"/>
        <PublishingPageLayoutMapping WebTemplateId="22" PublishingPageLayout="/_catalogs/masterpage/welcomelayout2.aspx"/>
    </PublishingPageLayoutMappings>
</SPSSiteUpgraderConfig>

You can see from this example that a Web site template maps to a page template; in other words, the Web site template with ID=20 maps to the page layout=defaultlayout.aspx. This means that every site that uses the template ID of 20 will have a home page (usually default.aspx) that uses a page layout defined by defaultlayout.aspx.

Make sure to include entries in the page template upgrade definition file for your customized landing pages from SharePoint Portal Server 2003 that you will use for page layouts in Office SharePoint Server 2007. These entries set a Web site template ID to the name of the landing page from SharePoint Portal Server 2003 that you will use as page layouts.

Create upgrade definition files

Give the upgrade definition file a unique name that begins with the name of the site definition. For example, for a site definition named "STS1," name the upgrade definition file "STS1_upgrade.xml."

Upgrade definition files must be installed in the following folder:

%COMMONPROGRAMFILES%\Microsoft Shared\web server extensions\12\Config\Upgrade

For more information about creating upgrade definition files, including a sample upgrade definition file, see the Upgrade Definition Files (https://go.microsoft.com/fwlink/?LinkId=109945&clcid=0x409) and Upgrade Definition Schema (https://go.microsoft.com/fwlink/?LinkId=109946&clcid=0x409) topics in the Windows SharePoint Services 3.0 SDK on MSDN.

For more information about deploying upgrade definition files and new site definitions, see Deploy upgrade definition files and new site definitions (Office SharePoint Server). For additional information about creating upgrade definition files, such as what to include in the files and the schema, see Upgrading SharePoint Portal Server 2003 Customizations to SharePoint Server 2007 (https://go.microsoft.com/fwlink/?LinkId=105294&clcid=0x409) in the MSDN Library.

Record upgrade definition file information on a worksheet

Record the file names and paths for each upgrade definition file that you need to create on the Custom templates and mapping files worksheet (https://go.microsoft.com/fwlink/?LinkID=798133&clcid=0x409).

Download this book

This topic is included in the following downloadable book for easier reading and printing:

See the full list of available books at Downloadable content for Office SharePoint Server 2007.