Upgrading SharePoint Portal Server 2003 Customizations to SharePoint Server 2007 (Part 1 of 2)

Summary: Learn the requirements to perform an upgrade of Microsoft Office SharePoint Portal Server 2003 customizations to Microsoft Office SharePoint Server 2007. This article is part 1 of 2. (26 printed pages)

Microsoft Corporation

November 2007

Applies to: Microsoft Office SharePoint Server 2007, Windows SharePoint Services 3.0

Contents

• Introduction to Upgrading SharePoint Customizations

• New SharePoint Concepts and Terminology

• Feature Introduction

• Determining the Upgrade Approach

• Determining How to Handle Customizations

• Deprecated APIs That Require Action

• Upgrading Customized Features Within SharePoint Products and Technologies

• Running the Pre-Upgrade Scan Tool

• Creating Upgrade Definition Files

• Upgrading Custom Site Definitions

• Upgrading Custom Site Templates

• Upgrading Areas and Listings

• Upgrading Areas Based on Custom Site Definitions

• Upgrading List Definitions

• Upgrading Customized (Unghosted) Pages

• Upgrading Custom Web Parts

• Upgrading Custom Event Handlers

• Upgrading Custom Themes and Style Sheets

• Upgrading Custom Code or Pages in Layouts Folders

• Inclusions or Exclusions

• Upgrading Third-Party Customizations

• Conclusion

• Additional Resources

Introduction to Upgrading SharePoint Customizations

The third generation of Microsoft SharePoint Products and Technologies introduces new functionality and enhancements that help organizations collaborate and access business intelligence. Microsoft Office SharePoint Server 2007 greatly streamlines the business process, but the deployment process requires some advanced planning on the part of the SharePoint administrator, especially when performing the upgrade from Microsoft Office SharePoint Portal Server 2003. This article provides the information required to perform the upgrade in an environment that has been customized, either slightly or significantly, from the base installation of SharePoint Portal Server 2003.

The upgrade process is not as simple as inserting a CD and running Setup. You need to carefully plan your approach, anticipate issues that might come up during or after the process, and consider your specific environment—especially when working with customized SharePoint sites and applications.

Because the upgrade process itself is documented on the SharePoint Server TechCenter on TechNet, the main focus of this article is how to identify customizations, what you should know before beginning the upgrade, and how to successfully upgrade customizations.

New SharePoint Concepts and Terminology

Microsoft Office SharePoint Server 2007 introduces new functionality and enhancements that help IT professionals deploy and maintain Office SharePoint Server 2007 solutions. Together, these new enhancements provide IT organizations with better control over information resources; individually these enhancements provide functional benefits that help reduce administrative overhead and help IT administrators work more efficiently and effectively. Changes that affect IT organizations and IT professionals include:

• An improved administration model that centralizes configuration and management tasks, and helps IT organizations delineate and delegate administrative roles.

• New and improved compliance features and capabilities that help organizations secure resources and manage business-critical processes.

• New and improved operational tools and capabilities that drive down the total cost of ownership (TCO).

• Improved support for network configuration.

• Improved extensibility of the SharePoint object model that helps to make custom applications and components easier to deploy and manage.

These changes mean that some of the ways that you are used to working with your sites and pages might not work or might not be the most effective. The following tables can help you understand some of the key changes to terminology and functionality that immediately affect the administration and site management process after upgrading. For more information about changes to Office SharePoint Server 2007, see What's New for IT Professionals in Office SharePoint Server 2007.

Table 1 lists updated or new concepts and terminology that reflect the new architecture and design of Office SharePoint Server 2007.

Table 1. Mapping terminology of SharePoint Portal Server 2003 to SharePoint Server 2007

SharePoint Portal Server 2003 Concept or Term	Office SharePoint Server 2007 Concept or Term	Comments
Virtual server	Web application	Change in terminology.
Shared services	Shared Services Providers	The architecture behind shared services has changed significantly, to allow easier and more flexible sharing of resources. For more information, see Plan Shared Services Providers.
Areas	Sites	SharePoint Portal Server 2003 areas are upgraded to sites that use the Publishing Site Template. To manage your site, on the Site Actions menu, click Manage Content and Structure.
Portal security	Windows SharePoint Services security	Portal security is now managed by using the new Windows SharePoint Services 3.0 security model. Groups and users are upgraded to this model. For more information about the new security model, see Plan Site and Content Security (Office SharePoint Server).
Custom authentication	New authentication choices	You can now use ASP.NET authentication methods, such as forms authentication, with Office SharePoint Server 2007 instead of creating a completely custom authentication solution. For more information, see Plan Authentication Methods (Office SharePoint Server).
	Rights management	Now available for documents stored in document libraries.
SharePoint Portal Server 2003 backward-compatible document libraries	Office SharePoint Server 2007 document libraries	SharePoint Portal Server 2003 backward-compatible document libraries are not supported for Office SharePoint Server 2007. You can move any content stored in these libraries into standard document libraries in Office SharePoint Server 2007. A tool for migrating this content is under development. For more information, see Perform Post-Upgrade Steps for a Gradual Upgrade (Office SharePoint Server) or Perform Post-Upgrade Steps for an In-Place Upgrade (Office SharePoint Server).

Feature Introduction

Windows SharePoint Services 3.0 introduces an inherently portable and modular functionality known as a Feature, which simplifies modifying sites through site definitions. A Feature is a package of Windows SharePoint Services elements that you can activate for a specific scope, and that helps users accomplish a particular goal or task.

Working with Features

Features reduce the complexity involved in making simple site customizations, and are robust when upgrades are applied to a deployment. Features eliminate the need to copy large chunks of code to change simple functionality. As a result, Features reduce versioning and inconsistency issues that may arise among front-end Web servers. Features make it easier to activate or deactivate functionality during a deployment, and administrators can easily transform the template or definition of a site by simply toggling a particular Feature on or off in the user interface. Features provide the following capabilities:

• Scoping semantics for determining where custom code runs

• Pluggable behavior for installing or uninstalling Features within a deployment

• Pluggable behavior for activating or deactivating Features at a given scope

• A scoped property bag for storing data required by a Feature within its scope

• The basis of a unified framework for distributed deployment of Windows SharePoint Services solutions

To implement a Feature, you add a subfolder containing a Feature definition within the Features setup directory (Local_Drive:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES). The Feature subfolder includes a Feature.xml file that defines the base properties of the Feature and lists elements bound to it, such as XML files containing element manifests and any other supporting files. A Feature folder may contain only a Feature.xml file, or it may contain a Feature.xml file and any number of supporting element files, including XML files, but also .aspx, .htm, .xsn, .resx, .dll, and other file types.

After creating the Feature folder, you can install and activate the Feature through command-line operations of stsadm.exe, or through the SharePoint object model. You can also activate a Feature through the user interface. Installing a Feature makes its definition and elements known throughout a server farm, and activating the Feature makes the feature available at a particular scope.

The Feature element is used in a Feature.xml file to define a Feature and to specify the location of assemblies, files, dependencies, or properties that support the Feature. A Feature includes a Feature.xml file and any number of files describing individual elements. Another Feature element from a different schema is used in an Onet.xml file to specify that a Feature be activated within a site definition.

Items that were previously contained within a large site definition file are broken out as separate elements within Features. An element is an atomic unit within a Feature. A Feature.xml file typically points to one or more XML files whose top-level <Elements> tag contains definitions for elements that support the Feature. Elements in Windows SharePoint Services 3.0 often correspond to what were discrete nodes in the Onet.xml or Schema.xml file of the previous version. There are several types of element—for example, a custom menu item or an event handler.

A Feature could provide, for example, a "My Favorite Items" functionality that includes the following elements:

• A custom list that stores, per user, a list of favorite items, which is created as a single hidden list per workspace when the Feature is enabled

• A custom menu item that is attached to all lists, named "Add to Favorites," which adds an item to the Favorites list

• A Web Part that implements usage data and link tracking to display the user's top 10 favorites at the top of a page

Each element of the Feature might not be very useful by itself, but when you enable the Feature on a site, all these elements add up to a complete solution.

Feature Stapling in Windows SharePoint Services 3.0

In Windows SharePoint Services 2.0, many of the customizations that organizations wanted required changes to the built-in site definitions. These types of customization were not supported by Microsoft because these files may need to be replaced by future service packs. To work around this limitation with the site definitions, you would copy the built-in definitions, make the required customizations, and hide the original definitions from the end user. This process would ensure that a service pack would not break the site definition.

In SharePoint Server 2007, Features enable you to turn functionality on and off within a site, even if the functionality was not in the original site definition. Although modifying the built-in site definitions is still not advisable or supported, you can use a process named Feature Stapling to attach a Feature to a site definition without modifying it in any way. For example, you can use this process to attach your custom application to the built-in definition.

To create a staple, you actually create another Feature that does the staple. Following is an excerpt from a SharePoint staple Feature we use to staple a Multilanguage Feature to the STS, BDR, and SPS site definitions.

Feature.xml file

<?xml version="1.0" encoding="utf-8" ?>
<Feature  Id="82E2EA42-39E2-4B27-8631-ED54C1CFC491"
  Title="$Resources:MultiLangStaplingFeatureName"
  Description="$Resources:MultiLangstaplingFeatureDescription"
  Version="12.0.0.0"
  Scope="Farm"
  xmlns="https://schemas.microsoft.com/sharepoint/"
  DefaultResourceFile="_Res">
  <ElementManifests>
    <ElementManifest Location="TransMgmtFunc.xml"/>
  </ElementManifests>
</Feature>

TransMgmtFunc.xml file that contains the FeatureSiteTemplateAssociation element

<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
  <FeatureSiteTemplateAssociation Id="29D85C25-170C-4df9-A641-
  12DB0B9D4130" TemplateName="STS#0" />
  <FeatureSiteTemplateAssociation Id="29D85C25-170C-4df9-A641-
  12DB0B9D4130" TemplateName="STS#1" />
  <FeatureSiteTemplateAssociation Id="29D85C25-170C-4df9-A641-
  12DB0B9D4130" TemplateName="BDR#0" />
  <FeatureSiteTemplateAssociation Id="29D85C25-170C-4df9-A641-
  12DB0B9D4130" TemplateName="SPS#0" />
</Elements>

The preceding code "staples" the Feature with the ID "29D85C25-170C-4df9-A641-12DB0B9D4130" to the STS#0, STS#1, BDR#0, and SPS#0 site definitions. This is very powerful because it enables you to add functionality to site definitions without modifying the site definitions. To staple your Feature to all site definitions, you can staple it to the GLOBAL site definition, and it will be added to all sites that are created.

For more information, see Chris Johnson's blog post Feature Stapling in WSS V3, and the Microsoft SharePoint Products and Technologies Team Blog entry Customizing MOSS 2007 My Sites Within the Enterprise.

Determining the Upgrade Approach

Before you run any upgrade process, you must determine which upgrade approach to take. You can follow one of several paths, depending on the needs of your organization. An in-place upgrade is used to upgrade all SharePoint sites at one time, which is best suited for very limited, single-server deployments or small deployments. In production, the in-place upgrade is suggested only for testing purposes, either in a separate test environment or by using a virtual network. The virtual in-place upgrade provides you with the ability to quickly roll back changes made during the upgrade through the use of undo disks.

For almost all upgrades, the gradual upgrade is the best path. A gradual upgrade allows finer control of the upgrade process by allowing one or more site collections to be upgraded at a time. The level of control offered by the gradual upgrade approach makes it the most desirable option for almost all environments. Both in-place and gradual upgrades take place on the same hardware on which your previous version is installed. A gradual upgrade is a better option than an in-place upgrade because it enables the administrator performing the upgrade to control how many site collections to upgrade at one time. In this way, large deployments can be upgraded gradually over several weekends while continuing to host the previous version sites. This is possible because you can continue to host the sites that are not yet upgraded on the same server as the upgraded sites.

If you are performing a gradual upgrade in a shared services environment, you can choose between two options:

• Upgrade the parent portal site first (recommended) or you can upgrade the child portal sites first, by using a new shared services provider. When performing this type of upgrade, you must follow specific steps (for guidance, see Perform a Gradual Upgrade with Shared Services).

• Migrate the lists and libraries from your Windows SharePoint Services 2.0 or SharePoint Portal Server 2003 environment to Windows SharePoint Services 3.0 or SharePoint Server 2007. This may also be an option when migrating from platforms such as Lotus Notes or Domino, collaborative shares, or collaborative public folders. This content migration upgrade approach simply copies the data into the new environment, dropping the UI and customizations. The migration API is built into the product allowing for a fairly flexible method of pushing content in and setting the appropriate metadata columns.

If you are either moving to new hardware or redesigning and restructuring your deployment, you can migrate your databases from the old version to the new version rather than directly upgrading them. When you perform a database migration, you perform an in-place upgrade on the databases, but you do not upgrade your server farm configuration data. Although this upgrade path has more manual steps than either an in-place or a gradual upgrade, it can be the best option if you have highly customized sites or custom Web services or applications. For information about database migration, see Chapter Overview: Deploy a New Farm, Then Migrate Databases (Office SharePoint Server 2007) on Microsoft TechNet.

If your organization has a significant amount of data to migrate, then a multithreaded database attach method can provide you with a quicker and potentially more flexible path than the gradual approach and the basic database migration. In the multithreaded approach, you create two or more front-end Web/query/index servers with a common SQL Server environment. You can find information about this approach on Bill Baer's blog on Microsoft TechNet.

If your environment is highly customized, you might want to get back to an environment that is more supportable or easier to upgrade by purposely removing some of the customization. The approach of migrating and then upgrading will serve that purpose. Basically, you migrate your customized environment into a clean Windows SharePoint Services 2.0 or SharePoint Portal Server 2003 environment, and then use the stsadm backup and restore commands to migrate the site collections into a clean database with a built-in file system and _layouts folder. This reduces the customization and overhead of the upgrade, and you can focus on running one of the three simple upgrades: in-place, gradual, or database migration. With this approach, you can focus on using many of the built-in features available in Windows SharePoint Services 3.0 and SharePoint Server 2007 that were not available in the earlier versions.

Table 2. Comparison of upgrade approaches

Approach	Description	Advantages	Disadvantages	Best for
In-place upgrade	Upgrades the content and configuration data in place, at one time.	Sites retain original URLs. Updates existing databases and servers by using existing hardware.	Environment is offline while it runs. No ability to revert to original site. Limited capability for all but smallest deployments. Unable to manage customizations. Often fails, not recommended for inexperienced administrators.	Single-server or small server farm. Suggested for testing purposes only (see virtual in-place upgrade).
Virtual in-place upgrade	Upgrades the content and configuration data in place within a virtualized environment.	Easy to rollback changes by using undo disks. No need for the physical hardware.	Timely trial-and-error process.	Single-server or small server farm. Suggested as a preferred alternative to regular in-place upgrade.
Gradual upgrade (recommended)	Installs the new version side-by-side with the previous version. The server administrator determines which site collections to upgrade and when to upgrade them.	Enables a more granular approach: You can upgrade at the site collection level. Reduces the amount of time any single user is affected. Sites retain original URLs. Can revert to original site. Uses existing hardware.	More complex and resource-intensive. Must redirect URLs during upgrade process, which causes issues for some client applications such as Microsoft Office. Requires extra storage in Microsoft SQL Server. Microsoft Windows SharePoint Services 2.0 scalable hosting mode is not supported.	Medium or large server farms (without shared services) with many sites for which you must limit downtime. Good when your environment has many customizations.
Gradual upgrade for shared services	The same as gradual upgrade but with separate upgrade passes to upgrade parent portal sites and child portal sites.	Same as gradual upgrade, but allows you to upgrade parent and child portal sites individually.	Same as gradual upgrade, plus: Two search crawls are active at the same time for the SharePoint Portal Server 2003 and SharePoint Server 2007 environments.	Server farm of any size with shared services.
Content migration	Only migrate lists and libraries from the Windows SharePoint Services 2.0 or SharePoint Portal Server 2003 environment to SharePoint Server 2007.	Supported by migration partners such as AvePoint, DocAve, and Tzunami Deployer.	Loses any customizations to the environment.	Situations where the content is important, but the customized templates are expendable.
Database migration (advanced)	Requires the server administrator to install the new version on a separate farm or separate hardware, and then manually migrate the databases into the new environment.	Enables moving to new farm or new hardware. SharePoint Portal Server 2003 environment is available and is untouched by upgrade.	Complex process that requires many manual steps and involves a higher risk of error. Requires additional manual steps to retain original URLs for sites. Search scopes must be re-created and search settings must be reapplied. Requires new server farm, and twice the amount of SQL Server storage space.	Those who are moving to new hardware or a new architecture. Those who need to maximize upgrade throughput. This approach is required for Windows SharePoint Services 2.0 environments that use scalable hosting mode or Active Directory directory service account creation mode.
Multithreaded database attach	Database migration approach, but creating two or more front-end Web/query/index servers in the SQL Server environment.	Multiple threads of data reduce the amount of time required to transfer data between the databases.	Same drawbacks as Database Migration. Advanced setup steps required.	Environments requiring a Database Migration approach with large amounts of data to migrate.
Migrate then upgrade	Migrates data into a clean Windows SharePoint Services 2.0 or SharePoint Portal Server 2003 environment (losing the existing customizations), and then upgrades the deployment.	Brings the environment from a highly customized, difficult to support configuration to a more manageable, built-in configuration.	Any customizations required by the organization must be re-created.	Environments with a very high level of customization, which creates a deployment that is difficult to manage and support.

Additional information and suggestions about choosing an upgrade path are available on Joel Oleson's SharePoint Land blog.

Determining How to Handle Customizations

If you have extensively customized your SharePoint Portal Server 2003 sites (by using Microsoft Office FrontPage 2003), you need to determine how 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. You can choose to keep the customizations, throw out the customizations, or redo the customizations:

Throw Out the Customizations

If you are planning a complete site redesign, or if you are significantly changing the information architecture, then the upgrade is your chance to start over with a new look or a new organization. There are two ways to throw out your customizations and start with a fresh site:

• Upgrade (either in-place or gradual) and reset all pages to use the default pages from the site definition. After an in-place upgrade, use Microsoft Office SharePoint Designer 2007 to reattach the default page layouts. For more information, see Building tylerbutler.com, Part 4:The Main Home Page and Migrating Content.

  For a gradual upgrade, use the upgrade option to reset the entire Web site to use the site definition pages. With this approach, you can start with the new look and functionality, and then decide whether to customize the site again. Site owners can reapply customizations when they review the upgraded sites.

  Note

  If you added a completely custom page to your site (for example, if you replaced default.aspx with a different file rather than making changes to the existing default.aspx file), that page has no association with the site definition and cannot be reattached to the page layout. If you want your custom page to have the same look and feel as the other pages in your site, consider creating a page based on the site definition and transferring your content to that new page.

• Start fresh with a new site in the new environment. This approach works when you are dramatically redesigning your site and you do not need to have either the structure or most of the content in the new site. Create a new site, create a new site design, and transfer your content into the new site. This is not an upgrade path, but rather an opportunity to design your new site from the beginning. For a list of Microsoft SharePoint Partners that can help in this process, see Additional Resources.

Keep the Customizations

Although this approach allows you to keep the same look and feel, you are not able to take advantage of the new capabilities available in the new version. This approach is generally discouraged because it results in mismatched SharePoint 2007 pages, which can result in confusion. If you really want your pages to look just as they did, there are three ways to keep the customizations:

• Do an in-place upgrade. By default, an in-place upgrade preserves customizations and does not reset to the site definition. Some controls, such as the Site Actions menu, might not be available in your upgraded site.

• Do a gradual upgrade, and keep the site in the previous version environment (do not upgrade the site). This maintains the site exactly as it is, with the previous version functionality only. This is usually a short-term solution, because most organizations do not want to support both versions over the long term.

• Do a gradual upgrade and upgrade the site, but do not reset any pages to the site definition. This approach might result in an uneven look if you did not customize every page. Customized pages retain the previous version's look and functionality, and pages that are not customized have the new version's look and functionality. Some controls, such as the Site Actions menu, breadcrumbs, and the new navigation, will not be available in your customized pages.

  Note

  By default, custom pages are kept as is after upgrade (except for themes).

Redo the Customizations

This approach allows you to take advantage of the new capabilities, modify your design slightly if you want, and move to a more manageable design. You can take advantage of the new master pages model to apply your design, rather than customizing each individual page. Converting customized landing pages to use page layouts instead also reduces future maintenance costs, because you can simply change the page layouts rather than changing each individual page. There are three ways to redo the customizations:

• Do an in-place or gradual upgrade and do not reset the pages to the site definition version. After upgrade, modify the appropriate master pages and page layouts in the upgraded site to take on the previous version's look and feel, and then reattach the page layouts to all customized pages. This gives all formerly customized landing pages the same look as the site before upgrade. You can incorporate the new controls, such as the Site Actions menu, into your new page layouts as part of this work.

• Do an in-place upgrade and do not reset the pages to the site definition. After upgrade, open the site and copy the customizations, then reattach the page layouts and reapply your customizations to the master pages and page layouts, as appropriate. By default, an in-place upgrade preserves customizations and does not reset the pages to the site definition version. When you open the site by using a Web page editor compatible with SharePoint Server 2007, such as Microsoft Office SharePoint Designer 2007, you can copy the customizations and then reset the original pages to get the new functionality. Then you can reapply any customizations to the master pages and page layouts that still make sense. Doing this process with an in-place upgrade is somewhat complicated because you need to copy the customized pages before resetting them. Consider using the following gradual upgrade method instead.

  Note

  If you perform an in-place upgrade, you cannot revert to the previous version of the site. To have the previous version and the new version of the site side by side so that you can transfer customizations from the previous version site to the new version site, use a gradual upgrade—or, if you are performing an in-place upgrade, ensure that you first create a copy on another server or server farm that is running the previous version.

• Do a gradual upgrade and, in the upgraded site, reattach the page layout. Then transfer the customizations from your original site to the master pages and page layouts in the upgraded site by using Office SharePoint Designer 2007. This option provides you with the most flexibility. Because you can refer to the original site, you can see exactly how you did the previous customizations. And because you reattached the page layouts, you can see the new functionality and decide which customizations to reapply to the master pages and page layouts and which to ignore.

  For more information about reapplying customizations after upgrade, see Reapply Customizations in the Browser and Microsoft Office SharePoint Designer 2007 and Reset a Customized Page to the Site Definition.

To determine which Windows SharePoint Services 2.0 customized site templates are deployed and used within the organization, you must use the pre-upgrade scan tool to scan your Windows SharePoint Services 2.0 environment. Running the pre-upgrade scan tool is part of the Windows SharePoint Services 3.0 upgrade process and is described in Running the Pre-Upgrade Scan Tool.

Using the pre-upgrade scan tool, you must scan your sites, and then fix any errors before you perform the upgrade. If you have not successfully run this tool before you attempt to upgrade your environment, when you do run the SharePoint Products and Technologies Configuration wizard, it will exit and prompt you to run the scan tool.

Deprecated APIs That Require Action

All object model changes in Office SharePoint Server 2007 were made with strong consideration for backward-compatibility with SharePoint Portal Server 2003. So even though you may encounter a completely redesigned area of the object model, such as areas, your code should work. You should be aware, however, that your earlier code, although functional, might not perform in the way you expect in the new object-model hierarchy.

If you upgrade applications that use deprecated classes or members, and when you write new applications, you must use the new classes or members in the applications for them to work properly in Office SharePoint Server 2007. For a lists of the APIs that are deprecated in Office SharePoint Server 2007 either because of the introduction of a new feature or enhancements in an existing feature, see SharePoint Portal Server 2003 APIs Deprecated in Office SharePoint Server 2007 and SharePoint Portal Server 2003 APIs That Do Not Work in Office SharePoint Server 2007.

Upgrading Customized Features Within SharePoint Products and Technologies

Organizations with a large investment in SharePoint Products and Technologies are recipients of significant innovations in the enterprise collaboration and portal capabilities. More often than not, as the implementation has grown, so has the significant customization of Windows SharePoint Services 2.0 and SharePoint Portal Server 2003 to achieve organization goals.

Some organizations have consciously practiced a controlled growth model. In those, administrators who are well-versed and trained in SharePoint Portal Server design, architecture, and best practices have also been able to apply design and usage guidelines to enable all areas of the organization to benefit. Conversely, organizations that have not devoted resources to tightly manage and plan the SharePoint Portal Server infrastructure must often handle multiple unwanted management effects. These include the uncontrolled propagation of sites and portals, inconsistent security models and access right delegation (for example, everyone is an administrator), stale or aging portals that are no longer used, and other aspects of uncontrolled usage and growth.

Regardless of the growth model within the organization, the migration to SharePoint Server is one that requires organizations to completely understand their SharePoint Portal Server environments. For the latest information about this topic, see Governance Information for SharePoint Server 2007 on Microsoft TechNet.

The second part of this two-part article (Upgrading SharePoint Portal Server 2003 Customizations to SharePoint Server 2007 (Part 2 of 2)) focuses on how to address individual customizations to each part of the SharePoint Products and Technologies architecture, including templates, site definitions, Web Parts, event handlers, customized (unghosted) pages, themes, style sheets, custom code or pages, inclusions, exclusions, and third-party customizations. In each section, we discuss the issues, suggest upgrade paths, and provide links to additional information about how to address the customization during the upgrade. For specific information about how to prepare for and to execute the actual upgrade process, see Upgrading to Office SharePoint Server 2007 on Microsoft TechNet.

Running the Pre-Upgrade Scan Tool

Before you perform an upgrade, you must use the pre-upgrade scan tool (prescan.exe) to scan your sites and then you must fix any errors. If you do not successfully run this tool and you attempt to upgrade your environment, when you attempt to run the SharePoint Products and Technologies Configuration wizard, the wizard will exit and prompt you to run the tool. We highly recommend that the server administrator run the pre-upgrade scan tool before the upgrade, and resolve any problems that can be resolved before scheduling the upgrade.

For each SharePoint site, issues reported by this tool include the existence of the following objects:

• Customized site templates. You must know which site templates are customized for a particular site so that you can verify the customizations again after the upgrade.

• Orphaned objects. Objects such as list items, lists, documents, Web sites, and site collections can be orphaned—that is, the objects exist but are not associated with a particular site. Because orphaned objects do not work in the previous version, they will not work after the upgrade. If you perform an in-place upgrade, the orphaned items still exist but do not work. If you perform a gradual upgrade, orphaned items are not copied to the new site. We recommend that you clean up any orphaned objects before upgrading.

  Note

  Members of the Administrators group on the front-end Web servers can recover orphaned items before the upgrade by following the steps in Knowledge Base article 918744, Description of a New Command-Line Operation That You Can Use to Repair Content Databases in Windows SharePoint Services.

• Custom Web Parts. Report the existence of custom Web Parts to the appropriate site administrator or developer before upgrading, to give the administrator or developer time to investigate. Heavily obfuscated custom Web Parts might need to be rebuilt and redeployed after the upgrade.

• Sites that are based on languages or that use controls that are not installed. If the database contains a Web site based on a language template pack that is not currently installed on the front-end Web servers, or a Web site uses controls (such as the Microsoft Office Web Components) that are not currently installed on the front-end Web servers, install the missing language packs or controls before upgrading.

Figure 1 shows a segment of a summary file. It shows the site template, Board of Directors—Basic, and lists all of the pages in the site template. A customized page is denoted by the unghostedPage element at the beginning of the URL tag for the page. A site is customized if one or more of its pages are customized (unghosted).

Figure 1. Sample of a summary file

Use the information gathered from the pre-upgrade scan tool to determine:

• Whether to perform an in-place upgrade or a gradual upgrade.

• Upgrade approach. Office SharePoint Server provides information to help you decide which type of upgrade to perform. It is important to consider the report generated by the pre-upgrade scan tool when making this decision. Generally, if you find significant issues, use a gradual upgrade rather than an in-place upgrade so that you can resolve the issues.

• Whether to upgrade some or all site collections that contain customized sites.

• Which sites need to have customizations reapplied or redone after upgrade and therefore might take longer than others in the review stage.

To install the prescan.exe tool, first install SharePoint Server 2007 on a test server, then search for the prescan.exe file and preupgradescanconfig.xml file and copy these to the computer running the existing version.

At the command prompt, change to the folder that contains the two files, and then run the following command to scan all servers in your server environment.

prescan.exe /c preupgradescanconfig.xml /all

You can specify that the pre-upgrade scan tool scan all Web sites in your environment by using the /all parameter command, or scan a specific URL by using the /vURL parameter command. If you do not supply a scoping parameter, all Web sites are scanned.

To download the pre-upgrade scan tool from the Microsoft Download Center, see SharePoint Products and Technologies Utility: Pre-Upgrade Scan Tool.

If you already installed the new version but have not yet run the SharePoint Products and Technologies Configuration wizard, you can run the pre-upgrade scan tool from the following folder: %PROGRAMFILES% \Common Files\Microsoft Shared\web server extensions\12\BIN. The amound of time it takes to run the scan can vary from several minutes to a few hours, depending on the amount of content in your environment.

After the scan completes, a summary report is displayed in the Command Prompt window. If there are any errors or if any upgrade issues are found for your sites, you can review the full report to see the details. The report is named PreupgradeReport_uniqueID_Log.txt (where uniqueID is a number string) and it is located in the temp directory on the computer of the user who ran the tool (for example, %SYSTEMDRIVE%:\Documents and Settings\User1\Local Settings\Temp). There is also a prescan.log file in the same directory; this prescan.log file notes the time or times when the pre-upgrade scan tool was run.

You can use the reports to find and troubleshoot issues (search for "error" in the report to find the issues). You can also share the relevant pre-upgrade scan test results with other members of the upgrade team. For example, you can report issues such as customized site templates or custom Web Parts to the appropriate site owner, Web designer, or developer before scheduling the upgrade to give them time to investigate the issues and take preliminary steps. For example, a designer or developer might decide that it would be prudent to rebuild a heavily obfuscated Web Part before the upgrade occurs. Site owners can then verify any customizations that were done to their sites, including changes to site templates and to core Active Server Pages Extension (ASPX) files, and can note any potential issues.

For a list of common errors, see You Receive an Error Message When You Run the Pre-Upgrade Scan Tool (Prescan.exe) to Scan Windows SharePoint Services 2.0 Sites Before You Upgrade to Windows SharePoint Services 3.0.

Creating Upgrade Definition Files

A site upgrade definition file describes how to map a customized previous-version site definition to a new-version site definition. The goal of a site upgrade definition file is to give developers a tool to transform their previous-version sites into new-version equivalents that take advantage of all the improvements the new version offers.

For Office SharePoint Server 2007, there are additional page template upgrade definition files for specific page templates (also known as page layouts). A page template is an Active Server Pages Extension (ASPX) file that defines the structure of a page. Page templates enable you to create new pages based on the page template, rather than editing the pages in a Web page editor that is compatible with Office SharePoint Server 2007. Page templates are stored at the top-level (root) of the site collection and are shared across the site collection.

In Office SharePoint Server 2007, page templates are used for most pages in the portal site. All new-version site definitions for Office SharePoint Server 2007 include page templates, and many portal pages that were based on the standard portal site definition in the previous version are based on different page layouts in the new version. The upgrade process moves portal pages from the previous version to pages that use page templates in the new version. Page templates from the previous version are moved to the default set of page templates that are included with the new version. If the default set of page templates does not meet your needs, you can create a custom set and provide an upgrade definition file to map the older portal pages to the new page templates.

An upgrade definition file for a site definition has the following sections:

• WebTemplate. Specifies upgrade information for the entire Web template. You need one <WebTemplate> tag per upgrade definition file.

• Lists. Specifies upgrade information for each list or library in the template. In the Lists section, you need one <List> tag per list or library.

• Files. Specifies upgrade information for the individual pages in the template. In the Files section, you need one <File> tag for each uncustomized (ghosted) page in the template.

• Applied SiteFeature and Applied WebFeature. Specifies upgrade information for any site collection–level features or subsite-level features included in the template. In the Applied SiteFeature and Applied WebFeature sections, you need one <Feature> tag for each feature at that level in the template.

For more information about creating upgrade definition files, including a sample upgrade definition file, see Upgrade Definition Files and Upgrade Definition Schema in the Windows SharePoint Services 3.0 SDK.

The following example, taken from one of the files installed in Office SharePoint Server 2007, outlines the format for a page template upgrade definition file.

<SPSSiteUpgraderConfig>
  <PublishingPageLayoutMappings>
    <PublishingPageLayoutMapping WebTemplateId="20" 
    PublishingPageLayout="/_catalogs/masterpage/defaultlayout.aspx"/>
    <PublishingPageLayoutMapping WebTemplateId="22" 
    PublishingPageLayout="/_catalogs/masterpage/welcomelayout2.aspx"/>
  </PublishingPageLayoutMappings>
</SPSSiteUpgraderConfig>

This example shows that a Web site template maps to a page template; the Web site template with ID=20 maps to the page layout=defaultlayout.aspx. This means that every site that uses the template ID of 20 has a home page (usually default.aspx) that uses a page layout defined by defaultlayout.aspx.

Create Upgrade Definition Files

Give the upgrade definition file a unique name that begins with the name of the site definition. For example, for a site definition named STS1, name the upgrade definition file STS1_upgrade.xml. You must install upgrade definition files to the following path: %WinDir%\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\Config\Upgrade.

For more information, see Deploy Upgrade Definition Files and New Site Definitions. For more information about creating upgrade definition files, such as what to include in the files and the schema to follow, see the Microsoft Office SharePoint Server 2007 SDK.

Upgrading Custom Site Definitions

Site definitions in SharePoint Portal Server 2003 include the set of presentation (ASPX) and configuration (XML) files from which all SharePoint sites and lists are derived. Site definitions contain all the configuration data for the site and are stored on the file system of each front-end Web server. As sites are created, SharePoint Portal Server references these files to define the layout, structure, and initial content. The site definition is referenced by each list and page that is derived from the site definition.

Site definitions are similar in SharePoint Server 2007 to their counterparts in SharePoint Portal Server 2003. One notable change is that site definitions no longer use a single monolithic Onet.xml file to define the structure of the site and various Schema.xml files to define the structure of lists and views. SharePoint Server 2007 relies on Features to define what is linked to a specific site definition.

In Windows SharePoint Services 2.0 and SharePoint Portal Server 2003, many types of customization required you to customize site definitions, which usually involved copying the STS site definition and modifying list schemas, pages, and other structural elements in the copied definition. Large parts of the custom site definition were not customized, which meant that they maintained many of the same basic traits as the STS site definition.

Recommended Upgrade Method

The way to obtain a Windows SharePoint Services 3.0 equivalent for a custom site definition created in Windows SharePoint Services 2.0 varies depending on the site definition. If you did not heavily customize the site definition in relation to the Windows SharePoint Services 2.0 site definition on which it was based, the best option may be to create a Windows SharePoint Services 3.0 equivalent for that site definition and retrofit the new definition to include Windows SharePoint Services 2.0 customizations. For example, if your only customization to a Windows SharePoint Services 2.0 site definition was the addition of a custom list, or a copy of the STS site definition and customization of the Default.aspx page for a custom look and feel, then you should probably re-create the customization by using the Windows SharePoint Services 3.0 STS base site definition. If your customizations were more extensive, however, it is probably wiser to convert the Windows SharePoint Services 2.0 site definition into a Windows SharePoint Services 3.0 equivalent.

Because Windows SharePoint Services is deeply integrated with ASP.NET 2.0, the structure of ASP.NET pages (.aspx files) used in SharePoint sites has changed significantly. When hosting a Web site based on a Windows SharePoint Services 2.0 site definition, Windows SharePoint Services executes pages in a compatibility mode to ensure that they function within the deployment. However, when running pages from a Windows SharePoint Services 3.0 site definition, Windows SharePoint Services does not run the pages in compatibility mode for performance reasons. As a result, when you create your Windows SharePoint Services 3.0 site definition, you must modify your ASP.NET pages to some extent.

If you have not customized ASPX pages in your Windows SharePoint Services 2.0 site definition, it is good practice to copy the Default.aspx page of the Windows SharePoint Services 3.0 STS site definition (located in the path 12\TEMPLATE\SiteTemplates\sts\xml) into your site definition.

All Web Part pages must now contain an ASP.NET Web Part manager to function properly. Consequently, if you have customized ASPX pages, you must add a Web Part manager to them, which you do by inserting <WebPartPages:SPWebPartManager id="m" runat="Server" /> into the pages.

The structure of the Onet.xml file has changed in fundamental ways. If you did not customize Onet.xml in your Windows SharePoint Services 2.0 custom site definition, it is good practice to copy the Windows SharePoint Services 3.0 Onet.xml from the path 12\TEMPLATE\SiteTemplates\sts\xml into your site definition.

In Windows SharePoint Services 3.0, all XML files in the setup directory are converted to use resource expressions ($Resources) to make them work for any language for which language packs are installed. To make a Windows SharePoint Services 2.0 site definition work for multiple languages, and to benefit from this expanded use of resources, you must make many changes in the Windows SharePoint Services 2.0 XML files. In this case, it might be best to copy the Windows SharePoint Services 3.0 STS site definition and add then your customizations to it.

If you customized the Onet.xml file in your Windows SharePoint Services 2.0 site definition, you must modify the file to work in Windows SharePoint Services 3.0. The following basic steps can help make your Windows SharePoint Services 2.0 Onet.xml file more consistent with a Windows SharePoint Services 3.0 site definition:

• To ensure that Web sites created through your definition consistently use the new Windows SharePoint Services 3.0 base list types, remove the <BaseTypes> section from your Windows SharePoint Services 2.0 Onet.xml file. Base list types are now included by default in SharePoint sites and do not need to be defined in your file.

• Remove standard lists from the Windows SharePoint Services 2.0 Onet.xml file. Many lists required for SharePoint functionality are now included by default in Windows SharePoint Services 3.0 and do not need to be defined in your Onet.xml file. For more information, see Upgrading List Definitions.

• Remove the <ListTemplate> tag for lists where the Name attribute equals webtemp, listtemp, wplib, or datasrcs. Also remove the underlying list definitions for these lists by removing the LISTS\WEBTEMP, LISTS\LISTTEMP, LISTS\wplib, and LISTS\DATASRCs folders. Remove each <List> tag from the Configurations section where the Type attribute equals 113 (Web template gallery), 114 (list template gallery), or 111 (Web Part gallery).

• Consider mapping the DocumentTemplates section to Windows SharePoint Services 3.0 document templates. The system of expressing document templates in a site definition has not changed significantly in Windows SharePoint Services 3.0. Document templates are still stored in a per-locale directory.

• For your specific site definition, you must ensure that you have the corresponding set of document template files in the path \12\TEMPLATE\locale ID\site definition name. However, if your document template files are not customized, you can simply make your site definition reuse document templates. To do this, annotate each <DocumentTemplate> node in your Onet.xml file to specify Path="STS".

After you have customized your site definition, test it in Windows SharePoint Services 3.0 to ensure that new Web sites created through the definition behave as expected. After you have created the proper Windows SharePoint Services 3.0 site definition, the next step is to create an upgrade definition to map your site definition from Windows SharePoint Services 2.0 to Windows SharePoint Services 3.0.

For more information about how to complete this process, see Chapter 3: Preparing a Site Template Based on a Customized Site Definition in the Upgrade Toolkit for Windows SharePoint Services Sites and Templates Guide on Microsoft TechNet.

For more information about upgrading your custom site definitions, updating ASPX files, and editing the Onet.xml, see Upgrading a Custom Windows SharePoint Services 2.0 Site Definition.

For more detailed information about working with upgrade definition files, see Upgrading SharePoint Portal Server 2003 Customizations to SharePoint Server 2007 (Part 2 of 2).

Upgrading Custom Site Templates

A custom site template is a package that contains a customized site design based on an existing site definition. Site templates in this context exist outside any site definition. The site definition is a server-side collection of files that define the structure of one or more site templates. When a user customizes a site or list in the user interface, the custom template consists of the difference between the original state of the site or list as determined by its definition and the state of the site when the custom template is generated. Custom templates remain tied to a particular site definition (for example, the one for a SharePoint site or a Meeting Workspace site), so that if the site definition is not present or is changed, the custom template will not work.

A custom template is persisted as a file with the .stp file name extension. When a site template is used to create a new site collection or site, the site definition that it is based on will be referenced, but any modified files will be stored directly into the database and considered customized (unghosted).

Recommended Upgrade Method

The Solution Accelerator Team (SAT) has created the Upgrade Toolkit for Windows SharePoint Services Sites and Templates Guide Solution Accelerator, which provides guidance and tools to enable IT professionals to successfully upgrade their Windows SharePoint Services 2.0 custom sites and templates. Following the guidelines in this Solution Accelerator results in a set of custom sites and templates that operate in a Windows SharePoint Services 3.0 environment.

The Upgrade Toolkit for Windows SharePoint Services Sites and Templates serves two main purposes:

• To provide IT professionals with the guidance and tools to upgrade customized Windows SharePoint Services 2.0 sites and site templates to function in a Windows SharePoint Services 3.0 environment. The upgraded sites and site templates maintain their customizations and acquire a set of Windows SharePoint Services 3.0 Features.

• To provide a set of upgraded application templates for Windows SharePoint Services based on those currently published for Windows SharePoint Services 2.0 on TechNet and to provide instructions for installing these application templates in a Windows SharePoint Services 3.0 environment.

Before you begin, there are two important points you should know about the custom site template upgrade process:

• The Windows SharePoint Services site template upgrade process is performed as part of the upgrade to Windows SharePoint Services 3.0.

• The process is composed of two stages: One stage is performed before your environment is upgraded from Windows SharePoint Services 2.0 to Windows SharePoint Services 3.0, and the other is performed after the upgrade is complete. These steps are addressed in detail in the Upgrade Toolkit for Windows SharePoint Services Sites and Templates.

Upgrading Areas and Listings

The object model, user interface, and architecture of areas and listings have changed. Areas now use Windows SharePoint Services 3.0 Web architecture, so the URLs of sites change. Bucket Web sites are removed during upgrade. In a clean installation, the user gets portal sites that are named just like new Windows SharePoint Services 3.0 sites. SharePoint Services 2.0 listings do not exist in Office SharePoint Server 2007. A new summary links Feature displays links on a page.

Recommended Upgrade Method

To preserve data and functionality, upgrading moves listings to an Office SharePoint Server 2007 list and uses the Content Query Web Part (CQWP) to display the items on a page. We recommend that you manually move upgraded data to summary links, because this is the new feature for displaying, sorting, and grouping links on a page.

During upgrade, areas are automatically moved to sites and bucket Web site URLs are removed. You must change favorites and other externally saved links. Upgrading automatically moves listings to an Office SharePoint Server 2007 list and a CQWP. News listings are also upgraded to Link lists or pages. We recommend that you manually move the data to the summary links Feature to receive all of the benefits of easy in-page link editing. To do this, you must add a summary links Web Part or control to the page, and then manually copy links from the upgraded list to the summary links Web Part.

Upgrading Areas Based on Custom Site Definitions

The SharePoint Portal Server 2003 area is built on top of Windows SharePoint Services 2.0 site functionality. The area as a whole provides additional functionality beyond the Windows SharePoint Services site, but as far as Windows SharePoint Services is concerned, the area-backing site is just another Windows SharePoint Services site based on a custom site definition. Windows SharePoint Services cannot fully upgrade a site created from a custom site definition without additional information because it does not know the full extent of the customizations. During the upgrade, an upgrade definition file must be provided to upgrade the custom SharePoint Portal Server area, similar to the process of upgrading a custom Windows SharePoint Services site.

Recommended Upgrade Method

A custom SharePoint Portal Server area, derived from one of the default area definitions, contains two sets of customizations as it appears to Windows SharePoint Services, one made by SharePoint Portal Server, and one made by the end user. To upgrade a custom area created from a custom site definition, you must provide an upgrade definition file that tells Windows SharePoint Services how to upgrade both sets of customizations.

To complete this upgrade, you must complete five major steps. The first four steps are completed after the binary installation before the actual upgrade process; the last step is completed after the upgrade has completed successfully.

Start by creating a custom webtemp*.xml file in the Windows SharePoint Services 3.0 location %SystemDrive%\Program Files\Common Files\Microsoft Shared Debug\Web Server Extensions\12\TEMPLATE\LCID\XML. For example, name this file webtempCUSTOM.xml. Add the following code to this XML file.

<?xml version="1.0" encoding="utf-8"?>
<Templates xmlns:ows="Microsoft SharePoint">
  <Template Name=" SPSCUSTOM " ID="10001">
    <Configuration ID="0" Title="Custom Area Template" Type="0" 
    Hidden="TRUE" ImageUrl="../images/spshome.gif" Description="This is 
    a custom area template."/>
  </Template>    
</Templates>

Then you must create the Windows SharePoint Services 3.0 equivalent of the 2.0 area definition. Most custom templates are created by copying and modifying an existing template, such as the SPSTOPIC template. Identify the template that was used to create your 2.0 template, and then find the corresponding template in Windows SharePoint Services 3.0 in the path %SystemDrive%\Program Files\Common Files\Microsoft Shared Debug\Web Server Extensions\12\TEMPLATE\SiteTemplates. Copy this template into the same directory and rename the file with a name such as SPSCUSTOM. By comparing the original 2.0 custom template to the new 3.0 custom template, you can apply the customizations to the new template.

To take advantage of the page layout functionality, you need to specify which layout page to use for the area welcome pages. Navigate to the path %SystemDrive%\Program Files\Common Files\Microsoft Shared Debug\Web Server Extensions\12\CONFIG\UPGRADE, and then open SiteUpgraderConfigSPS.xml. The file contains the following code.

<?xml version='1.0'?>
<SPSSiteUpgraderConfig>
  <PublishingPageLayoutMappings>
    <PublishingPageLayoutMapping WebTemplateId="20" 
    PublishingPageLayout="/_catalogs/masterpage/defaultlayout.aspx"/>
    <PublishingPageLayoutMapping WebTemplateId="22" 
    PublishingPageLayout="/_catalogs/masterpage/welcomelayout2.aspx"/>
    <PublishingPageLayoutMapping WebTemplateId="30" 
    PublishingPageLayout="/_catalogs/masterpage/welcomelayout2.aspx"/>
    <PublishingPageLayoutMapping WebTemplateId="31" 
    PublishingPageLayout="/_catalogs/masterpage/welcomelayout2.aspx"/>
    <PublishingPageLayoutMapping WebTemplateId="32" 
    PublishingPageLayout="/_catalogs/masterpage/welcomelayout2.aspx"/>
    <PublishingPageLayoutMapping WebTemplateId="33" 
    PublishingPageLayout="/_catalogs/masterpage/newshomelayout.aspx"/>
    <PublishingPageLayoutMapping WebTemplateId="34" 
    PublishingPageLayout="/_catalogs/masterpage/welcomelayout2.aspx"/>
    <PublishingPageLayoutMapping WebTemplateId="36" 
    PublishingPageLayout="/_catalogs/masterpage/welcomelayout2.aspx"/>
  </PublishingPageLayoutMappings>
</SPSSiteUpgraderConfig>

Under the <PublishingPageLayoutMappings> node, add another entry under <PublishingPageLayoutMapping> with the following code.

<PublishingPageLayoutMapping WebTemplateId="10001" 
PublishingPageLayout="/_catalogs/masterpage/customlayout.aspx"/>

This line tells Windows SharePoint Services that for all welcome pages in areas created by using the new custom area template with an ID of 10001, use CustomLayout.aspx as the page layout. The *.aspx and ID can be set to any value that is not already in use by Windows SharePoint Services. If the goal is to duplicate the Windows SharePoint Services 2.0 look and feel, copy the 2.0 default.aspx page and add the 3.0 Web Part manager control code <WebPartPages:SPWebPartManager id="m" runat="Server" />. However, some functionality is not available if you use this method.

The recommended method of creating the layout page is to copy the built-in Windows SharePoint Services 3.0 layout page and modify the copy to meet your needs. A good layout page to copy is located in the path %SystemDrive%\Program Files\Common Files\Microsoft Shared Debug\Web Server Extensions\12\TEMPLATE\FEATURES\PortalLayouts\welcomelayout2.aspx. Ensure that the Web zone IDs stay the same as in Windows SharePoint Services 2.0, or you will have Web Parts in the wrong zone or moved off to the page gallery after upgrade.

Now you must create the upgrade definition file. You can create this file by searching and replacing a few strings, depending on the type of customization you did to the custom area template. The upgrade definition file can have multiple <WebTemplate> nodes with each outlining how to upgrade sites created from a particular site template. For this example, the custom area template is based on the SPSTOPIC template (ID=31).

To create the upgrade definition file

1. Open the SPSUpgradePremium.xml file (or SPSUpgrade.xml depending on the SKU) in the path %SystemDrive%\Program Files\Common Files\Microsoft Shared Debug\Web Server Extensions\12\CONFIG\UPGRADE, and locate the <WebTemplate> node with ID=31.

2. In the path %SystemDrive%\Program Files\Common Files\Microsoft Shared Debug\Web Server Extensions\12\CONFIG\UPGRADE, create an XML file that contains the following text.

   <?xml version="1.0" encoding="utf-8"?>
   <Config xmlns="urn:Microsoft.SharePoint.Upgrade"> 
   </Config>
   

3. Copy the entire ID=31 <WebTemplate> from SPSUpgradePremium.xml to the new file under the <Config> node.

4. Change ID to 10001 and replace the text SPSTOPIC with SPSCUSTOM.

We recommend that you create your own upgrade definition file (rather than modify the existing upgrade definition file). Modifying any existing upgrade definition file is not supported and causes problems when installing patches.

There are four subnodes in the <WebTemplate> node:

• <Lists> maps a list ID to the corresponding list Feature ID. If you turned any of the 2.0 custom lists into Features ("featurized" them), you must add an entry to this node.

• <Files> maps an old setup path (ghost path) to the new path. For example, if an area template has moved from a directory under an LCID to a global directory, you need the following entry to tell the upgrade how to fix the setup path.

  <File FromPath="{LocaleId}\SPSCUSTOM\default.aspx" ToPath="SiteTemplates\SPSCUSTOM\default.aspx" />
  

  Also, the lists definitions are moved out of site definitions, and their support files are moved to a global directory. As a result, you need entries such as the following.

  <File FromPath="{LocaleId}\SPSCUSTOM\Lists\announce\AllItems.aspx" ToPath="pages\viewpage.aspx" />
  

  Add one entry for each custom file that has its setup path moved.

• <AppliedSiteFeatures> is useful only if the custom template can be used to create the root site in a site collection. Because Windows SharePoint Services 2.0 does not allow a custom home area template, this tag is irrelevant during the upgrade.

• <AppliedWebFeatures> allows you to specify what Features to turn on for areas created by using the custom template during upgrade. The Features that have their IDs already listed here are all required for upgrade to work correctly. You can add others as needed.

Finally, after upgrade has finished successfully, navigate to the master page and Page Layouts gallery at http://servername/_catalogs/masterpage/Forms/AllItems.aspx, and then click Upload in the toolbar to upload the page layouts.

For more information, see the Microsoft SharePoint Products and Technologies Team Blog entry How to Upgrade an Area Based on a Custom Site Definition.

Upgrading List Definitions

List definitions in Windows SharePoint Services 2.0 are contained within site definitions. In Windows SharePoint Services 3.0, the list definitions are moved into SharePoint Features to make them more easily accessible to all site definitions. For this reason, you no longer need to redefine lists that you do not intend to customize within your site definition.

Recommended Upgrade Method

If you have not customized any standard list definitions, simply remove the standard Windows SharePoint Services 2.0 list definitions from your site definition and replace them with a reference to the standard Windows SharePoint Services 3.0 team collaboration Feature.

To remove the standard list definitions from your site definition

1. Remove the<ListTemplate> tags in Onet.xml for the following list types: custlist, gridlist, doclib, imglib, voting, discuss, favorite, announce, contacts, events, tasks, xmlform, and issue.

2. Remove the supporting list directories for these Windows SharePoint Services 2.0 list definitions. That is, for your Windows SharePoint Services 3.0 site definition, you can remove the Windows SharePoint Services 2.0 ANNOUNCE, CONTACTS, CUSTLIST, DISCUSS, DOCLIB, EVENTS, FAVORITE, GRIDLIST, IMGLIB, ISSUE, TASKS, VOTING, and XMLFORM folders from \LISTS.

3. In each of the <Configuration> tags within your Onet.xml file, add a reference to the team collaboration Feature, as follows.

   <Configuration ...>
     <WebFeatures>
       <!-- TeamCollab Feature -->
       <Feature ID="00BFEA71-4EA5-48D4-A4AD-7EA5C011ABE5" />
     </WebFeatures>
   </Configuration>
   

If you have customized specific list definitions (for example, the document library definition [DOCLIB]), then you must use a different approach. Replace all the uncustomized lists as mentioned previously (in this case, all lists except DOCLIB). Instead of adding a reference to the team collaboration Feature in your <Configuration> tags, add specific references to the Features that contain list definitions that you have not customized.

If you have customized only the document library (DOCLIB) list definition in your Windows SharePoint Services 2.0 site definition, add Feature references for Features that are scoped to a site collection or Web site within the <Configuration> tags of your Onet.xml file. Add references for every Feature except the document library definition, so that this list definition maintains your customizations.

For additional information about this process, see Upgrading Standard List Definitions.

Upgrading Customized (Unghosted) Pages

Site definition files are cached in memory on the server at process startup of Internet Information Services (IIS). This improves scalability and performance by reducing unnecessary data storage or retrieval, and by allowing pages that are not customized to be reused across sites. The information contained in these files is pulled from the cache at run time. Pages and list schemas are read from the site definition files but appear to be actual files within a site, which is why these files are referred to as uncustomized or "ghosted."

When site pages are customized by using FrontPage or other means, with the exclusion of browser-based customizations such as modifications to Web Parts, the pages become customized or "unghosted," and their contents are stored in the database. Windows SharePoint Services 2.0 does not natively provide a means for removing customization from ("re-ghosting") pages. In addition, uploaded .aspx files are automatically considered customized (unghosted).

When upgrading to Office SharePoint Server 2007, any page that is still in its ghosted state immediately benefits from the Office SharePoint Server 2007 look and feel. However, any page that is customized (unghosted) maintains the SharePoint Portal Server 2003 look and feel, unless you revert the page to the site definition. When you revert to the site definition, the page appears in the default look and feel format.

Recommended Upgrade Method

You can take three possible approaches to upgrading customized (unghosted) pages, depending on your preference.

• With default site definitions and customized (unghosted) home pages, the primary decision is whether to revert to the site definition or not. When the upgrade takes place, only those pages that are in the default (uncustomized or ghosted) state take on the new look and feel (such as new breadcrumbs, top navigation, and security trimmed UI). With customized (unghosted) sites, you must reset the site definition for the entire site or reset it page-by-page by using the Site Actions menu to access Site Settings, and then clicking Reset to Site Definition. For additional explanation and instructions, see Reset a Customized Page to the Site Definition.

• Reset the site definition on the sites in the Administration UI as they are upgraded. This administration option is available on the Central Administration page, from the Operations tab. Navigate to Site Collection Upgrade, click Actions, and then click Upgrade Settings. Choosing this option resets all pages in the sites that are upgraded while this is enabled.

• Revert sites to the site definition during the upgrade process from the command line. This can be accomplished by using the command-line option. For more information, see Upgrade Sites by Using the Command Line.

Upgrading Custom Web Parts

A Web Part is an ASP.NET server control that serves a particular purpose, such as displaying data from a worksheet or streaming stock quotations from an online Web service. Web Parts are inserted in Web Part zones on Web Part Pages. Web Part zones are containers for Web Parts; they group and organize Web Parts and provide a set of properties that configure the Web Parts in that zone. Web Part Pages consolidate data and Web content through Web Part zones to create dynamic information portals.

Web Parts in SharePoint Portal Server 2003 are small, configurable server-side components that normally render HTML code that is returned to the client browser. Web Parts can require server-side assemblies to be installed if the Web Part requires server-side code, and these assemblies can be installed either in a virtual server–specific Bin directory or in the global assembly cache of the server. Web Parts installed in the global assembly cache are upgraded as is. Web Parts in the global assembly cache during a gradual upgrade must be re-registered; only in-place upgrade retains the registration. We do not recommend using in-place upgrade if you have any customizations, because of the likelihood of failed upgrades in conjunction with customizations.

Recommended Upgrade Method

Most custom Web Parts continue working after upgrade. However, you should test your 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:

• Used the ASP.NET 1.1 obfuscation tools; you must 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, you must redeploy your Web Parts to the new farm.

• Have stored your custom Web Parts in the \BIN folder and are not upgrading in-place. Gradual upgrade does not upgrade items to the new \BIN folder, so you must redeploy your Web Parts.

To upgrade your Web Parts, test them in ASP.NET 2.0, and then either rebuild or redeploy any Web Parts that meet the previous criteria.

Upgrading Custom Event Handlers

Event handlers in SharePoint Portal Server 2003 can be registered only for document libraries. Event handlers consist of server-side installed assemblies that are referenced individually at each document library that should become event-enabled. Additionally, the virtual server that hosts the document library must be set to allow event handlers to expose the document library advanced settings where event handlers are referenced. Only a single event handler can be referenced on any one document library.

Many developers use the event handlers in Windows SharePoint Services to execute custom managed code behind document libraries or form libraries. The goal of Windows SharePoint Services 3.0 is to provide developers with an even richer platform for developing custom integration points and building new types of applications on top of the infrastructure. For this purpose, the event handlers in Windows SharePoint Services 3.0 are extended in scope and depth in many ways. SharePoint Server 2007 provides many new events and even allows for synchronous events, allowing you to launch an event before data is committed. No longer are event handlers just for items you create; they are also for lists and sites you create.

Recommended Upgrade Method

If you have custom event handlers configured for your environment, you must reapply the event handlers or use new Features to perform the tasks instead. We recommend that you use a Feature instead of a custom event where it is practical to do so.

For more information, see How to: Create an Event Handler Feature and Feature Events.

During the upgrade process, many other considerations might take precedence over the existing custom event handlers. To account for this, Office SharePoint Server 2007 provides you the ability to continue using the Windows SharePoint Services 2.0 event handlers. From the Central Administration page, click the Application Management tab, and then click Web Application General Settings. From the Web Application General Settings page, scroll to the Backward-Compatible Event Handlers section to enable or disable this functionality.

Upgrading Custom Themes and Style Sheets

Themes in SharePoint Portal Server 2003 are collections of style sheets and image files that you 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, effects appear client-side through the visual modification of Web pages by the themes CSS file.

As a general rule, if you are using a SharePoint Portal Server 2003 theme, you should consider creating an Office SharePoint Server 2007 theme. Because themes can be more effective than master pages at branding a site, it is usually only necessary to create a master page if you want to change the structure of a page.

Recommended Upgrade Method

Although themes function identically in Office SharePoint Server 2007 to how they functioned in 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 recreate the custom themes so that they can render correctly. During your upgrade process, however, you should consider using master pages, which is a new option in 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 Windows SharePoint Services 3.0 is built on top of ASP.NET 2.0, it supports master pages for defining elements that are common to all pages. You can specify all of the shared elements of your site in the master page or pages, and add content page–specific elements to content pages.

For more information, see Master Pages and Windows SharePoint Services Default Master Pages.

When you install Windows SharePoint Services, a single default master page is applied to all the pages in a site. You can, however, create your own master pages for a site and make them available to the site and any sites beneath it. For more information about customizing master pages, see Customizing Master Pages in Windows SharePoint Services.

Upgrading Custom Code or Pages in Layouts Folders

The _layouts directory in SharePoint Portal Server 2003 contains many files that are common to the functioning of each site. This directory is available to each site through the relative path URL/_layouts. Any changes made in the _layouts directory apply across all sites hosted on the same server. These pages are stored in the virtual directory for the SharePoint Web application. The _layouts directory is also virtualized as a subfolder of every SharePoint site, and is exposed in a site collection or subsite, for example, http://MyServer/_layouts/Mysite.aspx or http://MyServer/a/b/c/_layouts/Mysite.aspx.

Recommended Upgrade Method

Windows SharePoint Services 2.0 _layouts pages typically refer to built-in 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 navigates users from /_layouts/Locale_ID/nameofoldpage.aspx to /_layouts/newpage.aspx.

For customized sites that are using the _layouts folder, remember that Office SharePoint Server 2007 no longer contains a "bin" directory in the _layouts virtual directory, so all pages must use inline code.

For more information, see Upgrading Pages and Web Parts and Application _layouts Page Type.

Inclusions or Exclusions

In Windows SharePoint Services 2.0, there are two categories of paths you can manage: included and excluded. An included path indicates that Windows SharePoint Services manages that path. An excluded path indicates that the path is managed by a different application (Windows SharePoint Services should leave it alone).

Recommended Upgrade Method

When performing content database migration steps, it is important that all inclusion paths, custom Web Parts, and custom site definitions are reapplied. Inclusion paths (such as /teams or /mysites) are commonly missed. When completing the upgrade, ensure that all inclusion paths are re-created. This is not necessary for exclusion paths because those are now assumed by default.

You can manage paths in SharePoint Products and Technologies by using the HTML Administration Pages. To include or exclude a new path, use the Define Managed Paths page for the virtual server that contains the path.

From the command prompt, by using the STSADM tool, use the addpath and deletepath operations are to manage paths. Both operations take the -url and -type parameters. The -type parameter has three values: exclusion, explicitinclusion, and wildcardinclusion. For example, to add a new wildcard inclusion to manage all sites at the top level of http://server1, you would use syntax like the following.

stsadm -o addpath -url http://server1/ -type wildcardinclusion

For more information, see Managing Paths in the Administrator's Guide for Windows SharePoint Services.

Upgrading Third-Party Customizations

Office Web Components (OWC)

Microsoft Office Web Parts and Components is a collection of Web Parts, Web Part Page solutions, templates, and data-retrieval services that work closely with Microsoft Office 2003 and Windows SharePoint Services 2.0. These added functionalities were particularly useful for large organizations that deployed the Microsoft Office system throughout their organization and wanted to take advantage of the enhanced functionality and efficiencies these Web Parts and components provided for their sites.

The Office Web Components (OWC) are a set of ActiveX controls that provide four principal components: Spreadsheet, Chart, PivotTable, and Data Source Control (DSC). In the 2007 Microsoft Office system, these Office Web Components are no longer installed.

OWC are being discontinued because a more flexible technology is required to help customers address the following needs that are not addressed by OWC:

• A server-side Microsoft Office Excel calculation engine

• Greater parity with Office Excel when worksheets are delivered over the Web

• The ability to enable worksheets to be more scalable and stable when loaded onto a server

• Improved security

• The ability to perform more detailed analysis to improve overall business intelligence

To address these customer challenges, the Enterprise Client Access License (CAL) version of Office SharePoint Server 2007 includes a technology named Excel Services, which includes the following:

• A server-side Excel calculation engine

• The ability to enable browser-based worksheet viewing and interactivity

• Web service access to the spreadsheet calculation engine in Excel

For additional information about Excel Services, see Excel Services Overview or the MSDN Blog Posts Category Excel Server.

Recommended Upgrade Method

There are a couple of items to consider if you are currently using solutions that use OWC. If the solutions are meeting your present needs, then you can continue to use OWC. However, if you feel that OWC is lacking certain features and is failing to address your needs, be aware that OWC is being discontinued and no functionalities will be added. Many browser-based OWC solutions might be migrated to use the new, thin Excel capabilities on the server, but the server does not provide a complete superset of functionality (for example, typing into any cell in the worksheet or adding new measures or dimensions to a PivotTable view from the browser is not supported).

If you need to install the Office Web Parts after upgrading, you can do this by locating three CAB files in the path Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\wppacks: Microsoft.sharepoint.solutions.greatplains.cab, Microsoft.sharepoint.webparts.quickquote.cab, and Microsoft.office.dataparts.cab. These files are explained in Shane Young's blog post How to Manually Install the Office Web Parts in SharePoint v3. After you find the CAB files, add each of them by using the following stsadm.exe command.

stsadm.exe -o addwppack -filename "c:\program files\common 
files\microsoft shared\web server 
extensions\60\wppacks\microsoft.office.dataparts.cab" -globalinstall

For more information about issues related to the upgrade of Office 2003 Web Parts and components, see Cannot View a SharePoint Services 3.0 Web Site After You Migrate a Windows SharePoint Services 2.0 Content Database.

RSS

RSS is a new syndication technology that has become popular over the last several years. Essentially, RSS is an XML file (also called a "feed," "Web feed," or "channel") that contains either a summary of content from a Web site or the full text. RSS feeds enable content publishers and consumers to exchange information in a simple and elegant way. A publisher produces an RSS feed and makes it available at a location (URL). Consumers (software that is a "feed reader" or "aggregator") read the feed and reformat the information for display. SharePoint Products and Technologies understand XML and are well suited to process RSS. Updated content such as blog entries, news headlines, or podcasts are examples of what might be published as RSS feeds.

Recommended Upgrade Method

In the previous versions of SharePoint Products and Technologies, there was no default support for RSS feeds, so many organizations added RSS functionality by installing add-ons. Because Office SharePoint Server 2007 provides this functionality, we recommend transferring your third-party RSS add-on to the native Office SharePoint Server 2007 interface. The feature itself is installed and enabled automatically after the upgrade. By navigating to a list or document library, you can select View RSS Feed from the Actions menu.

MSNBC Web Parts Discontinued

MSNBC Web Parts have been discontinued in the online Web Part gallery for Windows SharePoint Services. Web Parts that link to MSNBC now return the following error:

Cannot display information. This Web Part requires a connection to the Internet and Microsoft Internet Explorer 5.0 or later running on a Windows operating system. Customers are advised to remove these Web Parts as soon as it is convenient to do so.

Recommended Upgrade Method

If your pages contain these Web Parts, you should remove the Web Parts completely. To obtain up-to-date or live data in a Windows SharePoint Services site, we recommend that you pull data from an RSS feed. If you need additional help with this topic, search or post your own questions on the TechNet Forums Site for SharePoint Products and Technologies.

Next step: Upgrading SharePoint Portal Server 2003 Customizations to SharePoint Server 2007 (Part 2 of 2).

Conclusion

The third generation of Microsoft SharePoint Products and Technologies introduces new functionality and enhancements that help organizations collaborate and access business intelligence. Microsoft Office SharePoint Server 2007 greatly streamlines the business process, but the deployment process requires the administrator to plan ahead, especially when performing the upgrade from Microsoft Office SharePoint Portal Server 2003. This article provides the information needed to perform the upgrade in an environment customized from the base installation of SharePoint Portal Server 2003.

Additional Resources

For more information, see the following resources:

• Upgrading SharePoint Portal Server 2003 Customizations to SharePoint Server 2007 (Part 2 of 2)

2007 Microsoft Office System

• Microsoft Office Online

• 2007 Microsoft Office System Suites (comparison of the product suites)

• Microsoft Office Enterprise 2007 Product Guide

• White Papers and Book Excerpts for Office SharePoint Server 2007

Microsoft SharePoint Products and Technologies

• Microsoft Office SharePoint Server 2007 (product marketing home page)

• SharePoint Community Portal

• Microsoft Office SharePoint Server 2007 Products Comparison Download

• Windows SharePoint Services 3.0 Evaluation Guide

• Windows SharePoint Services Version Comparison

• Microsoft Office SharePoint Server 2007 Product Guide

• Microsoft Office SharePoint Server 2007 Feature Comparison

Upgrade Solutions from Microsoft SharePoint Partners

• CorasWorks Design Migrator

• Echo Technology (for SharePoint Server 2007)

• AvePoint (DocAve platform)