How to: Deploy a Web Application Project Using a Web Deployment Package

  • Article

This topic explains how to deploy a Web application project by performing the following tasks:

  • Creating a deployment package on the source computer by using Visual Studio.

  • Installing a deployment package on the destination server by using IIS Manager or by using the .cmd file that Visual Studio generates when it creates the package.

Note

Web deployment tools have been improved in Visual Studio 2012. You can install the improved tools in Visual Studio 2010 and Visual Web Developer 2010 Express by installing the Visual Studio Web Publish Update. For information about how to use the new tools, see the documentation for Visual Studio 2012. A good place to start is Web Application Project Deployment Overview for Visual Studio and ASP.NET.

Deploying a Web application by using a Web Deployment package might involve the following additional tasks that are not described in this procedure:

  • Specifying database deployment options. If the Web project that you want to deploy uses a database, and if scripts must run during deployment in order to set up database structures or data in the destination environment, you must enter settings in the Package/Publish SQL tab of the project Properties page. For more information, see How to: Deploy a Database With a Web Application Project.

  • Specifying Web.config file transformations. Web.config files typically include settings that have to be different depending on which environment the application is running in. For example, your development Web.config file might enable debugging but typically do not want debugging enabled on a production server. You can create transform files that automate the process of changing Web.config settings during deployment. For more information, see How to: Transform Web.config When Deploying a Web Application Project.

For more information about Web application project deployment, see ASP.NET Deployment Content Map.

Specifying Files and Settings to Deploy

You use the Package/Publish Web tab of the project Properties page to configure settings that determine what should be included when the Web application is deployed. The default settings on this tab work for many typical scenarios. You can skip this procedure if both of the following conditions are true:

  • You want to deploy only the files that are required in order to run the site. For example, this is typically true if source code files are compiled into assemblies, and you want to copy only the assemblies to the destination server.

  • You do not have to replicate IIS settings from the source computer to the destination server. For example, this is typically true if the project to deploy is a local IIS Web project and you have set up error-handling rules for its IIS application, but you do not have to replicate those rules on the destination server. If the project to deploy is a file system Web project, there are no IIS settings to replicate. (An IIS Web project is one for which you have selected Use Local IIS Web Server or Use Custom Web Server on the Web tab of the project Properties page.)

To specify files and settings to deploy

  1. In Solution Explorer, right-click the project name and then click Properties.

  2. Click the Package/Publish Web tab.

    The Package/Publish Web tab is displayed, as shown in the following illustration:

    Package/Publish dialog box

  3. In the Configuration drop-down list, select the build configuration that you want to configure deployment settings for.

    You can configure deployment for the Debug or Release build configurations, or fora custom build configuration that you have created by using the Configuration Manager dialog box. For example, you might want different settings for deploying to a test server and for deploying to a production server.

    The default value for the Configuration is Active, which means that the settings on this tab apply to the build configuration that is currently selected for the project. The currently selected build configuration is shown in the main toolbar and in the Configuration Manager dialog box. (To open Configuration Manager, select it from the Build menu.)

  4. Select one of the following options from the Items to deploy (applies to all deployment methods) drop-down list:

    • Only files needed to run this application. Files that are not required in order to run the site are not deployed to the destination server, such as code files that are compiled into assemblies.

    • All files in this project. All files included in the project are deployed to the destination server. Files that are in the project folder but are not included in the project are excluded.

    • All files in this project folder. All files in the project folder are deployed to the destination server, even if they are excluded from the project.

    For more information about how Visual Studio determines which files to deploy, see the question "Why don't all of the files in my project folder get deployed?" in ASP.NET Web Application Project Deployment FAQ.

  5. If you expect that you will never want to enable debugging on the destination server, select the Exclude generated debug symbols check box.

    Clearing this option causes .pdb files to be deployed to the destination server. These files are required for debugging. You typically do not want .pdb files on a production server, but you might want them on a test server.

  6. If you have files in the App_Data folder and you do not want them to be deployed to the destination server, select the Exclude files from the App_Data folder check box.

    For example, you might have a SQL Server Express .mdf file in the App_Data folder during development. However, you plan to deploy the database by using automatically generated scripts on the production server. In that case, you would select this option when you deploy to the production server because there is no use for the .mdf file on the production server.

  7. If you want to run database scripts that are specified in the Package/Publish SQL tab during deployment, select the Include all databases configured in Package/Publish SQL tab check box. (The Package/Publish SQL tab is described in a procedure later in this topic.)

    A typical scenario is to run scripts that configure databases only the first time a Web application is deployed. When you deploy updates to a Web application, you typically do not have to deploy updates to the database.

  8. If the Web project that you are deploying is an IIS Web project, and if you want to propagate the project's IIS settings to the destination environment, select the Include all IIS settings as configured in IIS Manager check box. (An IIS Web project is one for which you have selected Use Local IIS Web Server or Use Custom Web Server on the Web tab of the project Properties page.)

    IIS settings specify options such as authentication methods and how the Web application responds to errors. If you are deploying to a server on your company's network, you might want to configure the destination server the same as the development server when you deploy to a test server but not when you deploy to a production server. If you are deploying to a hosting company, the account that you use for deployment typically will not have the administrative permissions that are required in order to change IIS settings. In that case, do not select this option.

    If the current Web project is not an IIS Web project, this option and the option for application pool settings are disabled.

    Note

    Inherited IIS settings are not propagated to the destination server. For example, suppose that the IIS Web application that you want to deploy is under the default Web site on the source server, and the default Web site has Windows authentication set to true. If you deploy this site to the default Web site on a server that has Windows authentication set to false for the default Web site, Windows authentication will be false for the deployed Web site. This is true even if you select the Include all IIS settings as configured in IIS Manager check box. In that case, you will have to configure the settings manually on the destination server.

  9. If you selected the Include all IIS settings as configured in IIS Manager option, and if you want application pool settings from the Web project to be duplicated in the destination environment, select the Include application pool settings used by this Web project check box.

    Typical application pool settings include the following:

    • Whether to use Integrated or Classic mode.

    • The version of the .NET Framework to use (2.0 or 4).

    • The credentials that the site runs under.

    • Whether to enable 32 bit WOW mode on 64-bit servers.

    • The idle session time-out value.

Specifying Deployment Package Settings

You use the Web Deployment Package Settings section of the Package/Publish Web tab to specify settings that determine how the package is created and where to deploy it.

The default settings on this tab work for many typical scenarios. You can skip this procedure if all the following conditions are true:

  • You want to create the package as a compressed (.zip) file. A .zip file is the recommended way to store a package. It is smaller than files in a folder structure, and it is easier to copy from one location to another. In addition, only .zip files can be used to install a package in IIS 7 by using IIS Manager. There are few scenarios in which you would not want to use a .zip file. For example, you might want to leave files in a folder structure in order to facilitate automated comparison of daily builds. However, for most scenarios, a .zip file is appropriate.

  • You do not want to change the default application name (Default Web Site/projectname_deploy).

  • You did not select the Include all IIS settings as configured in IIS Manager option.

This procedure assumes that you still have the Package/Publish Web tab open after you completed the previous procedure.

To specify deployment package settings

  1. Make sure that the Create deployment package as a zip file check box is selected. (Unless you want the package in a folder structure instead of in a .zip file.)

  2. If you want the package to be created somewhere other than the default location, enter the location in the Location where package will be created box.

  3. If you want to use an IIS Web site or IIS application name that is different than the default name, enter the name in the IIS Web site/application name to use on the destination server box.

    If you enter an application name without an IIS Web site name, the package will be installed in the Default Web Site location (unless you override this value when you install the package).

    If the project that you are deploying is an IIS Web project, do not specify the same Web site and application name as the project's Web site. If you do, some of the project files might be overwritten during deployment.

    Note

    The default value ("Default Web Site") for the Web site will not work correctly if the operating system uses IIS 6 (Windows Server 2003) and is a language version other than English. In that case you must enter a value for the Web site. You can also change the value manually in the SetParameters.xml file. For information about the SetParameters.xml file, see ASP.NET Web Application Project Deployment Overview.

  4. If you selected the Include all IIS settings as configured in IIS Manager check box, perform the following steps:

    1. If you want the physical location of the Web application's folder to be different from the default value, enter the location in the Physical path of Web application on destination server box.

      If the Include all IIS settings as configured in IIS Manager check box is not selected, this box is disabled.

    2. In the Password used to encrypt secure IIS settings box, enter a password.

      Security noteSecurity Note

      The value that you enter is an encryption key and is not treated as a password by Visual Studio. It is shown in plain text when you enter it, and it is included in the deployment .cmd file in plain text.

      Note

      Do not include characters that have reserved meanings in command files, such as apostrophes (') or percent signs (%) in this string. Because this string is included in a .cmd file that can be used to install the package, deployment that uses the .cmd file will fail if the string contains reserved characters.

Creating the Package

After you have entered settings on the Package/Publish Web and Package/Publish SQL tabs, you can create the package.

Note

Before you create the package, you might also have to specify database and Web.config transform options. For more information, see How to: Deploy a Database With a Web Application Project and How to: Transform Web.config When Deploying a Web Application Project.

To create the package

  1. Make sure that the active build configuration is the one that you want to deploy.

    You can select the active build configuration in the Active solution configuration drop-down list in the Configuration Manager dialog box. To display the dialog box, select Build from the main menu and then select Configuration Manager.

  2. In the Project menu, click Build Deployment Package.

    The package and additional files that are provided to help with package installation are created in the location that you specified in the Package/Publish Web tab. A log is displayed in the Output window.

    If you specified that the package should be created as a .zip file, the output location contains the following files:

    • projectname.deploy.cmd. This is a helper command-line batch file that invokes Web Deploy in order to install the Web application on the destination server locally or remotely.

    • projectname.SetParameters.xml. This file contains parameters that are passed to Web Deploy on the destination server. By default, this file contains the values that are specified during the packaging process. If you want to install the Web application on multiple servers by using different settings, you can modify the parameter values in this file every time that you deploy the package by using the projectname.deploy.cmd command file.

    • projectname.SourceManifest.xml. This file contains settings that Visual Studio used to create the Web package. This file is required only in order to create the package. It is not used when the package is installed on the destination server.

    • projectname.zip. This file is the actual deployment package (if you specified that the package should be created as a .zip file). If you rename this file, make sure that you keep the .zip file-name extension.

    If you specified that the package should be created as files in a folder structure, the package is in a folder that is named Archive, and the name Archive is used for the other files in place of the project name.

Installing the Package

If IIS 7 is installed on the destination server, and if you specified that the package should be created as a .zip file, you can use IIS Manager to install the package. If the destination server has IIS 5.1 or IIS 6 installed, or if you prefer not to install the package by using IIS Manager, you can use the .cmd file that Visual Studio generates when it creates the package. For example, you might do this if you have to install the same package on multiple servers in a Web farm.

To install the package

See Also

Concepts

ASP.NET Deployment Content Map