Visual Upgrade How To and Troubleshooting

Understanding Visual Upgrade in SharePoint 2010 from here

The key value of Visual Upgrade is that it enables you to upgrade platform and sites to SharePoint 2010 without forcing their users to immediately begin using the new SharePoint 2010 user interface, instead it enables users to continue using the older familiar interface 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. Need time for users to get up to speed on the new user interface and carefully plan their migration to the new user interface of SharePoint 2010 and this migration should involve some end-user training. 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.

Questions you need to ask your self

Do your sites that you plan to upgrade rely on custom master pages (or web parts) that produce HTML that will not render correctly because of the DOCTYPE rules mentioned above.

Are you upgrading sites in which users have customized pages with their own HTML? If yes, the text may not render correctly because of the DOCTYPE rules mentioned above.

Do your sites rely on custom SharePoint solutions created by your company’s development staff or by third-party software vendors? If yes, they will need to be upgraded and tested.

Do you have a custom branding solution that updates the MasterURL property? This may cause pages that link to application.master to not be redirected to use the right master page.

Are you upgrading publishing site where they changed the master URL property? This may cause pages that link to application.master to not be redirected to use the right master page.

Important Technical Points you need to know

default.master from 2007 ships with 2010 (stored in Master Page Gallery of each Site Collection)  and contains the HTML layout and chrome of a Windows SharePoint Services 3.0 site and includes cascading style sheets file from Windows SharePoint Services 3.0 named core.css.

default.master is the 2007 master page and does not use DOCTYPE which forces browsers to interpret and render the HTML elements inside by using an older set of rules than 2010 pages.

V4.master is the 2010 master page which uses DOCTYPE  <!DOCTYPE html PUBLIC … This forces browser compatibility rules which allow for UI enhancements into the future. v4.master links to a new .css file named corev4.css, which was designed to work with the XHTML Strict DOCTYPE.

Application pages can now link to master pages in the master page gallery in 2010 and the standard application pages in 2010 are initially linked to v4.master.  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. 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.

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.

Both 2007 and 2010 use the standard MasterPageFile attribute with the same dynamic dynamic tokens. There are two, the default  dynamic token is "~masterurl/default.master" The second dynamic token is "~masterurl/custom.master"

Here is an example of the default dynamic token at top or an aspx page.
<%@ Page MasterPageFile="~masterurl/default.master" %> This is used to tell SharePoint which master page to link to.. For example the token "~masterurl/default.master" is replaced at run time by the value in the MasterUrl property. This property contains the server-relative full path to the master page, including file name. This is default setting at installation time.

Here is an example of the second dynamic token at top or an aspx page.
<%@ Page MasterPageFile="~masterurl/custom.master" %> This token references a master page from a content page by using the MasterPageFile attribute with the value of the CustomMasterUrl property. The token "~masterurl/custom.master" is replaced at run time by the value in the CustomMasterUrl property, which contains the server-relative full path to the master page, including file name.

Static tokens "~site/default.master" and "~sitecollection/default.master"

You can use these tokens to link to a site-relative or site collection-relative master page. For example, if your content page is located at http://siteColl/subsite1/subsite2/default.aspx and you use the token "~sitecollection/mypage.master", your content page would use the master page at http://siteColl/mypage.master. If you use the token "~site/mypage.master", the content page would use the master page located at http://siteColl/subsite1/subsite2/mypage.master.

NoteNote:

The MasterUrl and CustomMasterUrl properties are both set to "/_catalogs/masterpage/default.master" by default. If you subsequently need to delete default.master, you must set both of those properties to a different value, not just one of them, or an error is raised that suggests the default.master file is still being used as the master page for the site.

Alternatively, you can hard code the URL for the MasterPageFile attribute specified in the page directive however, this is a change to the page’s content and is will be un-ghosted and not scalable.

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 but when you upgrade a site it carries forward its current MasterUrl property value and could have been customized and could provide problems

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" %>

All this makes it possible to swap out the master page for every page in a SharePoint 2010 site simply by updating the SPWeb.MasterUrl property.

A Pages document library contain a special type of page known as Publishing Pages. All publishing pages dynamically link to a master page by using another property of the SPWeb class named CustomMasterUrl. You may be required to update the CustomMasterUrl property instead of, or in addition to, the MasterUrl property.

Starting with SharePoint 2010, each SPWeb object carries a new UIVersion property that is tracked in the content database. 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 property value is false, SharePoint 2010 does not provide the site administrator with any control to switch between the user interface versions.

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. When a site administrator decides to do final upgrade it updates the UIVersionConfigurationEnabled property to false, taking away the site administrator’s ability to move back to version 3. But you can change it back in a script.

Referencing the Master Page from a Content Page with tokens
two dynamic tokens    ("~masterurl/default.master" and "~masterurl/custom.master")
and two static tokens  ("~site/default.master" and "~sitecollection/default.master").

SharePoint 2010 switches out the primary .css file link from core.css to corev4.css causing custom HTML to render incorrectly post upgrade.

In 2007 and 2010 publishing sites, you can change the name of the master page from the browser UI, however this option does not exist in the administration UI on team sites. Workaround is to store a central master page on the root site of the site collection and use PowerShell to change the MasterURL property for the site collection, pointing to the new name and location Like in this example

$masterpagerelativeurl  = "/sites/MyCollection/_catalogs/masterpage/custom.master”
$siteurl = “http://www.nwi.local/sites/MySite
$web = Get-SPWeb $siteurl
$web.MasterUrl = $masterpagerelativeurl    
$web.Update()
$web.Dispose()

To change the master page setting for all sites in a site collection, use the following script:

$site = Get-SPSite http://portal/sites/collaboration
$site | Get-SPWeb -limit all | ForEach-Object { $_.MasterUrl = "/sites/collaboration/_catalogs/masterpage/custom.master";$_.Update() }
$site.Dispose()

If you want to revert back to using their own default master page again, then use the following script:

$site = Get-SPSite http://portal/sites/collaboration
$site | Get-SPWeb -limit all | ForEach-Object { $_.MasterUrl = $_.ServerRelativeUrl + "/_catalogs/masterpage/v4.master";$_.Update() }
$site.Dispose()

Start checking Your Farm Now

1. You should check all site pages that have a hardcoded link to a master page and update it  to use the token value of ~masterurl/default.master instead of a hardcoded path. If you don’t it 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.

2. After or before Farm upgrade and/or during Visual Upgrade preview, look for custom HTML that will render incorrectly post upgrade (because of the DOCTYPE requirements). Then implement a pair of UIVersionedContent controls to control HTML output, depending on whether the site is configured for version 3 or version 4. Per this example.

<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>

3. Look for any pages in your sites pointing at Custom Style Sheets (CSS). These are likely referenced within the pages found above that are rendering html incorrectly. Then factor cascading style sheets rules into separate files for version 3 and version 4 and 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>

TipTip:

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.

4. Check any custom web parts that may produce HTML 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.
  }
}

5. Check publishing pages and sites where they changed the master URL property to a master page in the LAYOUTS directory of the site? This may cause pages that link to application.master to not be redirected to use the right master page. The way to resolve this problem is to update the Page directive of any 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

 

 

Typical problems you may run into… with solutions

Remember: If you can fix it manually, you can automate it in PowerShell..

Doing a Visual Upgrade will reset all the sites in site collection to v4.master and would completely remove any user built custom master pages. You may may need to retain the custom master pages and reset them. How to do it manually? Visit site, jot down the old master page file name, reset the UI version to V4 and then reset the old master page. See PowerShell script below to automate it.

You are trying to check the visual upgrade option for the site in site settings visual upgrade and you see those options are grayed out. Could be because of missing feature ids, need to upgrade the dbs again by running the PSConfig. If this is not the issue run this to enable the options in PowerShell

Get-SPWeb http://url  |  ForEach-Object{$_.UIversionConfigurationEnabled=$true;$_.update()}
go to this url to validate    _layouts/suppux.aspx

If errors are present after upgrade try this as a workaround
Copied one v4default.master page from one of working site collection master page gallery and upload on to not working master page gallery.  opened this page _layouts/prjsetng.aspx  and site renderes now.

Some site collections have the Visual Upgrade buttons disabled   (/_layouts/suppux.aspx )
Some site other site collections buttons (/_layouts/suppux.aspx ) are not disabled and the user has the ability to visually upgrade the site to the 2010 experience. This could happen when a site has been modified using SharePoint Designer. Here is Error : Visual Upgrade failed. The default master page for this user interface could not be found at "/_catalogs/masterpage/v4.master". Here is Fix: Add the requested master page at this path and try again.

Another  resolution method or work around after upgrade
Try to switch the site back from using v4.master to v3 master, run PowerShell upgrade again (using -UpdateUserExperience), it may complete without the error and site will load as expected.

Or Verify the upgrade status for the site after the resolution steps have been implemented.
In CA: manage servers in this farm’, is status ‘Upgrade Available’ or ‘No action required’?
Upgrade and Migration’ > take a look at ‘Check upgrade status’ and ‘Check product and patch installation status’, but most importantly ‘Review database status’ for the content db.

From cmd prompt or PowerShell window:
stsadm -o localupgradestatus
Results will likely be lengthy so pipe it to a .txt file
Check the file for anything with upgrade available for upgrade needed, especially the status of the site generating error in upgrade logs.

Work around for another issue: can’t add web parts

After revert master page to v4.master, add and configure the web parts they need and then revert the master pages to the custom ones they are using.

Another solution

$site = Get-SPSite http://thesite 
$site.VisualUpgradeWebs()  # this is a function that will perform Visual Upgrade in one sweep

The output of this command indicates that there is no v4.master page associated with the broken site collection: Exception calling "VisualUpgradeWebs" with "0" argument(s): "Visual Upgrade failed. The default master page for this user interface could not be found at "/xyz/_catalogs/masterpage/v4.master". Add the requested master page at this path and try again."  The easiest way to get a clean v4.master file would be to create a new 2010 site collection and copy the master page generated.

Or This

Run the following script to allow a visual upgrade to be performed through the GUI:

$SiteCollection=Get-SPsite http://SiteCollection

foreach($SPWeb in $SiteCollection.AllWebs){$SPWeb.UIversionConfigurationEnabled=$true;$SPWeb.update();}

How to retract or revert Visual Upgrade

If you have a custom master page you can’t perform the visual upgrade. you can retract the visual upgrade using PowerShell per this script. Add setting of the master page after upgrading in a custom feature if you wish.

This can revert 1 web
Get-SPSite http://url/sites/WithV3UI | Get-SPWeb "webname" | Foreach{$_.UIVersionConfigurationEnabled=1;$_.UIVersion=3;$_.Update();}

reverts all sites in a site collection
Get-SPSite http://machinename/sites/V3UI | Foreach{$_.UIVersionConfigurationEnabled=1;$_.UIVersion=3;$_.Update();}

 

This seems like a good solution found here

This script iterates over all the sites and sub-sites, remembers their old master pages, switches to v4.master and resets the sites to old master pages. In effect, the Site Settings and other pages will have the SP 2010 look and feel.” Before running the scripts, it is useful to take a look at the web page for changing master page layouts /_layouts/ChangeSiteMasterPage.aspx, there are two fields Site Master Page and System Master Page, the former is for publishing pages and the later is for forms and views (think AllForms.aspx and Views.aspx).

$rootSite = get-spsite("http://spu.sp.local") 
$webs = $rootSite.AllWebs 

foreach($w in $webs) { 

  Write-Host
  Write-Host $w
  Write-Host "       " -Separator ": " $w.CustomMasterUrl $w.MasterUrl 

 
  # CustomMasterUrl is the Site Master Page 
  $oldCustomMasterUrl = $w.CustomMasterUrl 

  # MasterUrl is the System Master Page 
  $oldMasterUrl = $w.MasterUrl 
  $w.UIVersion = 4 
  $w.UIConfigurationVersionEnabled = $false

  # At this point, the CustomMasterUrl is set to v4.master 
  $w.Update() 

  # Reset to old master pages 
  $w.CustomMasterUrl = $oldCustomMasterUrl
  $w.MasterUrl = $oldMasterUrl
  $w.Update() 

$rootSite.Dispose()

End

Visual Upgrade all Sites in a specific Content DB from Todd Klindt

The Provide Content Database name and determine all the Site Collections in that db, it will then walk through all the webs in those Site Collections and set them to the SharePoint 2010 interface. What about disposal? Todd says: From what I understand, disposal is not a problem if you keep your PowerShell to a single line. When you do that, PowerShell disposes it all at the end.

$db = Get-SPContentDatabase WSS_Content_SharePoint_2007

$db.Sites | Get-SPWeb -limit all | ForEach-Object {$_.UIversion = 4; $_.UIVersionConfigurationEnabled = $false; $_.update()}

 

View Upgrade Status (run a report) of Current User interface
$sc = Get-SPSite http://machinename/sites/collectionname; $sc.GetVisualReport() | Format-Table

 

As a side note: How to manually turn on publishing feature
Ran below commands to get the publishing feature turn on the site collection. stsadm -o activatefeature -filename publishing\feature.xml -url <http://URL&gt; -force stsadm -o activatefeature -filename publishingresources\feature.xml -url <http://URL&gt; -force stsadm -o activatefeature -filename publishingSite\feature.xml -url <http://URL&gt; -force stsadm -o activatefeature -filename publishingweb\feature.xml -url <http://URL&gt; -force stsadm -o activatefeature -filename publishinglayouts\feature.xml -url <http://URL&gt; -force stsadm -o activatefeature -filename navigation\feature.xml -url <http://URL&gt; –force

Sample c# code to copy the v4.master page to master page gallery of all site collections for the web application

using System; using System.Linq; using Microsoft.SharePoint; using Microsoft.SharePoint.Administration; using System.IO; namespace SACA { class Program { static void Main(string[] args) { SPWebApplication webApp = SPWebApplication.Lookup(new Uri("http://url of your webapp")); string strFileUrl = "v4.master"; FileStream fstream = File.OpenRead(strFileUrl); byte[] content = new byte[fstream.Length]; fstream.Read(content, 0, (int)fstream.Length); fstream.Close(); foreach(SPSite site in webApp.Sites) { SPWeb web = site.RootWeb; SPList list = web.Lists["Master Page Gallery"]; SPQuery query = new SPQuery(); query.Query = "<Where><Eq><FieldRef Name=’FileLeafRef’ /><Value Type=’string’>" + strFileUrl + "</Value></Eq></Where>"; SPListItemCollection itesm = list.GetItems(query); if (itesm.Count == 0) { web.Files.Add(site.Url + "/_catalogs/masterpage/" + strFileUrl, content); } } } } }

 

My Testing in 2007 and Upgrade to 2010

I created a new web app in 2007, added 2 site collections and a root site. The site collection called TeamTest had 2 pages customized, one with a hard coded master page and one with custom custom master page. The default page was not customized but a content editor web part with classic HTML added to the source.

Made a custom master page in the gallery called jim.master

Hardcoded jim.master to top of page with no token page is called notoken.aspx

Changed dynamic token to to custom master page page is called jimMasterProperly.aspx this is name of token used   "~masterurl/custom.master" also Added one content editor web part with classic html.

Add one content editor web part to default.aspx (Note: page directive is OOB MasterPageFile="~masterurl/default.master" )

Content db name is wss_content_www, 2010 web app is called Play Pen)

Used this powershell command to upgrade db into play pen – Mount-SpcontentDatabase –name WSS_Content_WWW –webapplication "Play Pen"

Upgrade succeeded, sites function but with errors as follows (these are the errors that SharePoint inserts into the small error log file that always accompanies an upgrade. To find more details, go to ULS log.

[powershell_ise] [SPContentDatabaseSequence] [WARNING] [4/20/2012 3:27:02 PM]: File [Features\ExcelServerSite\Microsoft.Office.Excel.WebUI.dwp] is referenced [1] times in the database [WSS_Content_WWW], but is not installed on the current farm. Please install any feature/solution which contains this file.

[powershell_ise] [SPContentDatabaseSequence] [WARNING] [4/20/2012 3:27:02 PM]: One or more setup files are referenced in the database [WSS_Content_WWW], but are not installed on the current farm. Please install any feature or solution which contains these files.

[powershell_ise] [SPUpgradeSession] [ERROR] [4/20/2012 3:28:19 PM]: CanUpgrade [SPSite Url=http://spu.sp.local/sites/TestPublishing] failed.

[powershell_ise] [SPUpgradeSession] [ERROR] [4/20/2012 3:28:19 PM]: Exception: Object reference not set to an instance of an object.

[powershell_ise] [SPUpgradeSession] [ERROR] [4/20/2012 3:28:19 PM]:    at Microsoft.SharePoint.Upgrade.SPSiteSequence.IsRootWebTemplate(Int32 templateId)
   at Microsoft.SharePoint.Upgrade.SPDelegateManager.GetDelegates(Object o)
   at Microsoft.SharePoint.Upgrade.SPDelegateManager.GetUpgraders(Object o)
   at Microsoft.SharePoint.Upgrade.SPUpgradeSession.CanUpgrade(Object o)

[powershell_ise] [SPUpgradeSession] [ERROR] [4/20/2012 3:28:19 PM]: Cannot upgrade [SPSite Url=http://spu.sp.local/sites/TestPublishing].

[powershell_ise] [SPUpgradeSession] [ERROR] [4/20/2012 3:28:34 PM]:    at Microsoft.SharePoint.Upgrade.SPSiteSequence.IsRootWebTemplate(Int32 templateId)
   at Microsoft.SharePoint.Upgrade.SPDelegateManager.GetDelegates(Object o)
   at Microsoft.SharePoint.Upgrade.SPDelegateManager.GetUpgraders(Object o)
   at Microsoft.SharePoint.Upgrade.SPUpgradeSession.CanUpgrade(Object o)

[powershell_ise] [SPUpgradeSession] [ERROR] [4/20/2012 3:28:34 PM]: Cannot upgrade [SPSite Url=http://spu.sp.local/sites/TestTeam].

In the ULS Log we found this error when attempting to perform an visual upgrade.

Microsoft.SharePoint.SPException: Visual Upgrade failed. The default master page for this user interface could not be found  at "/sites/TestTeam/_catalogs/masterpage/v4.master". Add the requested master page  at this path and try again.

image

Note this is a runtime error as unexpected, remember this for filtering in the ULS logs. This must be because this is the only site that has customized pages. Why is the v4 template missing?