Upgrading Pages

Last modified: April 06, 2010

Applies to: SharePoint Foundation 2010

Microsoft SharePoint Foundation 2010 uses a different strategy for upgrading a page depending on whether or not it has been customized.

SharePoint Foundation tracks the version of the site definition through which a Web site was created. A Web site can be upgraded if it has an update definition that translates front-end site definition files that have not been customized. After the upgrade process, any references to uncustomized front-end files are mapped from the previous directory to the current directory, which is:

%ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\

Not every Web site path is upgraded at the time of initial upgrade. Any existing site definitions that do not have upgrade paths will still function but will continue to point to their original pages. Also, a Web site that has been updated may still have the previous version's customized pages that have been stored in the database.

When code is being parsed and pages rendered, SharePoint Foundation determines which Web site the page is associated with, and therefore, the version of uncustomized files on the front-end Web server. The pages of a previous version are not necessarily compatible with the standards of the current version. These pages run in a compatibility mode if the site has not been upgraded, but after an upgrade definition is applied and the site is upgraded, SharePoint Foundation assumes that the pages are fully compatible with Microsoft ASP.NET 3.5. This means, for example, that they have a Web Part manager if they contain Web Part zones, that they have valid control identifiers (IDs), and that they are associated with a master page.

Page Compatibility 

In previous versions of SharePoint Foundation, customized pages in the database were parsed by using the "Windows SharePoint Services" parser, which had different tolerances from the ASP.NET parser. If a page contains malformed markup language, it may be that while the page worked in a previous version, it might not work in ASP.NET and the current version of SharePoint Foundation because of differences between the parsers.

The SharePoint Foundation parser addresses a subset of known breaking issues in page markup, including the following:

  • Invalid control IDs that are not compliant with ASP.NET, such as when a name is invalid because the ID begins with a number or unsupported character, the ID is an empty string, or the ID is not unique with respect to other IDs on the page. This modification may break the page in the case where client-side script relies on the former ID names.

  • Known attributes inserted in the page by SharePoint Foundation (for example, __Preview, __Error, __Web PartId, WebPart) are handled by implementing the SharePoint IAttributeAccessor interface on Web Parts.

  • Removal of Trace attributes.

  • Addition of appropriate directives for registering tags like <WebPart:WebPartZone> or <SharePoint:Theme>.

SharePoint Foundation does not attempt to fix the following breaking issues on pages:

  • Unknown attributes on controls.

  • Presence of <object runat=server> tags.

  • Databinding expressions present inside attributes (<% ... %>).

SharePoint Foundation stores a version integer for each customized page in the database. When a customized page is browsed, SharePoint checks the version number of the page. If the version number corresponds to a previous version that has not been upgraded, SharePoint fixes these various breaking issues and updates the page behind the scenes.

Application Pages

SharePoint Foundation stores layouts files in a language-independent folder, and automatically sets up a redirect that navigates users from the previous /_layouts location to the current one.

Layout pages in general are keyed to use a master page that is set through the SPWeb.MasterUrl property. For site definitions of previous versions, this property should refer to a master page that retains the previous look and feel.

Web Parts from previous versions of SharePoint Foundation continue to function in the current version, although they may require a few changes in their configuration. If you create a new Web application to host a SharePoint Foundation installation, the web.config file for that installation must be updated to include additional safe control and code access security (CAS) policy settings.

Although the general level of CAS restrictions remains the same in SharePoint Foundation, policy files are modified to remain contemporary for ASP.NET. For this reason, it might not be possible to re-use the CAS policy files of a previous release in the current version of SharePoint Foundation. The best option is to make a copy of the current version's wss_minimaltrust.config file and incrementally add permissions as necessary.

For more information about how to upgrade Web Parts, see Upgrading Web Parts in SharePoint Foundation.