Use a trial upgrade to find potential issues (SharePoint Server 2010)


Applies to: SharePoint Server 2010

Before you begin the process of upgrading from Microsoft Office SharePoint Server 2007 to Microsoft SharePoint Server 2010, you will want to test the upgrade process to make sure that you know exactly what you have to do to have a successful upgrade. By using a trial upgrade to test the process, you can find out:

  • What customizations you have in your environment, so that you can plan for how to deal with them during upgrade.

  • Whether you should upgrade your hardware to make your upgrade run more efficiently and more quickly.

  • The timing for your upgrade, or how long upgrade will take for your environment.

  • What you need to plan for, operationally — for example, resources to have available.

In addition, you can use the trial upgrade to become familiar with the upgrade tools and the process itself, so that you know what to expect when you go through the actual process. Through testing, you can find out:

  • Which special cases apply to your environment and which upgrade approach will be most efficient for you?

  • What does the upgrade user interface look like? How do you know when you have finished one phase and are moving through another?

  • Where are the log files, and how do you read them? What information do they provide?

  • Which techniques can you use to mitigate downtime?

This article provides basic steps for testing upgrade, and it gives recommendations for reviewing the results and adjusting your upgrade plans based on what you learn during the tests.

In this article:

  • Set up a test environment

  • Identify and install customizations

  • Copy real data to the test environment and try the upgrade

  • Review results

  • Adjust your plans and test again

In addition, the following resources can be helpful when you test your upgrade process:

Set up a test environment

You can use either virtual or physical hardware to test the upgrade process. Every environment is unique, so there are no general guidelines for how long upgrade will take or how difficult a particular customization will be to upgrade. The best way to gauge how your upgrade will go is to perform a series of trial upgrades.

When you create your test environment:

  • Make your test farm as similar as possible to your real farm — for example, hardware, software, and space available.

  • Use the same URLs in your test farm as in your real farm. (Otherwise, you will waste time diagnosing issues relating to the URLs that will not come up in the real upgrade.)

  • Be sure that you transfer all of your settings and customizations to the test environment. The section Identify and install customizations provides information about gathering this information.

Using a virtual test environment

When you test by using a virtualized environment, you do not need a lot of hardware. You can replicate your environment by using just two servers that are running Hyper-V. One server has images for the front-end Web servers and application servers, and the other server has images for the database servers.

Virtual test environment for trial upgrade

Using a physical test environment

When you test by using a physical environment, you need to replicate your entire server farm environment as closely as possible. If you simplify the number of front-end Web servers, application servers, or database servers too much, you will not have an accurate estimate of how long the upgrade process will take and you may not account for complications that arise from interactions between servers in the same role (such as SQL Server transactions). If you have multiple servers in a role in your original farm, use at least two servers for that role in the test farm to test for such issues.

Physical test farm for a trial upgrade

Additional test environments for database attach upgrade

If you are using the database attach upgrade approach, you might need to create one additional test environment: a single server farm that is running Office SharePoint Server 2007 that you can use to run the pre-upgrade checker before you attempt to upgrade the data.

You can avoid this step by running the pre-upgrade checker on your existing production farm.

Identify and install customizations

To have an accurate test process, you must find all the customizations in your current environment and copy them to the test environment. For more information about the types of customizations you need to identify, see Determine how to handle customizations (SharePoint Server 2010).

  • Use the pre-upgrade checker to identify site definitions, site templates, and features in your environment.

    The pre-upgrade checker steps through each site collection and generates a report about the state of each site. It also saves list definition information for each list. You can review the reports to find issues and address them before you start the upgrade process. Unlike the pre-upgrade scan tool for Office SharePoint Server 2007, the pre-upgrade checker is a read-only tool and does not change your sites. For more information about this tool and steps for running it, see Pre-upgrade scanning and reporting for future releases (Office SharePoint Server) and Run the pre-upgrade checker (SharePoint Server 2010).

  • Use the Stsadm –o enumallwebs operation on all content databases in your Office SharePoint Server 2007 environment to identify specific customizations in subsites. This operation lists an ID for each site collection and subsite in your environment and the templates that the site relies on. This operation was first introduced in Office SharePoint Server 2007 with Service Pack 2 (SP2). For more information, see Enumallwebs: Stsadm operation (Office SharePoint Server).

  • Use a tool such as WinDiff (a tool that is provided with most Microsoft operating systems) to compare your production environment servers with your test farm servers. You can use this tool to see which files exist on your servers and the differences between them.

  • Check the web.config files for any changes, and look in the SafeControls element to find any custom controls.

  • Use the SharePoint Diagnostics Tool (SPDiag) to find deployed solutions. For more information, see SharePoint Diagnostics Tool (SPDiag).

  • Create a list of all customizations that you find. Identify the source of the customizations, if possible. For example, are there third-party add-ins or templates that were customized in-house? After you identify the source, you can then check for updated or upgraded versions of the customizations. A worksheet is available that you can use to fill in information about your environment, based on the data you find in the results from the pre-upgrade checker and in your research on your customizations. Download the worksheet from and customize it to suit your needs.


Whom do you contact about customizations that you did not create?

  • Contact Microsoft if you are having trouble with a template that you downloaded from the Microsoft Web site (such as the Windows SharePoint Services 3.0 Application Templates).

  • Contact your third-party solution vendor if you are having trouble with a template or component that they supplied you for the previous version. They may have an upgraded version available.

After you identify all the customizations, copy them to the appropriate servers in your test farm. You can use the Windows PowerShell cmdlet test-spcontentdatabase before you attach a database to SharePoint Server 2010 to determine whether any customizations are missing from the environment. Run this command for each database after you restore the databases to your database server, but before you run the upgrade. Note that this cmdlet runs silently — it will not return any output unless there is an error.

Copy real data to the test environment and try the upgrade

You cannot achieve your testing goals unless you use your actual data. You can use the following methods to create a copy of your data:

There is no better way to tell what may come up during upgrade than to perform the test on a copy of all of your data; however, this might not always be a realistic option for initial testing. You can phase the testing by testing one database at a time (if the databases are large) so that you can make sure you test whatever is unique about that data set, or you can assemble a subset of data from representative sites in your environment. If you want to first test by using a subset of your data, be sure that the subset has the following characteristics:

  • The data subset contains sites that are typical of the sites you support in your environment.

  • The size and complexity of the data subset is very similar to the actual size and complexity of your environment.


Testing a subset of your data does not produce a valid benchmark for how long it will take to process the entire volume of data for your environment.

After copying the data, take a first pass through the upgrade process to see what happens. This is just the preliminary round.

Try in-place upgrade

If you want to try an in-place upgrade approach, use the following steps to try out the upgrade process:

  1. Create a backup of your farm.

  2. Restore the backup to your test farm.

    For more information, see Back up and restore an entire farm (Office SharePoint Server 2007).

  3. Run the pre-upgrade checker. Make note of any issues it finds. You will want to address these issues in your original environment before you run the actual upgrade on your product farm. For more information, see Run the pre-upgrade checker (SharePoint Server 2010).

  4. Follow the steps in Perform an in-place upgrade (SharePoint Server 2010) to try the in-place upgrade.

  5. Review the results.

Try a database attach upgrade

  1. Create a SQL Server backup of your content databases and Shared Services Provider (SSP) databases.

  2. Use SQL Server to restore the backups into your single-server test farm and attach the content databases to that environment.

    For more information, see Back up and restore databases (Office SharePoint Server).

  3. Run the pre-upgrade checker. Make note of any issues it finds and any changes it makes. You will want to address these issues and make these changes in your original environment before you run the actual upgrade on your product farm. For more information, see Run the pre-upgrade checker (SharePoint Server 2010).

  4. Follow the steps in Prepare the new SharePoint Server 2010 environment for a database attach upgrade to configure the test environment for a database attach upgrade.

  5. Follow the steps in Attach databases and upgrade to SharePoint Server 2010 to try the database attach upgrade process.

Review your results

After your test upgrade has been completed, you can review the results and revisit your plans. Look at the log files, look at the upgraded sites, and check out your customizations. How did upgrade work for your environment? What did you find out? What do you need to rethink about your upgrade plan?

Review the log files

Review the following log files:

  • The pre-upgrade checker log file.

    The log files for the pre-upgrade checker (stsadm -o preupgradecheck) are located at %COMMONPROGRAMFILES%\Microsoft Shared\Web server extensions\12\LOGS. The log files are named in the following format: PreUpgradeCheck_YYYYMMDD-HHMMSS-SSS-random-number.log, where YYYYMMDD is the date and HHMMSS-SSS is the time (hours in 24-hour clock format, minutes, seconds, and milliseconds) and the random number is used to differentiate between possible simultaneous attempts to run the pre-upgrade checker.

  • The SharePoint Products Configuration Wizard (Psconfig.exe) log file (generated when you run this wizard as part of your trial in-place upgrade).

    The PSCDiagnostics log files are located at %COMMONPROGRAMFILES%\Microsoft Shared\Web server extensions\14\LOGS.

  • The upgrade log file and the upgrade error log file (generated when you run the upgrade).

    The upgrade log file (.log) and the upgrade error log file (.err) are located at %COMMONPROGRAMFILES%\Microsoft Shared\Web server extensions\14\LOGS. The log files are named in the following format: Upgrade-YYYYMMDD-HHMMSS-SSS.log, where YYYYMMDD is the date and HHMMSS-SSS is the time (hours in 24-hour clock format, minutes, seconds, and milliseconds).

To review the log files to find and troubleshoot issues. start at the top of the files. Errors or warnings may be repeated if they occur for several site collections in the environment, or if they block the upgrade process altogether. For example, if you cannot connect to the configuration database, the upgrade process will try (and fail) several times and these attempts will be listed in the log file.

Search, or visually scan, for the following entries:

  • Finished upgrading SPFarm Name=<Name of Configuration Database>

  • In-place upgrade session finishes. Root object = SPFarm=<Name of Configuration Database>, recursive = True. 0 errors and 0 warnings encountered.

If you find these entries, the installation was successful.

If you do not find the entries from the previous step, you can identify specific issues that may have contributed to the failure by searching, or visually scanning, through the Upgrade.log file for the following terms:

  • Search for ERROR in the log files to find any failures (such as failing components or faulty database connections).

  • Search for WARNING to find issues such as missing features or components.

To find upgrade issues, you may find it useful to use a log parser to run queries against the log files.

Restart upgrade, if necessary

During a database attach upgrade, any sites that cannot be upgraded will be skipped. During an in-place upgrade, if the server restarts or the upgrade fails, you will need to restart the upgrade process to upgrade the remaining sites.

To see whether any sites were missed or skipped during upgrade, run the following Stsadm operation stsadm -o localupgradestatus on every front-end Web server in your SharePoint Server 2010 server farm. For more information about this operation, see Localupgradestatus: Stsadm operation (Office SharePoint Server).

If the upgrade skipped any site collections, you can restart the upgrade process for the database that contains that site collection by using the following Windows PowerShell cmdlet: upgrade-spcontentdatabase -id <GUID>. For more information about this cmdlet, see Upgrade-SPContentDatabase.

For more information, see Resume upgrade (SharePoint Server 2010).

Review upgraded sites

Review your upgraded sites to identify any issues that need to be addressed before you run the upgrade process on your production environment. For more information about specific things to look for, see Verify upgrade and review upgraded sites (SharePoint Server 2010).

Adjust your plans and test again

Repeat the testing process until you are sure that you have found all the issues that you may face and that you know how to deal with them. Your goal is to know what your plan is if it is 4:00 P.M. on Sunday, you have to be back online Monday morning, and it is not going well. Is there a point of no return? Test your rollback plan and make sure that it works before you begin your real upgrade.

See Also

Other Resources

Downloadable book: Upgrading to SharePoint Server 2010
Resource Center: Upgrade and Migration for SharePoint Server 2010