Upgrading Pages and Web Parts

  • Article

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

General Page Upgrades 

Windows SharePoint Services uses a different strategy for upgrading a page depending on whether or not it has been customized (unghosted).

Windows SharePoint Services tracks whether a Web site was created through a Windows SharePoint Services 2.0 (\web server extensions\60) or Windows SharePoint Services 3.0 (\web server extensions\12) site definition. A Web site can be upgraded by virtue of having 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 \web server extensions\60 directory to \Web server extensions\12.  

Not every Web site is upgraded from \60 to \12 at the time of initial upgrade. Any existing site definitions that do not have upgrade paths will still function, but continue to point to their \60 pages. Also, a Web site that is updated from \60 to \12 may still have Windows SharePoint Services 2.0 pages (in other words, no master page, no Web Part manager) that have been customized and thereby stored in the database. 

At the time of parsing and rendering a page, Windows SharePoint Services determines which Web site the page is associated with, and therefore, whether uncustomized (ghosted) files on the front-end Web server are Windows SharePoint Services 2.0 or Windows SharePoint Services 3.0. Windows SharePoint Services 2.0 pages are not directly compatible with Windows SharePoint Services 3.0 standards. 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, Windows SharePoint Services assumes that the pages are fully compatible with Microsoft ASP.NET 2.0. This means, for example, that they have a Web Part manager if they contain Web Part zones, that they have valid control IDs, and that they are associated with a master page.

Page Compatibility 

In Windows SharePoint Services 2.0, customized pages in the database were parsed 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 Windows SharePoint Services Windows SharePoint Services 2.0, it will not work in ASP.NET and the new version of Windows SharePoint Services because of differences between the parsers.

The new Windows SharePoint Services 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 Windows SharePoint Services (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>.

Windows SharePoint Services 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 (<% ... %>).

Windows SharePoint Services 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 an un-upgraded Windows SharePoint Services 2.0, SharePoint fixes these various breaking issues and updates the page behind the scenes.

Version 2 Layouts Pages in Version 3 

Windows SharePoint Services 2.0 layouts pages typically refer to out-of-the-box layout files that are installed to the \Web Server Extensions\60\TEMPLATE\LAYOUTS\Locale_ID setup directory. Because Windows SharePoint Services 3.0 layouts files are now stored in a language-independent folder, Windows SharePoint Services automatically sets up a redirect that navigate users from /_layouts/Locale_ID/nameofoldpage.aspx to /_layouts/newpage.aspx.

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

Upgrading Web Parts

Windows SharePoint Services 2.0 Web Parts continue to function in Windows SharePoint Services 3.0, although they require a few changes in their configuration. If you create a new Web application to host a Windows SharePoint Services 3.0 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 Windows SharePoint Services 3.0, the Windows SharePoint Services policy files have been modified to make them contemporary for ASP.NET 2.0.  For this reason, it is not generally possible to re-use Windows SharePoint Services 2.0 CAS policy files in Windows SharePoint Services 3.0.  The best option is to make a copy of the Windows SharePoint Services 3.0 wss_minimaltrust.config file and incrementally add permissions as necessary.