Migrating a Web Server from IIS 6.0 to IIS 7.0 by Using the Microsoft Web Deployment Tool

The Microsoft Web Deployment Tool (MS Deploy) is a utility that you can use to migrate your Web server or Web site from a computer that is running Information Services (IIS) version 6.0 on Microsoft Windows Server 2003 to a computer that is running IIS 7.0 on Windows Server 2008. You can also use MS Deploy to migrate from an IIS 6.0 Web server to another IIS 6.0 Web server, or from an IIS 7.0 Web server to another IIS 7.0 Web server.

This article describes how to install MS Deploy, migrate a Web server from IIS 6.0 to IIS 7.0, and how to perform post-migration configuration steps. It also discusses migrating application pools from classic to integrated mode.

The configuration storage architecture in IIS 7.0 has changed significantly from those in earlier versions of IIS. IIS 7.0 replaces the legacy metabase with the new text-based applicationHost.config file, which stores global configuration settings in XML format. As a result of this change, you cannot use utilities such as iiscnfg.vbs to migrate the configuration of a Web server to IIS 7.0.

You should plan to use MS Deploy to migrate your IIS 6.0 Web server to IIS 7.0 unless you either have:

• An up-to-date build script for your Web environment that explicitly sets all necessary IIS configuration values for the legacy metabase.
• A Web environment that requires minimal configuration.

This article addresses the specific scenario in which you migrate a Web Server that is running IIS 6.0 on Windows Server 2003 to a Web server that is running IIS 7.0 on Windows Server 2008 on a different physical or virtual computer.

Installing MS Deploy

You can download and install MS Deploy from the locations listed in Table 1.

Table 1. MS Deploy Download Locations

Software Requirements

Before you install MS Deploy, you must install .NET Framework version 2.0 SP1 or 3.5 (which includes 2.0 SP1) on your computer.

You must install the appropriate version of MS Deploy on both the source IIS 6.0 Web server and the destination IIS 7.0 Web server.

To install MS Deploy on the source IIS 6.0 Web server

1. Visit the x86 or x64 link in Table 1 and click Download.
2. In the File Download dialog box, click Run.
3. In the Internet Explorer - Security Warning dialog box, click Run.
4. On the Welcome to the Microsoft Web Deployment Tool Setup Wizard page, click Next.
5. On the End-User License Agreement page, click I accept the terms in the license agreement, and then click Next.
6. On the Choose Setup Type page, click Custom.
7. On the Custom Setup page, click the Installs the remote agent service down arrow, select Will be installed on local hard drive, and then click Next.
8. Click Install.
9. Click Finish.
10. In Computer Management, under Services, verify that the Microsoft Web Deployment Agent Service is started.

To install MS Deploy on the destination IIS 7.0 Web server

1. Perform steps 1 through 5 in the previous procedure.
2. On the Choose Setup Type page, click Typical.
3. Click Install.
4. Click Finish.

Using MS Deploy to Migrate from IIS 6.0 to IIS 7.0

This section describes the recommended steps you should perform to migrate from IIS 6.0 to IIS 7.0 by using MS Deploy. To perform the migration:

1. Create a backup of the configuration of the destination IIS 7.0 Web server.
2. Verify dependencies on the source IIS 6.0 Web server.
3. Install required software components on the IIS 7.0 Web Server.
4. Verify the migration behavior before you perform the migration.
5. Run the MS Deploy migrate command.

Creating a Backup of the IIS 7.0 Web Server Configuration

You should always create a backup of your destination IIS 7.0 Web server configuration before you use MS Deploy to migrate to IIS 7.0. The Microsoft Operations Engineering (MSCOM Ops) team recommends that you create the backup by using the appcmd.exe command line tool, which is included with IIS 7.0. The appcmd.exe tool is located in the %windir%\system32\inetsrv folder, which is not in the system Path environment variable by default.

The following examples illustrate how create, list, and restore a backup of your IIS 7.0 configuration files. It is assumed that you have either navigated to the %windir%\system32\inetsrv folder by using the command prompt, or have added a reference to the folder to the Path environment variable prior to executing the commands in the following example.

To create a backup by using appcmd.exe

At the command prompt, type

appcmd add backup "PreMigration"

and press ENTER.

To list all existing backups by using appcmd.exe

At the command prompt, type

appcmd list backup

and press ENTER.

To restore a backup by using appcmd.exe

At the command prompt, type

appcmd restore backup "PreMigration"

and press ENTER.

Using MS Deploy

MS Deploy is installed in the C:\Program Files\Microsoft Web Deploy folder, and the executable file is named msdeploy.exe. Setup does not add this folder to the system Path environment variable. It is assumed that you have used the command prompt to navigate to this folder or that you have added a reference to this folder to the Path environment variable prior to executing the commands in the following examples.

The following command lists complete MS Deploy syntax and usage examples.

To list MS Deploy syntax and usage examples by using MS Deploy

At the command prompt, type

msdeploy /?

and press ENTER.

Verifying Dependencies on the Source IIS 6.0 Web Server

After making a configuration backup of your destination IIS 7.0 Web server, you should verify dependencies on the source IIS 6.0 Web server. The results of the verification process can help you verify the settings required to correctly perform the migration.

In Technical Preview 1, the MS Deploy dependency verification automatically performs the checks on all data in the Web root folder on the source Web Server. If you have a large amount of data or a large number of files, this process may take a long time to complete. In the final release, this check will be optional.

To verify dependencies by using MS Deploy

At the command prompt, type

msdeploy –verb:getDependencies –source:metakey=lm/w3svc

and press ENTER.

Following is an example of a dependency report on an IIS 6.0 Web server:

C:\Program Files\Microsoft Web Deploy>msdeploy -verb:getDependencies -source:metakey=lm/w3svc
<dependencyInfo>
  <dependencies>
    <dependency name="Metabase" />
    <dependency name="AnonymousAuthentication" />
    <dependency name="WindowsAuthentication" />
    <dependency name="HttpRedirect" />
    <dependency name="ISAPIFilter" />
    <dependency name="ASP" />
    <dependency name="ServerSideIncludeDisabled" />
    <dependency name="AspNet2.0" />
    <dependency name="HttpCompressionStatic" />
  </dependencies>
  <apppoolsInUse>
    <apppoolInUse name="DefaultAppPool" definitionIncluded="True" />
    <apppoolInUse name="AppPool01" definitionIncluded="True" />
    <apppoolInUse name="AppPool02" definitionIncluded="True" />
    <apppoolInUse name="AppPool03" definitionIncluded="True" />
    <apppoolInUse name="AppPool04" definitionIncluded="True" />
  </apppoolsInUse>
  <cgis />
  <isapis>
    <isapi dll="C:\WINDOWS\system32\inetsrv\httpodbc.dll" enabled="False" />
  </isapis>
  <drives totalSpace="165252825">
    <drive name="D:" size="165252825" isUnc="False" sizeWindir="0" sizeInetpub="0" />
  </drives>
</dependencyInfo>

The results returned by the getDependencies command should not be considered to be an absolutely definitive list because MS Deploy may not find every component dependency. It does a fairly complete job of identifying installed IIS components but it does not, for example, identify that SMTP is a required component in Technical Preview 1. It is also possible that getDependencies will report some components that are installed as dependencies, but not actually in use. In most cases, dependencies that are incorrectly reported are issues in Technical Preview 1 and should be posted in the MS Deploy forums on iis.net. For example, on the Web Server on which the verification in the previous example was performed, ASP was not being used.

To work around this situation, you should verify which components are actually in use, and only install the IIS role services on the IIS 7.0 Web Server that you need.

getDependencies may identify some components (such as WebDAV and FrontPage Server Extensions) that are not supported by IIS 7.0. These components may not be supported or may require additional steps in order to work. In the final release of the tool, these components will have added information in the Help files to help you proceed. getDependencies is used to determine current dependencies of your site or server. It does not provide any information on other optional components that you could install on IIS 7.0 (such as Failed Request Tracing or Dynamic Content Compression).

The <drives totalSpace> section is particularly important because it indicates the minimum amount of drive space, in bytes, required on the destination IIS 7.0 Web server.

Installing Required Software Components on the Destination IIS 7.0 Web Server

Based on the results of the preceding dependency audit, the MSCOM Ops team would use the output to assist with preparing the destination IIS 7.0 Web server for the migration (after verifying whether the listed component dependencies are all actually in use on the source IIS 6.0 Web server) as follows:

• Install the Web Server (IIS) role.
• Install the following role services:
• Windows Authentication
• HTTP redirection
• ISAPI filters (Note: ISAPI filters are only supported in IIS 7.0 classic mode.)
• ASP
• ASP.NET
• Static Content Compression (already installed by default when adding Web Server role)
• Do not install Server Side Includes.
• Ensure that the destination data drive has adequate capacity to accommodate the value in the <drives totalSpace> section.

In Technical Preview 1, due to known issues, there may be some dependencies that are not correctly gathered. For example, this particular dependency audit failed to report two ISAPIs that are enabled in the Web Service Restriction List, so be sure to verify its output. If any dependencies are not correctly reported, please post these to the MS Deploy forums on iis.net to ensure that they are known issues. In the final release, MS Deploy should gather script maps and installed IIS components accurately.

Verifying the Migration Behavior

After you install all necessary roles and role services on the IIS 7.0 destination Web server, you can migrate from the IIS 6.0 Web server to the IIS 7.0 Web server. Before you perform the actual migration, you should verify the migration behavior by using the migrate command with the –whatif switch, and storing the results in a log file.

The following example demonstrates how to verify the migration behavior prior to performing the migration.

To verify migration behavior by using MS Deploy

At the command prompt on the destination IIS 7.0 Web server, type

msdeploy –verb:migrate –source:webserver60,targetName=http://servername/msdeploy –dest:webserver60 –whatif > msdeploy_test.log

where servername is the name of the source IIS 6.0 server, and press ENTER.

Running the MS Deploy Migrate Command

After verifying the changes in the output log files, you can then perform the actual migration by using the same command and omitting the -whatif switch:

To migrate to a destination server by using MS Deploy

At the command prompt on the destination IIS 7.0 Web server, type

msdeploy –verb:migrate –source:webserver60,targetName=http://servername/msdeploy –dest:webserver60 > msdeploy_actual.log

where servername is the name of the source IIS 6.0 server, and press ENTER.

Including Custom Objects in a Migration

After you execute the migrate command, migration of your site is complete. All IIS configuration, .NET configuration (machine.config and root web.config files), Web content and associated NTFS ACLs, and certificates are migrated to the server that is running IIS 7.0 on Windows Server 2008. However, if you have a custom .NET assembly in the Global Assembly Cache (GAC), these additional objects can be moved by using a manifest file.

For example, you may wish to include additional objects in a migration, such as:

• Custom .NET assemblies in the Global Assembly Cache (GAC)
• A custom directory path that is not included in your Web site paths
• Registry keys
• Custom COM components

For more information about how to use a manifest file to help migrate a site, see the “05_Syncing a Custom Manifest” topic in MS Deploy Walkthroughs.

Performing Post-Migration Configuration Steps

After you run the migrate command, migration of your site is complete. All IIS configuration, .NET configuration (machine.config and root web.config files), Web content and associated NTFS ACLs, and certificates are migrated to the server that is running IIS 7.0 on Windows Server 2008. The IIS configuration is now contained in applicationHost.config, which is located in the %windows%/system32/inetsrv/config folder.

However, you may still need to configure other Web server-related components, including:

• Platform components such as specific versions of the .NET Framework, ASP.NET Ajax, AJAX Control Toolkit, and so on.
• Custom Windows services
• Custom Scheduled tasks

To complete the configuration of your migrated Web server, you can install these components either manually or by using a Web server build script. However, additional components that you need to configure or migrate may be addressed by other providers. For example, environment variables are stored in a registry key and therefore could be included in a custom manifest file. You should ensure that the components support this type of migration. If you try to move a component by only moving the registry or file location where it is stored, verify that this actually includes everything you need, and that the component can be moved safely in this way.

After you have completed any post-migration steps, you can then begin to verify the behavior of your site by browsing to it and examining how it responds.

Migrating Application Pools from Classic to Integrated Mode

As part of the migration process, MS Deploy configures all IIS 7.0 application pools in classic request-processing mode (for backward compatibility with IIS 6.0.) instead of IIS 7.0 integrated mode. MS Deploy uses classic mode because some ASP.NET applications developed for use by IIS 6.0 may require modification before they can run correctly in integrated mode.

Migrating application pools to classic mode helps ensure that your sites will function as expected after migration. MS Deploy is designed to help you migrate from IIS 6.0 on Windows Server 2003 to IIS 7.0 on Windows Server 2008, and it is beyond the scope of MS Deploy to eliminate all compatibility issues between classic and integrated modes in IIS 7.0.

For more information about how to migrate existing ASP.NET applications to IIS 7.0 integrated mode, see "ASP.NET Integration with IIS7".

Summary

This article described how to install MS Deploy and how to use MS Deploy to migrate a Web Server that is running IIS 6.0 on Windows Server 2003 to a Web Server that is running IIS 7.0 on Windows Server 2008. It then described how to perform post-migration configuration steps, and discussed migrating application pools from classic to integrated mode.

More Information

Microsoft Web Deployment Team Blog

MS Deploy Walkthroughs