Understanding Visual Upgrade in SharePoint 2010

  • Article

Summary:  Learn about Visual Upgrade in Microsoft SharePoint 2010 to understand options for redeploying the user interface and customized pages and custom solutions from Windows SharePoint Services 3.0 and Microsoft Office SharePoint Server 2007.

Applies to: Business Connectivity Services | Open XML | SharePoint Designer 2010 | SharePoint Foundation 2010 | SharePoint Online | SharePoint Server 2010 | Visual Studio

Provided by:  Ted Pattison, Critical Path Training (SharePoint MVP)

Contents

  • Overview of Visual Upgrade for SharePoint 2010

  • Motivation for Visual Upgrade

  • How Visual Upgrade Works

  • Managing the Visual Upgrade Process

  • Updating Custom SharePoint Solutions

  • Conclusion

  • Additional Resources

Overview of Visual Upgrade for SharePoint 2010

Microsoft SharePoint 2010 introduces a new standardized user interface that represents a significant advancement over the user interface experience provided by Windows SharePoint Services 3.0 and Microsoft Office SharePoint Server 2007. To assist companies that are upgrading their farms and content, SharePoint 2010 provides a feature known as Visual Upgrade to ease the transition to the new SharePoint 2010 user interface. This article discusses Visual Upgrade from the perspective of developers and site designers and makes recommendations about how to upgrade customized pages and custom components that were initially designed for Windows SharePoint Services 3.0 and Office SharePoint Server 2007.

Motivation for Visual Upgrade

The user interface of SharePoint 2010 is a clear and welcome departure from the user interface provided by Windows SharePoint Services 3.0 and Office SharePoint Server 2007. The new SharePoint 2010 user interface leaves behind many of the unnecessary postbacks, the confusing page transitions, and the table-based page layouts of the previous version. The result is a much improved user experience that includes a server-side ribbon and new client-side behavior that executes standard user commands behind the scenes by using asynchronous callbacks to the web server.

Although the advancements to the SharePoint 2010 user interface represent a great step forward, one must also acknowledge that the new user experience is very different from that of Windows SharePoint Services 3.0 and Office SharePoint Server 2007. The links and buttons for standard user commands live in new places behind ribbon tabs. The user experience for executing many common tasks is now dialog box–driven and might take some time to become familiar with. Although the new user interface has obvious long-term benefit, it can also have a short-term effect on user productivity. Therefore, companies should carefully plan their migration to the new user interface of SharePoint 2010 and this migration should involve some end-user training.

In addition to the need for users to get up to speed on the new user interface, there is also the issue of page customizations and custom components that were designed and tested for Windows SharePoint Services 3.0 and Office SharePoint Server 2007. Companies that are migrating sites that have customized pages or that rely on custom components such as Web Parts should take proactive steps to ensure that these page customizations and custom components appear and behave correctly when used in the new user interface of SharePoint 2010. In some scenarios, customized pages and custom solutions designed for Windows SharePoint Services 3.0 and Office SharePoint Server 2007 might have to be updated before they work correctly in the new user interface.

SharePoint 2010 provides Visual Upgrade, which is designed to assist companies that are upgrading their existing sites to run in a SharePoint 2010 environment. The key value of Visual Upgrade is that it enables companies to upgrade sites to SharePoint 2010 without forcing their users to immediately begin using the new SharePoint 2010 user interface. Instead, Visual Upgrade enables users to continue using the older familiar interface within a SharePoint 2010 farm during a period of transition. At some point in the future when the users are ready for the change, the site administrator can reconfigure the site to begin using the new SharePoint 2010 user interface.

The core value of the Visual Upgrade feature is that it effectively decouples the migration of sites and content from the end users' migration to the new SharePoint 2010 user interface. This enables the farm administrator to upgrade sites and content to SharePoint 2010 without having to worry about coordinating end-user training in advance. Visual Upgrade also makes it unnecessary to prematurely force business users to begin using the new SharePoint 2010 user interface, no matter which weekend the farm administrator choses to perform the upgrade.

Understanding the default.master Master Page

To understand the inner workings of Visual Upgrade, it is necessary to conduct a quick review of the standard user interface components that are used in Windows SharePoint Services 3.0. Whenever Windows SharePoint Services 3.0 provisions a new site, it creates a special hidden document library known as the master page gallery. In addition to creating the master page gallery in each new site, it also provisions an instance of a master page named default.master, which is the primary master page in Windows SharePoint Services 3.0 that is used to give sites their standard look and feel.

The layout of the HTML elements defined within default.master is dependent upon rules inside cascading style sheets (.css files). The master page definition inside default.master includes a server-side control named CssLink, which automatically adds a link to an important file named core.css. Many customized pages and custom SharePoint solutions in Windows SharePoint Services 3.0 and Office SharePoint Server 2007 extend the cascading style sheets rules that are defined inside core.css with additional rules.

One very important point to consider is that default.master is defined without a DOCTYPE. The omission of a DOCTYPE in the pages of a Windows SharePoint Services 3.0 site forces browsers to interpret and render the HTML elements inside by using an older set of rules. It is equally important to acknowledge that the cascading style sheets rules behind HTML pages are also affected by the DOCTYPE, or in the case of Windows SharePoint Services 3.0, by the lack of a DOCTYPE.

When a page does not define a DOCTYPE, the browser interprets the cascading style sheets rules behind it by using an older set of rules that many Web designers refer to as "quirks mode." It is called quirks mode because there is quite a bit of inconsistency in the way in which cascading style sheets rules are applied across browsers.

In Windows SharePoint Services 3.0, site pages typically link to default.master by using a special token instead of a hardcoded path. More specifically, the Page directive in Windows SharePoint Services 3.0 site pages includes the MasterPageFile attribute, which is assigned the token value of ~masterurl/default.master, as in the following example.

<%@ Page MasterPageFile="~masterurl/default.master" %>

The value of this special token is that it is dynamically replaced by Windows SharePoint Services 3.0 as it processes the page. Each Windows SharePoint Services 3.0 site has a MasterUrl property that is initially assigned a value that references the instance of default.master in the current site's master page gallery. However, a custom solution can upload a custom master page to the master page gallery and update the MasterUrl property to redirect site pages to use the custom master page instead of default.master.

An important point regarding master pages and application pages is that Windows SharePoint Services 3.0 and Office SharePoint Server 2007 do not support linking application pages to default.master or to any other master page in a site's master page gallery. Instead, application pages are written to link to master pages that are deployed inside the LAYOUTS directory. For example, the majority of application pages that are supplied by Windows SharePoint Services 3.0 and Office SharePoint Server 2007 link to the standard master page named application.master, which is deployed inside the LAYOUTS directory.

<%@ Page MasterPageFile="~/_layouts/application.master" %>

You should also understand that many custom SharePoint solutions that were designed for Windows SharePoint Services 3.0 and Office SharePoint Server 2007 deploy their own custom application pages. Most of these custom application pages use the same technique of linking to application.master or to another master page that is deployed inside the LAYOUTS directory.

How Visual Upgrade Works

The new user interface in SharePoint 2010 has been rebuilt from the ground up. Therefore, it uses new master pages and new .css files that were not included with Windows SharePoint Services 3.0 or Office SharePoint Server 2007. However, to provide the functionality that is required for Visual Upgrade, SharePoint Foundation 2010 must also carry forward the same standard master pages and .css files that are used in Windows SharePoint Services 3.0. Therefore, SharePoint Foundation 2010 deploys several files that have the same names as they do in Windows SharePoint Services 3.0, such as default.master, application.master, and core.css.

To differentiate between the older files that are created for Windows SharePoint Services 3.0 and the newer files that are created for SharePoint Foundation 2010, Microsoft created a simple versioning scheme. The user interface of Windows SharePoint Services 3.0 and Office SharePoint Server 2007 is named version 3 because Windows SharePoint Services 3.0 carries the version number of 3.0. The new user interface of SharePoint 2010 is named version 4. As you will see, some files that are included with SharePoint Foundation 2010 have either a v3 or a v4 in their name to indicate which version of the user interface they are designed to support.

Whenever SharePoint 2010 provisions a new site, it creates the master page gallery and provisions a master page named default.master, just like Windows SharePoint Services 3.0. However, SharePoint 2010 provisions two additional master pages named v4.master and minimal.master.

The master page named v4.master is the primary master page that is used to construct the new SharePoint 2010 user interface. For example, v4.master is what gives team sites in SharePoint 2010 a common page layout across all the pages in a site, including familiar elements such as the Site Actions menu, the breadcrumb trail, the ribbon, the Welcome menu, the Site Icon, the TopNav bar, and the QuickLaunch.

One noteworthy improvement to the SharePoint 2010 user interface is that application pages can now link to master pages in the master page gallery. Many of the standard application pages that are included in Microsoft SharePoint Foundation 2010 and Microsoft SharePoint Server 2010 are initially linked to v4.master. The fact that sites pages and application pages can now be linked to a single master page creates a more uniform look and feel across all the pages in a site.

The master page named minimal.master provides a page layout for version 4 without any of the chrome that is included in v4.master, such as the Site Actions menu, the ribbon, the TopNav bar, and the Quick Launch. Minimal.master is used by several of the standard site page templates and application pages that are distributed along with SharePoint Foundation 2010 and SharePoint Server 2010.

The third master page that is provisioned in the master page gallery for every new SharePoint 2010 site is default.master. This master page contains the HTML layout and chrome of a Windows SharePoint Services 3.0 site. The cascading style sheets file from Windows SharePoint Services 3.0 named core.css is also included with SharePoint Foundation 2010 to provide the same formatting behavior as in a Windows SharePoint Services 3.0 farm. You should understand that default.master and core.css are specifically included to support Visual Upgrade scenarios where SharePoint 2010 sites are required to render by using the older Windows SharePoint Services 3.0 user interface.

Understanding the v4.master Master Page

The master page named v4.master is at the heart of the new user interface of SharePoint 2010. The HTML that is defined inside v4.master and the cascading style sheets rules behind it are significantly different from those of default.master. That is because v4.master and the cascading style sheets rules behind it were designed to embrace emerging Internet standards in web design and to achieve much higher levels of consistency across today's most popular browser such as Internet Explorer, FireFox, and Safari.

The v4.master master page is different from default.master because it defines a DOCTYPE. This is one of the keys of achieving consistency across different browsers. More specifically, v4.master defines a DOCTYPE of XHTML 1.0 Strict.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

From the perspective of a web designer, it is also important to understand that the top-level HTML that is used to lay out pages in v4.master is based on div elements, as opposed to the table-based layout used in default.master. The use of div elements allows v4.master to improve accessibility over Windows SharePoint Services 3.0 and Office SharePoint Server 2007. The elimination of a table-based page layout is also a welcome change to web designers because it opens up the possibility of using modern design techniques that are used by other popular and familiar websites on the Internet.

You should also observe that the inclusion of the XHTML Strict DOCTYPE in v4.master affects how the browser interprets the cascading style sheets rules behind a page. For example, a cascading style sheets rule may have a certain effect on an HTML element when the hosting page contains no DOCTYPE. The same cascading style sheets rule may have a very different effect, or no effect, when the hosting page is later given a specific DOCTYPE such as XHTML Strict. For this reason, v4.master does not rely on the cascading style sheets rules inside core.css because its cascading style sheets rules were designed for pages that do not define a DOCTYPE. Instead, v4.master links to a new .css file named corev4.css, which was designed to work with the XHTML Strict DOCTYPE.

Linking to Master Pages in SharePoint 2010

The way that site pages link to a master page is the same in SharePoint 2010 as it is in Windows SharePoint Services 3.0 and Office SharePoint Server 2007. If you examine the site page templates supplied by SharePoint Foundation 2010 and SharePoint Server 2010, you discover that they use the standard MasterPageFile attribute with the same dynamic token that is used in Windows SharePoint Services 3.0, as shown in the following example.

<%@ Page MasterPageFile="~masterurl/default.master" %>

Just as in Windows SharePoint Services 3.0, the SPWeb object that represents a site has a MasterUrl property, which is used to tell SharePoint 2010 which master page to link to for pages using the dynamic token of ~masterurl/default.master. When you create a new site in SharePoint 2010, the MasterUrl property is initialized to reference the instance of v4.master in the current site. However, when you upgrade a site from Windows SharePoint Services 3.0 or Office SharePoint Server 2007, that site carries forward its current MasterUrl property value, which most often references default.master. However, a Windows SharePoint Services 3.0 site that uses a custom branding solution could also reference a custom master page that has been uploaded to the master page gallery.

Although the technique for linking site pages to a master page remains essentially the same between Windows SharePoint Services 3.0 and SharePoint Foundation 2010, this is not true for application pages. SharePoint Foundation 2010 now makes it possible for application pages to link to the same master page as site pages. For example, when running a SharePoint Foundation 2010 team site under the version 4 user interface, most application pages link to v4.master along with the site pages. When you update the MasterUrl property of a site, both site pages and application pages begin using the new master page.

There is new syntax introduced in SharePoint 2010 that enables application pages to link to a master page by using the same dynamic token that is used by site pages. This syntax involves adding the DynamicMasterPageFile attribute in the Page directive, as shown in the following example.

<%@ Page DynamicMasterPageFile="~masterurl/default.master" %>

This syntax can be confusing at first because the DynamicMasterPageFile attribute is not recognized by the ASP.NET runtime. Instead, DynamicMasterPageFile is a custom attribute that is read and interpreted by SharePoint 2010 early in the page life cycle. Just as in the case of a site page, SharePoint 2010 is able to retrieve the MasterUrl property value for the current site and use it to dynamically link the application page to the correct master page.

The way that site pages and application pages link to a master page is different, but they both typically rely on the ~masterurl/default.master token to produce the same effect. This is what makes it possible to swap out the master page for every page in a SharePoint 2010 site simply by updating the SPWeb.MasterUrl property.

Notice that there is one common scenario in Office SharePoint Server 2007 and SharePoint Server 2010 where the pages in a site do not link to the master page referenced by the MasterUrl property. This scenario involves publishing sites that contain a special document library named Pages. The Pages document library contains a special type of page known as a publishing page. All publishing pages dynamically link to a master page by using another property of the SPWeb class named CustomMasterUrl. Therefore, when writing code to swap out the master page in a publishing site, you are required to update the CustomMasterUrl property instead of, or in addition to, the MasterUrl property.

Switching Between Versions of the SharePoint User Interface

By default, when a Windows SharePoint Services 3.0 site or an Office SharePoint Server 2007 site is upgraded to SharePoint 2010, its pages are initially rendered by using the version 3 user interface of Windows SharePoint Services 3.0. However, the choice of when to migrate the user interface to version 4 can be made by site administrators on a site-by-site basis by using standard commands in the browser. There is also a command available in the browser for a site collection owner to migrate all the sites within a site collection at one time. This means that individual teams can decide when the time is right for them to migrate the user interface of their sites to version 4.

Now it is time to discuss the implementation details that enable SharePoint 2010 to switch the user interface for a site back-and-forth between versions. Each SharePoint site is represented by an SPWeb object. Starting with SharePoint 2010, each SPWeb object carries a new UIVersion property that is tracked in the content database. The UIVersion property is integer-based and can have a valid value of either 3 or 4. When a site has a UIVersion property value of 3, SharePoint 2010 will render the site's pages by using version 3. When a site has a UIVersion property value of 4, SharePoint 2010 will render the site's pages by using version 4.

SharePoint 2010 also makes it possible to enable or disable the ability of a site administrator to reconfigure the user interface version. This control is made possible through another new SPWeb property, the UIVersionConfigurationEnabled property. If this property has a Boolean value of true, SharePoint 2010 provides the site administrator with the ability to move forward or move back between versions by using the browser. If a site has a UIVersionConfigurationEnabled property value of false, SharePoint 2010 does not provide the site administrator with any control to switch between the user interface versions.

When you create a new site in SharePoint 2010, the Visual Upgrade feature is unnecessary. Therefore, new sites are created with a UIVersion property value of 4 and a UIVersionConfigurationEnabled property value of false. This means that the user interface for new sites runs by using version 4. It also means that the site administrator has no ability to move the site's user interface back to version 3.

Things are different when upgrading existing sites from Windows SharePoint Services 3.0 and Office SharePoint Server 2007. When you upgrade a site, SharePoint 2010 has the default behavior of initially assigning a UIVersion property value of 3 and a UIVersionConfigurationEnabled property value of true. This means that the user interface for upgraded sites initially runs under version 3. Upgraded sites also provide the site administrator with the ability to reconfigure the user interface for the site to begin using version 4. However, when a site administrator decides to reconfigure the site running under version 4, SharePoint 2010 updates the UIVersionConfigurationEnabled property to false, taking away the site administrator's ability to move back to version 3.

Updating the UIVersion Property by Using Code

The server-side object model of SharePoint 2010 makes it relatively easy to update the UIVersion property of one or more sites to automate migrating the user interface of sites in a farm from version 3 to version 4. The following simple C# code snippet, written by using Microsoft Visual Studio 2010, reconfigures all the sites within a site collection so that their user interface runs under version 4.

string url = "http://intranet.wingtip.com";
using (SPSite siteCollection = new SPSite(url)) {
  foreach (SPWeb site in siteCollection.AllWebs) {
    site.UIVersion = 4;
    site.UIVersionConfigurationEnabled = false;
    site.Update();
  }
}

What if you are a farm administrator and you want to accomplish the same result without having to write a compiled component or application? You can write the equivalent code to update the UIVersion property of one or more sites by using a Windows PowerShell script. For example, what if you want to transition a single site that is currently running under version 3 to use version 4? You can write a Windows PowerShell script that creates an SPWeb object for the target site and updates the same properties as the C# code in the preceding example.

When you create a Windows PowerShell script in which you want to call cmdlets provided by SharePoint 2010, you should begin by calling the Add-PSSnapin cmdlet to load the Windows PowerShell snap-in that contains the SharePoint 2010 cmdlets. Then you can retrieve the target site object with the Get-SPWeb cmdlet to retrieve the target SPWeb object. After that, you can assign a value of 4 to the UIVersion property and a value of false to the UIVersionConfigurationEnabled property, followed by a call to Update, as shown in the following example.

Add-PSSnapin "Microsoft.SharePoint.PowerShell"
$site = Get-SPWeb "http://intranet.wingtip.com"
$site.UIVersion = 4
$site.UIVersionConfigurationEnabled = false
$site.Update()

Managing the Visual Upgrade Process

When you begin migrating existing sites from Windows SharePoint Services 3.0 and Office SharePoint Server 2007 to SharePoint Foundation 2010 and SharePoint Server 2010, you must be careful to consider what customizations have been applied. For example, are you upgrading sites in which users have customized pages with their own HTML by using Microsoft Office SharePoint Designer 2007? You must also consider whether any of the sites to be upgraded rely on custom SharePoint solutions created by your company's development staff or by third-party software vendors. For example, do the sites that you plan to upgrade rely on custom master pages or Web Parts that produce HTML that will not render correctly when they are hosted on a page that defines the XHTML Strict DOCTYPE? These are the types of issues that you must anticipate and be prepared to resolve when upgrading sites to SharePoint 2010.

Updating SharePoint Page Customizations

Consider a scenario where the pages in a Windows SharePoint Services 3.0 site have been customized by users by using Office SharePoint Designer 2007. After this site is upgraded, you might find that these pages behave as expected because the pages are running under version 3. However, you might find that these same pages do not render correctly after the site administrator reconfigures the site to run under version 4. This section discusses some of the most common issues that you might encounter and how to resolve them.

Ensuring That Site Pages Use the ~masterurl/default.master Token

As stated previously, most site pages link to a master page by using the dynamic token value of ~masterurl/default.master. However, this might not be the case for site pages that have been created or customized by using Office SharePoint Designer 2007. You might find that some site pages in an upgraded site link to default.master or some other custom master page by using a hardcoded path instead of the dynamic token. This will cause problems because SharePoint 2010 relies on the dynamic token to redirect the master page link from default.master to v4.master when the site's UIVersion property is changed from 3 to 4. Therefore, you should update all site pages to link to a master page by using the token value of ~masterurl/default.master instead of a hardcoded path.

Refactoring Custom HTML into SharePoint v3 and v4 Sections

When you reconfigure the user interface for a site from version 3 to version 4, two important changes usually occur that can affect how HTML is rendered. First, the master page changes from default.master, which has no DOCTYPE, to v4.master, which has an XHTML DOCTYPE of Strict. The second thing that happens is that SharePoint 2010 switches out the primary .css file link from core.css to corev4.css. Both of these changes have the ability to make HTML layouts designed for Windows SharePoint Services 3.0 and Office SharePoint Server 2007 render incorrectly when running under version 4.

When you find that customized site pages or customized master pages contain HTML fragments that do not properly render properly under version 4, you can factor this HTML out into separate sections for version 3 and version 4. This can be accomplished by using the UIVersionedContent control that is introduced in SharePoint 2010.

The following code snippet shows an example of using a pair of UIVersionedContent controls to output different HTML content, depending on whether the site is configured for version 3 or version 4.

<Sharepoint:UIVersionedContent ID="myContentIDv3" runat="server" UIVersion="3">
  <ContentTemplate>
    <p>This content displays only when UIVersion=3.</p>
  </ContentTemplate>
</SharePoint:UIVersionedContent>
<Sharepoint:UIVersionedContent ID=" myContentIDv4" runat="server" UIVersion="4">
  <ContentTemplate>
    <p>This content displays only when UIVersion=4.</p>
  </ContentTemplate>
</SharePoint:UIVersionedContent>

Refactoring Custom Cascading Style Sheets Rules into Separate .css Files

Due to the fact that pages in a SharePoint site use a different DOCTYPE for version 3 and version 4, a single set of cascading style sheets rules will not produce consistent results when used across both version 3 and version 4. Furthermore, the HTML element IDs and cascading style sheets class names that must be referenced by cascading style sheets rules vary between the default.master and v4.master files. Therefore, it makes sense to factor cascading style sheets rules into separate files for version 3 and version 4. For example, let's say that you are upgrading a site that has a custom .css file named WingtipStyles.css. The recommended approach is to create a new .css file (or make a copy of the existing file) and name it WingtipStylesv4.css. This provides you with the ability to maintain separate sets of cascading style sheets rules for version 3 and version 4. You can then link to the appropriate .css file by using two UIVersionedContent controls, as shown in the following example.

<Sharepoint:UIVersionedContent ID="myLinkIDv3" UIVersion="3" 
                               runat="server" >
  <ContentTemplate>
   <link href="WingtipStyles.css" rel="stylesheet" type="text/css" />
  </ContentTemplate>
</SharePoint:UIVersionedContent>
<Sharepoint:UIVersionedContent ID="myLinkIDv4" UIVersion="4"
                               runat="server" >
  <ContentTemplate>
   <link href="WingtipStylesv4.css" rel="stylesheet" type="text/css" />
  </ContentTemplate>
</SharePoint:UIVersionedContent>

Tip

If you are using SharePoint Server 2010, you could instead insert a CSSLink control, and then use the CSSRegistration control to apply the correct cascading style sheet. The CSSRegistration control enables you to select either the version 3 or version 4 user interface.

Updating Custom SharePoint Solutions

Some custom SharePoint solutions that were designed for Windows SharePoint Services 3.0 and Office SharePoint Server 2007 require updates to work correctly when they are used in SharePoint Foundation 2010 and SharePoint Server 2010 sites running the version 4 user interface. Common examples of project items that might require an update include Web Parts and custom application pages.

Updating Web Parts to Inspect the UIVersion Property

Many custom Web Parts that were developed for Windows SharePoint Services 3.0 and Office SharePoint Server 2007 were written to render HTML elements inside the M:System.Web.UI.WebControls.RenderContents method. For example, the following code snippet is a starting point for creating a Web Part that renders a simple paragraph tag.

protected override void RenderContents(HtmlTextWriter writer) {
  writer.RenderBeginTag(HtmlTextWriterTag.P);
  writer.Write("Hello World");
  writer.RenderEndTag(); // </p>
}

This example is very simple; most Web Parts that use this technique produce more elaborate HTML fragments that might not display correctly when running with the DOCTYPE and cascading style sheets rules that are used when running under version 4. The best way to handle this is to add conditional logic so that each Web Part provides different HTML output, depending on whether the current site has a UIVersion property value of 3 or 4, as shown in the following example.

protected override void RenderContents(HtmlTextWriter writer) {
  int UIVersion = SPContext.Current.Web.UIVersion;
  if (UIVersion == 3) {
    // Write HTML for site running under version 3.
  }
  if (UIVersion == 4) {
    // Write HTML for site running under version 4.
  }
}

As discussed earlier in this article, SharePoint 2010 enables application pages to link to a master page by using the same dynamic token as site pages. However, this capability did not exist in Windows SharePoint Services 3.0 or Office SharePoint Server 2007. Therefore, most of the custom applications pages designed for Windows SharePoint Services 3.0 and Office SharePoint Server 2007 have hardcoded links to master pages within the LAYOUTS directory, such as application.master.

<%@ Page MasterPageFile="~/_layouts/application.master" %>

When an application page that links to application.master runs under version 3, it behaves as you would expect. The application page links to the application.master file deployed by SharePoint 2010, which has the same HTML layout as the application.master file deployed by Windows SharePoint Services 3.0. However, SharePoint 2010 is designed to add some special processing logic when the same page runs under version 4. When an application page that links to application.master runs under version 4, SharePoint 2010 dynamically changes the application page to link to a different master page named applicationv4.master, which has a DOCTYPE and HTML layout very similar to v4.master. This enables these older application pages to render by using the new SharePoint 2010 page layout.

Although this behavior of SharePoint 2010 to redirect application pages from application.master to applicationv4.master is useful, it is still not an optimal solution. If you use a custom branding solution that updates the MasterUrl property, application pages that link to application.master will not be redirected to use the same master pages as the other pages in the site. The same problem exists if you try to change the master page that is used by a publishing site.

The way to resolve this problem is to update the Page directive of any master page that directly links to a master page in the LAYOUTS directory. You should remove the MasterPageFile attribute from the Page directive and replace it with the DynamicMasterPageFile attribute.

<%@ Page DynamicMasterPageFile="~masterurl/default.master" %>

Conclusion

The user interface introduced by SharePoint 2010 is a great step forward for the SharePoint platform. However, the dramatic change in the user experience can have a short-term effect of lowering user productivity. The Visual Upgrade feature is designed to lessen this effect on users by decoupling farm and content migration from migration to the new user interface. Visual Upgrade goes further by enabling user interface migration from version 3 to version 4 on a site-by-site basis. This level of granularity enables different teams within a company or organization to move to the new version 4 user interface at their own pace, independently of any other team.

Now that you have seen the implementation details of how Visual Upgrade works, you have the knowledge that is required to automate converting sites to the version 4 user interface by writing code in Visual Studio 2010 or by writing Windows PowerShell scripts. In addition, you can understand the issues that might arise when you upgrade sites that have customized pages and custom SharePoint solutions. By understanding the problems that might arise and taking proactive steps to resolve them, you can manage the smoothest possible transition to migrate sites from Windows SharePoint Services 3.0 and Office SharePoint Server 2007 to SharePoint Foundation 2010 and SharePoint Server 2010.

Additional Resources

For more information, see the following resources: