Upgrading a Custom Site Definition
Applies to: SharePoint Foundation 2010
In previous versions of SharePoint Foundation, many types of customization required customizing site definitions, which usually involved copying the STS site definition and modifying list schemas, pages, and other structural elements in the copied definition. Large parts of the custom site definition were not customized, which meant that they maintained many of the same basic traits as the STS site definition.
The way to obtain a current equivalent for a custom site definition of a previous version varies depending on the site definition and the kinds of customization that you made. If you did not heavily customize the site definition in relation to the site definition on which it was based, the best option may be to create a current equivalent for that site definition and retrofit the new definition to include previous customizations. For example, if your only customization to a previous version's site definition was to use a Feature to add a custom list, or to customize the Default.aspx page for a custom look and feel, then you should probably use the site definition of the current version as the base for a new custom site definition and upgrade your Feature (see Upgrading Features). If your customizations were more extensive, however, it would probably be better to convert the previous site definition into an equivalent for the current site definition. The remainder of this topic provides guidance on how to convert a customized site definition of the previous version into a correct site definition of the current version.
Updating ASPX Pages
When hosting a Web site based on a previous version's site definition, SharePoint Foundation executes pages in a compatibility mode to ensure that they function within the deployment. However, when running pages from a site definition of the current version, SharePoint Foundation does not run the pages in compatibility mode for performance reasons. For this reason, when you create your SharePoint Foundation site definition, you must modify your Microsoft ASP.NET pages to some extent.
If you have not customized ASPX pages in your previous version's site definition, it is good practice to copy the Default.aspx page of the current version's site definition. For example, if the site was based on a custom site definition that was originally based on the STS site definition, this page would be located int the %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\SiteTemplates\sts\xml folder.
All Web Part pages must contain an ASP.NET Web Part manager to function properly. Consequently, if you have customized ASPX pages, you must add a Web Part manager to them, which you do by inserting <WebPartPages:SPWebPartManager id="m" runat="Server" /> into the pages.
Note
Because all SharePoint master pages include a Web Part manager, it is good practice to take the extra step of basing your ASP.NET pages on a master page. You gain more flexibility from a master page-based infrastructure, and master pages help ensure that common parts of SharePoint Foundation functionality are included on the page. For more information, see Master Pages.
Editing Onet.xml
The structure of the Onet.xml file has changed in fundamental ways. If you did not customize Onet.xml in your custom site definition of the previous version, it is good practice to copy the current version's Onet.xml file from the %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\SiteTemplates\sts\xml folder into your site definition.
In SharePoint Foundation, all XML files in the setup directory use resource expressions ($Resources) to make them work for any language whose language packs have been installed. To make a previous version's site definition work for multiple languages, and to benefit from this expanded use of resources, you must make numerous changes in the XML files of the previous version. In this case, it may be best to copy the current version's site definition and add your customizations to it.
If you customized the Onet.xml file in a previous version's site definition, you must modify the file to work in the current version. The following basic steps can help you make a previous Onet.xml file more consistent with a current site definition.
To ensure that Web sites created through your definition consistently use the current SharePoint Foundation base list types, you may need to remove the <BaseTypes> section from the Onet.xml file. Base list types are included by default in SharePoint Foundation sites and do not need to be defined in your file.
If present, remove standard lists from the Onet.xml file of the previous version. Many lists required for SharePoint functionality are now included by default in SharePoint Foundation and do not need to be defined in your Onet.xml file. For more information, see Upgrading Standard List Definitions.
If present, remove the <ListTemplate> tag for lists where the Name attribute equals webtemp, listtemp, wplib, or datasrcs. Also remove, if present, the underlying list definitions for these lists by removing the LISTS\WEBTEMP, LISTS\LISTTEMP, LISTS\wplib, and LISTS\DATASRCs folders. Remove each <List> tag from the <Configurations> section where the Type attribute equals 113 (Web template gallery), 114 (list template gallery), or 111 (Web Part gallery).
Consider mapping the <DocumentTemplates> section to current document templates. The system of expressing document templates in a site definition has not changed significantly between versions, and document templates are still stored in a per-locale directory.
For your specific site definition you must ensure that you have the corresponding set of document template files in the %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\<locale ID>\<site definition name> directory. However, if your document template files are not customized, it is possible to simply make your site definition re-use document templates. To do this, annotate each <DocumentTemplate> node in your Onet.xml file to specify Path="STS".
Final Considerations
After you have customized your site definition, test it in SharePoint Foundation 2010 to ensure that new Web sites created through the definition function as expected. After you have created the proper SharePoint Foundation site definition, the next step is to create an upgrade definition to map your site definition from the previous version to the current one.
See Also
Concepts
Upgrading Standard List Definitions