Share via

Visual Upgrade

Applies to: SharePoint Foundation 2010

When you upgrade to Microsoft SharePoint Foundation 2010, changes that have been made to the new product that affect the user experience may adversely affect certain user interface (UI) elements, such as customized pages, Web Parts, Web controls, or views. Visual Upgrade allows site collection administrators and Web site owners to decide whether or not to switch from previous visual UI elements to current visual UI elements. The administrator can choose to either provide or hide the Visual Upgrade option in all the Web sites of a site collection, or the administrator can proceed to apply the latest UI elements directly to all the Web sites.

When Visual Upgrade is enabled within a site collection, Web site owners control Visual Upgrade, and the initial server farm upgrade preserves the previous user experience (including layout, command organization, and style) so that all the data and settings of the original Web site are preserved. However, after the server farm has been upgraded, farm administrators, site collection administrators, or Web site owners can update their sites to provide the latest SharePoint user experience. Preserving the previous user experience reduces the likelihood that customized content will stop functioning, which ensures that administrators, developers, and end users can continue working in SharePoint Foundation until all upgrade work has been completed. As long as Web sites function according to the previous SharePoint user experience, some new SharePoint features might not be available. Such new features include, for example, the Server ribbon UI, in-place editing for Wiki pages, interactive calendars, or list relationships. When Web sites are switched to the latest user experience, new features automatically become available. New sites that you create after upgrade use the new UI by default.

Test in Both UI Modes

After upgrade, use a test environment to test Web sites both before and after Visual Upgrade. Perform tests in the previous UI mode and the current UI mode to make sure that the sites work in both versions. Make sure that your customizations are installed, and that they function correctly at least in the previous UI mode.

Verify that UI elements that have a visual aspect work correctly and look correct in the new version of SharePoint Foundation. Any visual customization, or any customization that injects a form of HTML, or that has dependencies on the style sheets--for example, master pages, layout structures, controls on the page--will probably require revision that you will not know you need until you test them. Such UI elements include, for example, delegate controls, Web Parts, custom site definitions, custom master pages, custom themes, and so on. Chances are high that, although such UI elements work well before Visual Upgrade, after Visual Upgrade they will render something that is incompatible with the new UI, and you will need to modify the element. UI elements that probably require the least amount of work for upgrade include, for example, custom content types, custom field controls that do not have a visual aspect, custom HTML modules, or HTML handlers.

If a UI element is visual, you will almost always have to write code to make it work in the current version of SharePoint Foundation. Consider how the element is displayed in the browser. In some cases, you may simply need to repair the HTML for strict mode by closing tags. Or a Web Part might inject old markup language on the page. If nested lists are closed in the wrong order, for example, the page might break because of browser-specific or DOM-related behavior. Custom user controls that contain script, that contain code defined in .asmx and .ascx pages, or that allow you to host .ascx controls in document libraries, do raise security risks and upgrade issues, and you should consider them during upgrade. If during testing you discover problems, always try to solve them by first using one of the XML declarative upgrade structures that are provided in SharePoint Foundation, either an upgrade definition file, or Feature upgrade, both of which are easy to test.

Visual Upgrade Object Model

New members have been added to the SharePoint Foundation object model that change according to Visual Upgrade status, and that allow you to determine whether a Web site is rendering correctly. Visual Upgrade allows you to render a control in two different ways, which can help prevent creating a control that works in the current UI, but that breaks all pages that are rendered in the previous UI. For example, you do not want to mix modes by rendering a style structure of the current mode in a UI page of the previous mode, but you want to render pages in the appropriate mode of the site. The new properties allow you to build intelligence into features by writing code that determines how to display UI elements conditionally, depending on the UI version.

  • UIVersion (SPWeb): Specifies the current version of the Web site’s user interface. Valid values include 3, for Windows SharePoint Services 3.0, and 4, for SharePoint Foundation 2010 and Microsoft SharePoint Server 2010.

  • UIVersionConfigurationEnabled (SPWeb): Specifies whether to enable the Visual Upgrade settings UI for changing the UI version of the Web site. If set to false, users cannot change the UI version.

  • UIVersionConfigurationEnabled (SPSite): Specifies whether to enable the Visual Upgrade settings UI for changing the UI version of the site collection. Setting this property to false disables the Visual Upgrade settings UI that allows site collection owners to convert all child Web sites to the new UI, and this setting also hides the Visual Upgrade settings UI on all the Web sites.


    A Web site has a UI version, but a site collection does not have a UI version.

In addition to the previous properties, SharePoint Foundation provides a UIVersionedContent control, which is a Web control that conditionally displays content based on a specified version string and the current Web site’s UI version. This control adds its contents to the page control hierarchy only if it matches the Web site’s UI version. Another control, VersionedPlaceHolder, does not perform as well, but it provides a backup option for cases where the control must be on the page for initialization, loading, and prerendering, but where it is hidden for rendering. For information about new Version properties and attributes that have been added to the object model and schema for upgrading Features, see Upgrading Features.

The Pre-Upgrade Checker tool provided in Windows SharePoint Services 3.0 with Service Pack 2 , whose rules were updated in the October 2009 Cumulative Update Server Hotfix Package , provides means to help you identify where customizations are used and whether they're working correctly. For example, you can use the enumallwebs operation of the stsadm command-line utility to identify where Web Parts, event receivers, Features, or custom list views have been implemented. If you are concerned about customizations that have been made, it is recommended that you upgrade your installation of Windows SharePoint Services 3.0 to Service Pack 2 and then install the October 2009 Cumulative Update Server Hotfix before you run the Pre-Upgrade Checker. For information about how to use the Pre-Upgrade Checker tool, see Run the pre-upgrade checker (SharePoint Server 2010) .

See Also

Other Resources

Upgrading SharePoint Foundation