Upgrade examples: Upgrading three common customizations

Applies To: Office SharePoint Server 2007

This Office product will reach end of support on October 10, 2017. To stay supported, you will need to upgrade. For more information, see , Resources to help you upgrade your Office 2007 servers and clients.

Topic Last Modified: 2016-11-14

In this article:

• Example: Upgrading custom Web Parts

• Example: Upgrading custom navigation

• Example: Upgrading custom .CSS files and themes

If you have extensively customized your Microsoft Office SharePoint Portal Server 2003 sites (by using Microsoft Office FrontPage 2003), you need to determine how you want to handle your customized sites when you upgrade. Your approach will vary based on the extent of the customizations, the complexity of your site, and your goals for upgrading.

The examples in this article provide instructions for the following approaches for handling the customizations:

• Keep the customizations

  • Preserve the customizations and ignore new functionality.

  • Preserve the customizations and use new functionality.

• Remove the customizations

  • Remove the customizations or redo the customizations by using new functionality.

For more information about the different approaches to handle customizations, see Determine how to handle customizations (Office SharePoint Server).

Example: Upgrading custom Web Parts

You can upgrade custom Web Parts created for SharePoint Portal Server 2003 to Office SharePoint Server 2007 and continue using them in the new environment.

You can upgrade a custom Web Part from SharePoint Portal Server 2003 to Office SharePoint Server 2007 by using any one of the options described in the following sections.

Preserve the customizations and ignore new functionality

To preserve customizations and ignore new functionality, install the new version, but do not upgrade the customized site collection. You can run both versions side-by-side so that the site continues to run on SharePoint Portal Server 2003. The customizations are automatically preserved because the site is running on SharePoint Portal Server 2003. You can now use the environment to deploy additional Office SharePoint Server 2007 sites.

Preserve the customizations and use new functionality

To preserve customizations and take advantage of the new functionality in Office SharePoint Server 2007, upgrade the site by using any upgrade approach. The server and the site are upgraded to Office SharePoint Server 2007. Next, upgrade the customizations done in SharePoint Portal Server 2003.

Upgrade custom Web Parts

You need to test the Web Parts in ASP.NET 2.0 to verify that they will work in the new environment. In particular, you must rebuild or redeploy custom Web Parts if you:

• Have used the ASP.NET 1.1 obfuscation tools. Rebuild your Web Parts by using ASP.NET 2.0.

• Are moving to a new server farm by using the database migration path for upgrade. If you choose this upgrade path, redeploy your Web Parts to the new farm.

• Have stored your custom Web Parts in the \BIN folder and are not performing an in-place upgrade. Because upgrade does not upgrade items to the new \BIN folder, redeploy your Web Parts.

If you do not rebuild or redeploy custom Web Parts as described in the preceding list, custom Web Parts that were created in SharePoint Portal Server 2003 by using ASP.NET 1.1 cause the following error when run on Office SharePoint Server 2007:

Web Part Error: A Web Part or Web Form Control on this page cannot be displayed or imported. The type could not be found or it is not registered as safe.

Use the following procedures to compile all custom Web Parts that were developed in ASP.NET 1.1 into ASP.NET 2.0, and then add the Web Parts into the global assembly cache. The following steps use the Microsoft Visual Studio 2005 development system, but you can also use Visual Studio 2008 to upgrade a custom Web Part.

Upgrade a custom Web Part

1. Open the solution file of the Web Part that you want to upgrade in Visual Studio 2005. If the solution was built in Visual Studio 2003, the application prompts you to upgrade the code.

2. Open Project Properties, and then in the Signing section, assign a strong name to the Key file.

3. Build the project.

4. Click Start, and then Run.

5. Type Assembly, and then press Enter.

   • Drag and drop the compiled assembly into the global assembly cache.

6. Open the properties of the .dll file to retrieve the public key token.

7. To add custom components in Web.config file, open the Web.config file of the SharePoint site to which you want to add the Web Part.

   Note

   To find the correct Web.config file, in Internet Information Services (IIS) Manager, open the Properties dialog box for the SharePoint site. The path and file name for the Web.config file for that site is on the ASP.NET pane, in the File location box.

8. Add the following safe control tag for the Web Part in the Web.config file:

   <SafeControl Assembly='TestWebpart', Version=1.0.0.0, Culture=neutral, PublicKeyToken=1a61461e2e62b800" Namespace="TestWebpart" TypeName="*" Safe="True"/>

   • You can view the public key token and version from the global assembly cache.

9. Specify the assembly name and namespace from your application, and then save the changes.

10. Restart IIS by using the iisreset /noforce command. The .dll file is registered in the Web.config file.

Office SharePoint Server 2007 now detects the Web Parts you have added. Next, use the following procedure to populate the Web Part gallery.

Populate the Web Part gallery

1. On the top-level site of the site collection, on the Site Actions menu, point to Site Settings, and then click Modify All Site Settings.

2. On the Site Settings page, in the Galleries section, click Web Parts.

3. On the Web Part Gallery page, click New.

4. On the Web Part Gallery: New Web Parts page, select the Web Part that is recently upgraded, and then click Populate Gallery. The new Web Part is added to the gallery and is ready to use.

For more information, see the following resources:

• Upgrading SharePoint Portal Server 2003 Customizations to SharePoint Server 2007 (https://go.microsoft.com/fwlink/?LinkID=105294&clcid=0x409)

• Step-By-Step Guide to Converting Web Projects from Visual Studio .NET 2002/2003 to Visual Studio 2005 (https://go.microsoft.com/fwlink/?LinkId=110338&clcid=0x409)

Remove the customizations or redo the customizations by using new functionality

To remove the customizations and create a fresh site in Office SharePoint Server 2007, upgrade the server to Office SharePoint Server 2007 by using either the in-place or gradual upgrade method. Upgrade the site collection, and then reset all pages to use the default pages from the site definition and use the new features of Office SharePoint Server 2007.

When you use this approach, site owners can start with the new look and functionality, and then decide whether or not to customize the site again. If customization is required, site owners can re-create a new custom Web Part by using the features of Office SharePoint Server 2007.

Example: Upgrading custom navigation

SharePoint Portal Server 2003 has a few limitations in its navigation functionality. For example, on a team site, you can use the Quick Launch to go to lists and libraries within the site. However, you cannot go to the subsites in SharePoint Portal Server 2003. After upgrading the site to Office SharePoint Server 2007, you can access the subsites from the Quick Launch.

You can upgrade custom navigation components from a SharePoint Portal Server 2003 site to Office SharePoint Server 2007 by using any one of the options described in the following sections.

Preserve the customizations and ignore new functionality

To preserve customizations and ignore new functionality, install the new version, but do not upgrade the customized site collection. You can run both versions side-by-side so that the site continues to run on SharePoint Portal Server 2003. The customizations are preserved automatically because the site still runs on SharePoint Portal Server 2003. You can now use the environment to deploy additional Office SharePoint Server 2007 sites.

Preserve the customizations and use new functionality

To preserve customizations and use the new functionality in Office SharePoint Server 2007, upgrade the site by using any upgrade approach. The server and the site are upgraded to Office SharePoint Server 2007. Next, upgrade the customizations done in SharePoint Portal Server 2003.

Custom navigation controls are often implemented as Web Parts. You can use the procedure in the previous section to create custom navigation Web Parts. You may need to recompile the Web Part with the .NET Framework version 2.0 to ensure that the code remains functional. After recompiling, you can see the Office SharePoint Server 2007 navigation control and the custom navigation control on the same page.

Remove the customizations or redo the customizations by using new functionality

To remove the customizations and create a fresh site in Office SharePoint Server 2007, upgrade the site (by using either in-place or gradual upgrade), and then reset all the pages to the site definition. This enables you to use the default pages from the site definition and use the new features of Office SharePoint Server 2007.

When you use this approach, site owners can start with the new look and functionality, and then decide whether or not to customize the site again. If customization is required, site owners can re-create a new custom navigation by using the features of Office SharePoint Server 2007.

The following list shows the features available for navigation in Office SharePoint Server 2007:

• Subsites and pages

• Sorting

• Global navigation

• Current navigation

• Navigation editing and sorting

Example: Upgrading custom .css files and themes

You can upgrade sites created in SharePoint Portal Server 2003 to Office SharePoint Server 2007 if you want the sites to have the same look as in SharePoint Portal Server 2003.

Themes in SharePoint Portal Server 2003 are collections of style sheets and image files that you can use to apply an overall style to a SharePoint site. Themes are installed server-side as a directory that contains multiple resource files and also requires an entry in the SPThemes.xml file. Themes are a low-risk customization because a site collection is not modified when a template is applied. Instead, the effects appear client-side through the visual modification of Web pages by the theme's .css files.

You can upgrade a custom logo and style sheet on a SharePoint Portal Server 2003 site to Office SharePoint Server 2007 by using any one of the options described in the following sections.

Preserve the customizations and ignore new functionality

To preserve customizations and ignore new functionality, install the new version, but do not upgrade the customized site collection. You can run both versions side-by-side so that the site continues to run on SharePoint Portal Server 2003. The customizations are automatically preserved because the site is still running on SharePoint Portal Server 2003. You can now use the environment to deploy additional Office SharePoint Server 2007 sites.

Preserve the customizations and use new functionality

To preserve customizations and use the new functionality in Office SharePoint Server 2007, upgrade the site by using any upgrade approach. The server and the site get upgraded to Office SharePoint Server 2007. Next, upgrade customizations done in SharePoint Portal Server 2003.

If you created a custom site definition to include your customizations — such as custom pages, lists or libraries, plus .css files or themes — you need to create a new site definition for Office SharePoint Server 2007 and create an upgrade definition file to use during upgrade.

If you applied custom .css files or a theme to your sites based on a standard site definition, you can upgrade the site by using any upgrade approach and then redo your .css file and theme customizations. The styles and themes available have changed between the versions, so you might want to make different choices in the new environment. For more information about this approach, see "Remove the customizations or redo the customizations by using new functionality" later in this article.

Upgrade custom site definitions with the help of an upgrade definition file

An upgrade definition file provides a means to upgrade sites based on custom site definitions in SharePoint Portal Server 2003 so that they use features in Office SharePoint Server 2007. An upgrade definition file maps the files and list data of one build or version to a subsequent build or version, in addition to specifying additional items that should be placed within upgraded Web sites.

Use the following procedure to map the customizations made in SharePoint Portal Server 2003 — for example, custom lists and libraries, a custom .css file and custom logo — to Office SharePoint Server 2007. After you upgrade the site, you can view the look and feel as customized in SharePoint Portal Server 2003. Additionally, you can use the Office SharePoint Server 2007 functionality.

Use an upgrade definition file to map customizations made in SharePoint Portal Server 2003

1. Run Setup for Office SharePoint Server 2007.

   Important

   Do not run the SharePoint Products and Technologies Configuration Wizard now.

2. Copy the custom WEBTEMP file — for example, a file named WEBTEMPspscustom.XML, from the *<install drive>\*Program Files\Common Files\Microsoft Shared\Web server extensions\60\TEMPLATE\1033\XML folder to the <install drive>\%COMMONPROGRAMFILES%\Microsoft shared\Web server extensions\12\TEMPLATE\1033\XML folder.

   Note

   You must base the custom site definition you create in Office SharePoint Server 2007 on the custom site definition you created in SharePoint Portal Server 2003. Therefore, record the site definition on which you based the custom site definition. For example, if you created the original site definition from a portal site definition, you probably based it on a copy of the SPS site definition.

3. Create a custom site definition in Office SharePoint Server 2007 by performing the following steps:

   1. Copy the folder containing the base site definition that you used for your custom site definition in SharePoint Portal Server 2003 from <install drive>\%COMMONPROGRAMFILES%\Microsoft Shared\Web server extensions\12\TEMPLATE\SiteTemplates and paste it at the same location, creating a new folder.

   2. Rename the folder to match the custom site definition from SharePoint Portal Server 2003. In this example, the SPS folder that contained the standard site definition for SharePoint Portal Server 2003 was copied to spscustom in the …\60\TEMPLATE\SiteTemplates path when the custom site definition was created. Therefore, rename the new folder for the custom site definition for Office SharePoint Server 2007 spscustom in the …\12\TEMPLATE\SiteTemplates path.

4. Open the ONET.XML for the spscustom file located at <install drive>\%COMMONPROGRAMFILES%\Microsoft Shared\Web server extensions\12\TEMPLATE\SiteTemplates\spscustom\XML.

5. Compare the ONET.XML file to the ONET.XML file for the SharePoint Portal Server 2003 custom site definition, and then update it to include the changes you need.

6. Navigate to <install drive>\%COMMONPROGRAMFILES%\Microsoft Shared\Web server extensions\12\Config\Upgrade, copy SPSUpgradePremium.XML, and then rename it with a unique name, such as SPSUpgradecustom.XML.

7. Open the SPSUpgradecustom.XML file and change the WebTemplate ID.

      <WebTemplate

         RemoveSiteExternalSecurityProvider="true"

         ID="10001" <!-- We recommend that you change the ID to above 10000-->

         LocaleId="*"

         FromProductVersion="2"

         BeginFromSchemaVersion="0"

         EndFromSchemaVersion="0"

         ToSchemaVersion="10">

         <Lists>

8. In the SPSUpgradecustom.XML file, replace the site definition name.

   In this example, all instances of \SPS\ have been replaced with \spscustom\ for the Tasks list.

   <File

   FromPath="{LocaleId}\spscustom\Lists\tasks\active.aspx"

   ToPath="pages\viewpage.aspx"

   />

   <File

   FromPath="{LocaleId}\spscustom\Lists\tasks\AllItems.aspx"

   ToPath="pages\viewpage.aspx"

   />

   <File

   FromPath="{LocaleId}\spscustom\Lists\tasks\byowner.aspx"

   ToPath="pages\viewpage.aspx"

   />

   <File

   FromPath="{LocaleId}\spscustom\Lists\tasks\DispForm.aspx"

   ToPath="pages\form.aspx"

   />

   <File

   FromPath="{LocaleId}\spscustom\Lists\tasks\duetoday.aspx"

   ToPath="pages\viewpage.aspx"

   />

   <File

   FromPath="{LocaleId}\spscustom\Lists\tasks\EditForm.aspx"

   ToPath="pages\form.aspx"

   />

   <File

   FromPath="{LocaleId}\spscustom\Lists\tasks\MyItems.aspx"

   ToPath="pages\viewpage.aspx"

   />

   <File

   FromPath="{LocaleId}\spscustom\Lists\tasks\NewForm.aspx"

   ToPath="pages\form.aspx"

   />

9. Add a new entry of the ID of the custom site definition to the PreUpgradescanconfig.XML file at <install drive>\%COMMONPROGRAMFILES%\Microsoft Shared\Web server extensions\12\Bin.

   <?xml version="1.0" encoding="utf-8"?>

      <configurations>

         <customTemplate id="20"/>

         <customTemplate id="21"/>

         <customTemplate id="22"/>

         <customTemplate id="30"/>

         <customTemplate id="31"/>

         <customTemplate id="32"/>

         <customTemplate id="33"/>

         <customTemplate id="34"/>

         <customTemplate id="35"/>

         <customTemplate id="36"/>

         <customTemplate id="10001"/> <!-- Enter the template ID which you mentioned in SPSUpgradecustom.XML file -->

      </configurations>

10. Run the Pre-upgrade scan tool by performing the following steps.

    1. Click Start, and then Run.

    2. Type cmd in the Open box. The command prompt appears.

    3. At the prompt, change the directory to <install drive>\%COMMONPROGRAMFILES%\Microsoft shared\Web server extensions\12\Bin, type the following command, and then press ENTER:

       prescan /C preupgradescanconfig.xml /ALL

11. Run the SharePoint Products and Technologies Configuration Wizard. After the wizard completes, the Central Administration home page appears.

12. In Central Administration, on the Operations page, in the Upgrade and Migration section, click Site content upgrade status. You can view all the sites that need to be upgraded.

13. Click a site that you want to upgrade. The site is upgraded to Office SharePoint Server 2007.

Remove the customizations or redo the customizations by using new functionality

To remove the customizations and create a fresh site in Office SharePoint Server 2007, upgrade the server to Office SharePoint Server 2007, and then upgrade the site to use the new features of Office SharePoint Server 2007. By so doing, you enable site owners to re-design their sites. Site owners can create new sites and re-work the customizations by using the new features of Office SharePoint Server 2007. This is not a real upgrade path but a chance to improve the site's architecture.

To ignore customizations and create a fresh site in Office SharePoint Server 2007, upgrade the site (by using either in-place or gradual upgrade), and then reset all the pages to the site definition. This enables you to use the default pages from the site definition and use the new features of Office SharePoint Server 2007.

By using this approach, you can start with the new look and functionality of Office SharePoint Server 2007, and then decide whether or not to further customize the site again. If further customization is required, you can design a new custom style sheet taking advantage of the features of Office SharePoint Server 2007.

Although themes function identically in Office SharePoint Server 2007 and SharePoint Portal Server 2003, the tags that the .css files apply can be different. Most existing SharePoint Portal Server 2003 custom themes do not render correctly in the Office SharePoint Server 2007 environment. In most cases, you must re-create the custom themes so that they render correctly. During the upgrade process, you can consider using master pages, a new option in Office SharePoint Server 2007.

Master pages provide the look and feel and standard behavior that you want for all of the pages in your site. Together with layout pages, they produce output that combines the layout of the master page with content from the layout page. Because Office SharePoint Server 2007 is built on ASP.NET 2.0, it supports master pages for defining elements that are common to all pages. You can specify all the shared elements of a site in the master pages and add content page–specific elements to content pages.

For information about creating a Office SharePoint Server 2007 custom master page and page layouts for a Web content management site, see the following resources:

• How to Create a SharePoint Server 2007 Custom Master Page and Page Layouts for a Web Content Management Site (https://go.microsoft.com/fwlink/?LinkID=107863&clcid=0x409)

• Sample master pages overview (https://go.microsoft.com/fwlink/?LinkId=110372&clcid=0x409)

Download this book

This topic is included in the following downloadable book for easier reading and printing:

• Upgrading to Office SharePoint Server 2007

See the full list of available books at Downloadable content for Office SharePoint Server 2007.

See Also

Concepts

Determine how to handle customizations (Office SharePoint Server)
Determine upgrade approach (Office SharePoint Server)
Reapply customizations in the browser and Microsoft Office SharePoint Designer 2007