Upgrade Customization Articles Posted
The deepest most comprehensive content on upgrading customizations is now available. The best minds on upgrade were put together to pull this off. This paper is based on a project I drove though Aeshen. From Bill Baer (MS IT), Sean Livingston (upgrade PM), Chris Gideon (product support), Boxin Li (dev), Shane Young (SharePoint MVP), Gabe Bratton (product support), Nakul Joshi (MCS) and more. I give you the names here to help you understand how good this stuff is. From upgrading themes to upgrading site defintions with an annotated upgrade mapping file, this paper has it.
Upgrading SharePoint Portal Server 2003 Customizations to SharePoint Server 2007 (Part 1 of 2)
Upgrading SharePoint Portal Server 2003 Customizations to SharePoint Server 2007 (Part 2 of 2)
Sometimes I know it's hard to know if this is a paper you want to dig into, so let me give you the table of contents and a couple of quotes to show you some of the goodies in this paper.
- 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
Here's a table for comparing upgrade methods:
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. |
Copy of a sample upgrade definition file that is annotated:
<Config xmlns="urn:Microsoft.SharePoint.Upgrade">
<!-- WebTemplate - Contains site template upgrade information.
ID - Contains unique integer for every upgrade definition.
LocalID - Determines the upgrade file to use during an upgrade; the
setting of "*" means this upgrade definition can be used unless a
locale-specific upgrade exists.-->
<WebTemplate
ID="1"
LocaleId="*"
<!-- FromProductVersion - When determining if a site can be
upgraded, the following algorithm is used to choose an upgrade
definition file:
1. If the Web site is not running on the latest product version,
Windows SharePoint Services chooses an upgrade definition file
that updates the site to the latest schema version. Upgrade
definitions can upgrade across versions, or across schemas, but
not both, which means that a definition cannot have both the
FromProductVersion and BeginFromSchemaVersion/EndFromSchemaVersion
attributes set. If no upgrade definition can be found to upgrade
the Web site across versions, the Web site cannot be upgraded.
2. If Number 1 does not apply, an upgrade definition file is chosen
such that the value of the ToSchemaVersion attribute most closely
matches the current schema version of the site definition (without
surpassing it), and the schema version of the existing site
instance falls in the range between BeginFromSchemaVersion and
EndFromSchemaVersion.
3. If more than one site upgrade definition passes the criteria
of Number 2, the upgrade definition with the highest
BeginFromSchemaVersion value is chosen.
4. If there is both a generic language and a specific locale
template for a given site definition, Windows SharePoint Services
chooses the specific locale template.-->
FromProductVersion="2"
BeginFromSchemaVersion="100"
EndFromSchemaVersion="149"
ToSchemaVersion="150">
<!--Lists element contains information about how to upgrade
existing lists.-->
<Lists>
<!--List element defines how to upgrade a specific list.-->
<List
<!--FromTemplateId specifies type of list from previous
SharePoint version.
ToFeatureId is the GUID of the content type feature that the list
is being upgraded to (maps to a feature ID defined in the
AppliedWebFeatures element).
V3Type is content type ID to which the old list is upgraded. -->
FromTemplateId="104"
ToFeatureId="00BFEA71-D1CE-42de-9C63-A44004CE0104"
v3Type="0x0104">
<Source v2List="104" />
</List>
<!-- List element attributes here are the same as above.-->
<List
FromTemplateId="105"
<!-- ToFeatureId maps to a Feature ID defined in the
AppliedWebFeatures element.-->
ToFeatureId="00BFEA71-7E6D-4186-9BA8-C047AC750105"
v3Type="0x0105">
<Source v2List="105" />
</List>
...
</Lists>
<!--Files element contains descriptions of relationships between
existing provisioned files and their equivalents for upgrading to a
new version.-->
<Files>
<File
<!--FromPath is the relative path of the file to upgrade.
Notice that {LocaleId} is used instead of the default full path
(\Program Files\Common Files\Microsoft Shared\web server
extensions\60\TEMPLATE).
ToPath is location in the setup directory of the file to which
the file of the old version is mapped, relative to the
\Program Files\Common Files\Microsoft Shared\web server
extensions\12\TEMPLATE directory.-->
FromPath="{LocaleId}\STS\default.aspx"
ToPath= "SiteTemplates\STS\default.aspx" />
<File
FromPath="{LocaleId}\STS\Lists\announce\AllItems.aspx"
ToPath= "Features\AnnouncementsList\announce\AllItems.aspx" />
<File
FromPath="{LocaleId}\STS\Lists\announce\DispForm.aspx"
ToPath= "Features\AnnouncementsList\announce\DispForm.aspx" />
<File
FromPath="{LocaleId}\STS\Lists\announce\EditForm.aspx"
ToPath= "Features\AnnouncementsList\announce\EditForm.aspx"/>
<File
FromPath="{LocaleId}\STS\Lists\announce\NewForm.aspx"
ToPath= "Features\AnnouncementsList\announce\NewForm.aspx" />
...
</Files>
<!--AppliedSiteFeatures element is a list of site collection
features to mark as "provisioned" for site collections created.
For example, an announcements list template of the previous version
must be mapped to its equivalent announcements feature in the new
version.-->
<AppliedSiteFeatures>
<!--Feature ID element is a feature to mark as "provisioned" for
Web sites or site collections created through the new version.-->
<Feature ID="00BFEA71-1C5E-4A24-B310-BA51C3EB7A57" />
</AppliedSiteFeatures>
<!--AppliedWebFeatures element is a list of Web site features to
mark as "provisioned" for Web sites created through the new version
of Windows SharePoint Services. For example, an announcements list
template of the previous version must be mapped to its equivalent
announcements Feature in the new version. -->
<AppliedWebFeatures>
<!--Feature ID element specifies a Feature to mark as "provisioned"
for Web sites or site collections created through the new version.
Note: The first feature ID maps to the first upgraded list. The
second feature ID maps to the second upgraded list.-->
<Feature ID="00BFEA71-D1CE-42de-9C63-A44004CE0104" />
<Feature ID="00BFEA71-7E6D-4186-9BA8-C047AC750105" />
<Feature ID="00BFEA71-DE22-43B2-A848-C05709900100" />
...
</AppliedWebFeatures>
</WebTemplate>
</Config>
