ASP.NET Web Application Project Deployment Overview

After you have created an ASP.NET Web application project or an ASP.NET Web site project in Visual Studio, you typically deploy the project to a Web server where others can access your application. Deployment typically involves more than just copying the application's files from one server to another. You might also have to perform additional tasks, such as the following:

• Changing Web.config file settings that must be different in the destination environment, such as settings for debugging, or database connection strings.

• Propagating data or data structures in databases that are used by the Web application.

• Configuring IIS settings on the destination computer, such as the application pool, the authentication method, whether directory browsing is allowed, and error handling.

• Installing security certificates.

• Setting values in the registry of the destination computer.

• Installing application assemblies in the global assembly cache (GAC) on the destination computer.

An extension to Microsoft Internet Information Services (IIS) that is named Web Deploy can automate most deployment tasks. Visual Studio provides tools that work with Web Deploy to make it easier for you to deploy a Web application project.

This topic is for Web applications that are created by using a Web application project template. You can also create Web applications by using a Web site project template. For information about how to deploy Web site projects, see ASP.NET Web Site Project Deployment Overview.

This topic contains the following sections:

• Web Deployment Packages

• One-Click Publish

• Enterprise Scenarios

• Third-Party Hosting Scenarios

• Web.config File Transformation

• Deploying a SQL Server Database

• Extending the Web Publishing Pipeline

For more information about the topics that are discussed in this overview, see ASP.NET Deployment Content Map.

Web Deployment Packages

You can deploy a Web application project by using Visual Studio to create a Web deployment package and by installing the package on the destination server. A deployment package is a compressed (.zip) file that contains information that is required in order to set up the application in IIS, copy application files to it, and set up related resources such as databases.

You can create the deployment package and then install it separately. Alternatively, you can use one-click publish, which lets you deploy remotely in one step. (By default, one-click publish does not create a package, but you can specify that it should create a package if you want one.)

In addition to the application's source files and binary files, a deployment package typically includes files that contain the following kinds of information:

• IIS settings, such as the application pool, the authentication method, whether directory browsing is allowed, and error handling.

• Database scripts that are used to propagate changes to database data or to database structures.

• Parameters that contain values that might need to be changed when the package is installed, such as settings for debugging, or connection strings.

The Visual Studio package-creation process is extensible. Some examples of information that you might want to include in a package but that require custom extensions include the following:

• Security certificates.

• Windows registry settings.

• Assemblies (.dll files) that must be installed in the GAC on the destination computer.

Specifying What to Include in a Deployment Package

Visual Studio uses settings that you create in the Package/Publish Web tab of the project Properties page in order to determine what it puts into a deployment package. The following illustration shows the Package/Publish Web tab.

Database-related settings that affect package creation are entered on the Package/Publish SQL tab, which is described later in this topic.

These two tabs let you update the most commonly used settings. Other settings that are used less frequently are stored in the Visual Studio project file (.csproj or .vbproj) and can be changed by directly editing that file.

Creating a Deployment Package

You can create a package in the following ways:

• Use tools in Visual Studio.

• Use the MSBuild command directly from the command line.

• Use the MSBuild command indirectly from PowerShell or Team Build.

Installing a Deployment Package

After you create a deployment package, you install it on the destination computer. Web Deploy uses the information in the package to configure IIS, to set up databases, to create folder structures and copy files to them, and to do anything else that is required in order to deploy the application.

You can install a package in the following ways:

• Use Web Deploy from the command line.

• Use a .cmd file that Visual Studio creates that contains the Web Deploy commands that install the package. Web Deploy commands can be long and complex, and this file is provided to make it easier to install a package from the command line.

• Use IIS Manager.

• Use PowerShell to execute Web Deploy commands.

You can include parameters in a package when you create it. These are name-value pairs that you supply a default value for when the package is created, but that for which a new value can be supplied when the package is installed. If you use IIS Manager to install the package, the parameter names are displayed using text boxes so that you can enter new values. If you install by using Web Deploy from the command line, you can specify parameter values in an XML file.

Location and Contents of the Package Folder

By default, Visual Studio generates deployment packages in the folder that is identified by the MSBuild IntermediateOutputPath property. The IntermediateOutputPath property refers to the project's obj\Configuration folder, as shown in the following illustration of the Solution Explorer window:

The predefined names for Configuration are Debug (as shown in the preceding illustration) and Release. You can define additional build configurations.

The package is created in a folder that is named Package. The Package folder contains the following files:

• projectname.zip. This is the actual deployment package.

• projectname.deploy.cmd. This is a command-line batch file that invokes Web Deploy in order to make it easier for you to install the package from the command line.

• projectname.SetParameters.xml. This file contains parameters that are passed to Web Deploy when you use the deploy.cmd file to install the package. For each parameter, a default value is specified that is determined by the Visual Studio package settings. For example, you can change these values if you want to install the Web application to multiple servers but use different settings for each server. 

• projectname.SourceManifest.xml. This file contains settings that Visual Studio passed to Web Deploy, and which Web Deploy used to create the Web package. This file is required by Web Deploy only in order to create the package. It is not used when the package is installed.

If you choose not to create the package as a .zip file, the files that would have been stored in the .zip file are located in a folder that is named Archive. In that case, the first node of the deploy.cmd, SetParameter.xml, and SourceManifest.xml file names is "Archive" instead of projectname.

The interrelationships between Visual Studio, Web Deploy, and these files are shown in the following illustration:

One-Click Publish

You can also deploy remotely by using the Visual Studio one-click publish feature. In that case, you specify in a publish profile how and where Visual Studio should deploy the application. The following illustration shows the Publish Profile dialog box.

If you use one-click publish to deploy your application to a third-party hosting company, the hosting company will typically provide you with the settings that you require for the Publish Profile dialog box.

When you have finished specifying publish settings, you can click the Publish button in this dialog box or in the Web One Click Publish toolbar. Visual Studio then deploys the application on the destination computer. When you click the Publish button after a Web application project has already been deployed, Visual Studio redeploys only the changed items.

You can create multiple profiles so that you can publish to different servers or to the same server with different settings. There is a limit of 50 profiles.

Enterprise Scenarios

In an enterprise environment, you typically deploy from a development computer to one or more intermediate environments, such as a test server or a staging server. From one of the intermediate environments, you then deploy to the production environment.

For the initial deployment from the development environment, typical scenarios include the following:

• Create a deployment package by using Visual Studio and install it manually.

• Create and install the deployment package by using a command-line process. This is typically done in batch mode from a source-control repository by using MSBuild.

• Use one-click publish. This option is available if the development computer has remote access to the destination environment, if the destination computer is set up for the method of publishing that you select, and if you have appropriate permissions on the destination computer. By default, one-click publish does not create a package. However, you can specify that a package should be created for use as an archive or backup.

To deploy from one environment to the next after the initial deployment, you can use the same package that was created for the initial deployment. Alternatively, you can use Web Deploy to create a new package on the computer that you are deploying from.

The following illustration shows some typical enterprise scenarios.

Third-Party Hosting Scenarios

If you use a third-party hosting company and you deploy directly from your development computer to the hosting company, you have the following options:

• Use Visual Studio one-click publish.

• Create a package and use IIS Manager to install it remotely.

At the hosting company, your application might be in a shared environment or on dedicated servers. For applications that are hosted in shared environments, there are typically significant limitations on your ability to configure the environment. For example, you are typically not allowed to change IIS settings in a shared hosting environment.

The following illustration shows some typical third-party hosting scenarios.

Web.config File Transformation

Web.config files typically include settings that have to be different depending on which environment the application is running in. For example, you might have to make changes such as the following when you deploy a Web.config file to a destination server:

• Change a database connection string to point to the production database.

• Disable debugging in the production environment.

• Remove sensitive information such as connection strings, such as if you provide a package to a community site.

To manually manage changes to a Web.config file, you can do the following:

• Edit the Web.config file on the destination server each time the project is deployed.

• Maintain separate versions of the Web.config file for each environment (perhaps in separate folders or using distinctive names), and copy only the version that is appropriate to the destination environment when you deploy.

• Create XSLT files to transform the Web.config and apply the transforms when the application is deployed.

For Web application projects, ASP.NET provides tools that automate the process of changing (transforming) Web.config files when they are deployed. You can use Web Deploy parameterization or Visual Studio Web.config transformations to do this. Web Deploy parameters are more complex to set up than Visual Studio Web.config transformations but are very flexible and can automate many deployment tasks, not just Web.config file changes. For example, you can use Web Deploy parameters to update database scripts and IIS settings. When you deploy by using a deployment package, you can specify Web Deploy parameter values when the package is installed, not just when it is created. This is especially useful in enterprise environments, where it's common for different people to be responsible for creating and installing deployment packages. For example, the developer who creates a package might not know certain passwords that need to be in the Web.config file. The IT administrator who installs the package can enter those values when the package is installed. For more information, see Parameterization vs. Web.config Transformation on Vishal Joshi's blog and How to: Use Parameters to Configure Deployment Settings When a Package is Installed.

Visual Studio Web.config transformations are simpler to set up. All you have to do is create a transform file that uses a special syntax to specify the changes that you want to be applied to the Web.config file during deployment. You can specify separate transformations for each build configuration. Transform file names include the name of the build configuration as an additional node between "Web" and "config". For example, the transform file for the Debug build configuration is Web.Debug.Config. The Visual Studio Solution Explorer window automatically groups these files underneath the Web.config file, as shown in the following illustration:

A transform file is an XML file that specifies how the Web.config file should be changed. Transform files use XML attributes that have been designed specifically for transforming Web.config files for deployment. For example, suppose your Web.config file has the following connection string section:

<connectionStrings>
  <add name="ApplicationServices"
      connectionString="[TestDatabase]" />
</connectionStrings>

The following transform file specifies that the connection string that is named ApplicationServices should be automatically converted to point to a production database when the Web application is deployed.

<?xml version="1.0"?>
<configuration xmlns:xdt="https://schemas.microsoft.com/XML-Document-Transform">
  <connectionStrings>
    <add name="ApplicationServices" 
        connectionString="[ProductionDatabase]" 
        xdt:Transform="Replace" xdt:Locator="Match(name)"/>
  </connectionStrings>
</configuration>

In the example, the Locator attribute value Match(name) specifies that only the add element that has the same name (ApplicationServices) should be changed. The Transform attribute value Replace specifies that the deployment process should replace the entire add element.

Deploying a SQL Server Database

When you deploy a Web application that uses a SQL Server database, you might also have to propagate data structures, data, or both. Visual Studio can automatically create scripts (.sql files) to do this in the destination database, and these scripts can be included in the Web package. You can also include custom SQL Server scripts and specify the order in which the scripts should run. Web Deploy runs the scripts on the destination server when the package is installed.

You specify SQL Server deployment options on the Package/Publish SQL tab of the project Properties page. The following illustration shows the Package/Publish SQL tab.

Extending the Web Publishing Pipeline

The Web Publishing Pipeline (WPP) is the process that Visual Studio uses when you create a deployment package or use one-click publish. The work that is performed in the WPP is actually done by MSBuild and Web Deploy. This is why the same functionality is available either in Visual Studio or when you use command-line tools to deploy.

Some aspects of the WPP can be extended by modifying the XML files that control MSBuild behavior. For example, tasks that that you can handle by modifying XML files include the following:

• Excluding specific Web application files or folders from the package.

• Precompiling the Web application before the package is created.

• Installing application assemblies in the GAC on the destination server.

• Updating registry keys on the destination server.

• Installing SSL certificates on the destination server.

Other tasks require that you extend both MSBuild and Web Deploy. For example, suppose that your Web application uses MSMQ and you want to automate MSMQ deployment. You can do this by creating an MSMQ provider for Web Deploy and adding it to the WPP by modifying the files that control MSBuild.

Web Deploy uses the .NET Framework provider model. Each kind of information that needs to be managed for deployment is handled by a provider. For example, there is a provider for IIS settings, a provider for SQL Server databases, a provider for Web content such as .html files and .aspx files, and so on.

When Web Deploy creates a package, it calls each provider to gather information that pertains to the Web application that is to be deployed. Web Deploy invokes the provider to serialize the information and to store it in files. When Web Deploy installs the package, the provider reads the files that it created for the package and deserializes the information as required to re-create the original settings in the destination environment. Providers must be able to handle installation-time parameters. That is, they must be able to work with values that are supplied at installation time in the IIS Manager UI or in a Parameters.xml file.

The following illustrations show the flow of data between a Web application's information, Web Deploy providers, the Web Deploy API, a deployment package, and a parameters file. In the illustration, the Parameters.xml is shown next to the package .zip file in order to illustrate its role. However, Parameters.xml is actually included in the package .zip file.

Development Computer

Web Server

Web Deploy supplies providers for most of the kinds of resources that might be associated with a Web application. However, you can write a custom provider if none of the built-in providers is appropriate for your requirements. For a list of available providers, see Web Deploy Providers on the Microsoft TechNet Web site.

The following illustration shows a typical sequence of steps in the WPP when you use Web Deploy to package or publish. This shows a WPP that has been extended by adding the following steps:

• Excluding specified files.

• Precompiling the Web application.

• Deploying GAC assemblies, COM assemblies, and registry keys.

• Deploying SSL certificates.

If you choose to deploy by using one-click publish and by using a method other than Web Deploy, you can extend only the parts of the WPP that do not apply to Web Deploy, as shown in the following illustration:

For examples that describe how to extend the Web Publishing Pipeline for specific scenarios, see the following entries on the Visual Web Developer Team blog:

• How to extend the destination file to include registry settings for web deployment packages

• How to package and deploy COM components

• How to package .NET assemblies

See Also

Concepts

ASP.NET Deployment Content Map