How to: Install a Deployment Package Using the deploy.cmd File

Article
02/13/2013

When you create a Web deployment package in Visual Studio, Visual Studio creates a .cmd file that you can use to install the package. This .cmd file contains the actual Web Deploy commands that install the package. The .cmd file is provided in order to make command-line installation syntax easier for you, because the Web Deploy commands can be long and complex.

Before you start the .cmd file, you must make sure that the destination server is set up correctly. If the destination is a remote server, you must make sure that you have an appropriate connection to the remote server and that you have appropriate permissions on the remote server. When you start the .cmd file, you can pass options to it that the .cmd file in turn passes to Web Deploy.

This topic explains the syntax that you use to invoke the .cmd file. It provides an overview of prerequisites for invoking the .cmd file, and it provides links to other resources for more detailed setup information.

Choosing an Installation Method

This section provides an overview of the options for installing the package locally or remotely, followed by server configuration procedures for each option. The server configuration procedures for remote deployment are intended to provide an overview that helps you decide which method is best for your scenario. Each of these procedures links to a topic on the Microsoft IIS TechNet Web site where you can find detailed instructions.

If you are deploying to your development computer (which you might do for testing), you have to read only the procedure that describes how to configure a computer for in-process local deployment.

If you are deploying to a third-party hosting company or to destination servers that are administered by someone else, the hosting company or server administrators will specify the method that they want you to use. In that case, you can skip the overview of options. Instead, you can read only the part of the procedure that indicates development computer requirements for the method that you are using.

The following installation methods are available:

Install the package in-process on the local server (the one that you run the .cmd file on).

You must have administrative rights on the local server. This is the method that is typically used by developers to deploy to the development computer for local testing using IIS.
Install on a remote server by using Web Management Service (WMSvc) and the Web Deployment handler.

Third-party hosting companies typically set up their servers for this deployment method so that clients can deploy applications by themselves. However, the hosting company does not have to give administrative rights on the servers to the client. This method is also frequently used in enterprise environments when the IT department does not want to give administrative rights to developers on test servers or production servers.

This method requires IIS 7. A person who has administrative rights on the destination server uses IIS Manager to set up an account that you can use for deployment. You use the credentials for that account when you deploy. An advantage of this method is that when you deploy, you do not have to have administrative rights on the destination server. A disadvantage is that you typically cannot perform deployment tasks that require administrative rights, such as configuring IIS settings.
Install on a remote server by using the Web Deployment Agent Service (MsDepSvc). This is also referred to as Web Deploy Remote Service or just Remote Agent.

You must have administrative rights on the remote server. An advantage of this method is that there are no limitations on what you can do when you deploy, because you are an administrator on the destination server. You cannot use this method if the person who performs the deployment should not be an administrator on the destination server.
Install on a remote server by using the Web Deploy tempAgent provider setting.

As with Remote Agent, you must have administrative rights on the destination server. The advantage of this method over Remote Agent is that Web Deploy does not have to be installed on the computer that you run the command file on or on the destination computer. You can run Web Deploy from a shared folder on a server that has Web Deploy installed. Therefore, you can deploy to multiple servers without first installing Web Deploy on each server. You also do not have to update each server when new versions of Web Deploy are released or make sure that the source and destination computers have the same version of Web Deploy. The tempAgent provider setting requires some additional setup on destination servers compared to Remote Agent. However, if there are multiple servers to maintain, it typically results in less work to maintain over time.

For more information about how to choose the option that is appropriate for your scenario, see Using Web Deploy Remotely on the Microsoft TechNet Web site.

The rest of this section contains procedures that provide an overview of how to configure servers for each package installation method.

Configuring a Server for Local Deployment

The following procedure describes how to set up a server for in-process local package installation.

To set up a server for local in-process deployment

Make sure that the server has the following software installed:
- IIS 5.1 or later.
- The .NET Framework 2.0 SP1, or a later version if it is required by the Web application that you are installing.
- Web Deploy (the same version that was used to create the package).
For information about how to install IIS, the .NET Framework, and Web Deploy by using the Web Platform Installer, see Microsoft Web Platform Installer 2.0 on the Microsoft Web site.

Configuring Servers for Web Management Service

The following procedure provides an overview of how to set up source and destination computers so that you can install deployment packages by using Web Management Service (WMSvc) and the Web Deployment handler. For more information and for detailed instructions, see Configuring the Web Deployment Handler on the Microsoft TechNet Web site or Configure the Web Deployment Handler on the IIS.net Web site.

To set up servers to use Web Management Service for deployment

Make sure that the computer that you run the deploy.cmd file on has the following software installed:
- Web Deploy (the same version that was used to create the package).
Make sure that the destination server has the following software installed:
- IIS 7.
- The .NET Framework 2.0 SP1, or a later version if it is required by the Web application that you are installing.
- Web Deploy (the same version that was used to create the package).
For information about how to install IIS, the .NET Framework, and Web Deploy by using the Web Platform Installer, see Microsoft Web Platform Installer 2.0 on the Microsoft Web site.
On the destination server, configure the Web Management Service (WMSvc) by following these steps:
1. Add the Management Service role service.
2. Enable remote connections.
3. Create a user account to use for package installation.
4. Add delegation rules for the user account.
On the destination computer, make sure that the application pool for the IIS Web site that you are installing the package to is set to the .NET Framework version that is required by the package. (If the package specifies a Web application name but no Web site name, the package will install in the Default Web Site.)

Configuring Servers for Web Deploy Remote Service

The following procedure provides an overview of how to set up source and destination computers so that you can install packages remotely by using Web Deployment Agent Service (MSDepSvc). For more information, see Web Deploy Remote Service on the Microsoft TechNet Web site.

To set up servers to use Web Deployment Agent Service for deployment

Make sure that the server that you run the deploy.cmd file on has the following software installed:
- Web Deploy (the same version that was used to create the package).
Make sure that the destination server has the following software installed:
- IIS 5.1 or later.
- The .NET Framework 2.0 SP1, or a later version if it is required by the Web application that you are installing.
- Web Deploy (the same version that was used to create the package).
For information about how to use the Web Platform Installer to install IIS, the .NET Framework, and Web Deploy, see Microsoft Web Platform Installer 2.0 on the Microsoft Web site.
On the destination server, make sure that the MSDepSvc service is configured and started.
On the destination server, configure the firewall to allow HTTP traffic through port 80.
On the destination computer, make sure that the application pool for the IIS Web site that you are installing the package to is set to the .NET Framework version that is required by the package. (If the package specifies a Web application name but no Web site name, the package will install in the Default Web Site.)

Configuring Servers for tempAgent Provider Setting

The following procedure provides an overview of how to set up source and destination computers for remote installation by using the Web Deploy tempAgent provider setting. For more information, see Web Deploy On Demand on the Microsoft TechNet Web site.

To set up servers to use the Web Deploy tempAgent provider setting for deployment

Make sure that the source computer has the following software installed:
- Web Deployment Agent Service (MSDepSvc)
  
  Note
  
  By default, the Web Deployment Agent Service is not installed as part of Visual Studio. To install it, run Web Deployment Tool setup and select Remote Agent Service.
Make sure that the destination server has the following software installed:
- IIS 5.1 or later.
- The .NET Framework 2.0 SP1, or a later version if required by the Web application that you are installing.
For information about how to install IIS and the .NET Framework by using the Web Platform Installer, see Microsoft Web Platform Installer 2.0 on the Microsoft Web site.
On the destination server, configure the firewall to allow the following:
- HTTP traffic through port 80.
- WMI traffic.
On the destination server, make sure that the Windows Management Instrumentation (WMI) service is running.
On the destination server, make sure that there is a shared folder to which the temporary Web Deploy program files can be copied.
On the destination server, make sure that the Web Deployment Agent Service (MSDepSvc) is not installed. If the service is installed, it will interfere with the deployment process.
Make sure that the credentials that you use when you execute the deployment command file are from a user account that is a local administrator on the remote server.
On the destination computer, make sure that the application pool for the IIS Web site that you are installing the package to is set to the .NET Framework version that is required by the package. (If the package specifies a Web application name but no Web site name, the package will install in the Default Web Site.)

Executing the Command File

We recommend that you run Web Deploy in trial mode first to verify that the deployment works as expected. That way, if anything unexpected occurs, you can make changes before you perform the actual deployment. The following procedure describes how to execute the command file for some typical scenarios.

To deploy by using the command file

Make sure that the package (ProjectName.zip), the ProjectName.SetParameters.xml file, and the ProjectName.deploy.cmd file are all in the same folder.

If you are using the tempAgent provider setting, this folder can be on a remote computer. Otherwise, it must be on the computer where you intend to run the command file.
If you want to customize the values for any of the parameters that are included in the SetParameters.xml file, edit the file to change the values.

For example, you might use the same package to install to a staging server first and to a production server later. If so, the database connection string value might have to be different for each of these installations.
Execute the command file, specifying the t flag (trial mode) and optional flags that are appropriate for your scenario.

Following are some typical scenarios and the optional flags that are appropriate for them.

Note

To see a list of optional flags that are supported, enter the .cmd file name at a command prompt without any flags after it. If you open the .cmd file, you might see additional flags. Any flags that are not displayed in the help text and that are not described in this topic are not supported and should not be used.

Note

If characters that are not in the active code page are used for the destination server name, user name, or password, the .cmd file might fail.
- For the Web Management Service (WMSvc), include the m flag and specify the service URL as MSDeploy.axd, using the following syntax:
  
  ProjectName.deploy.cmd /t /m:https://DestinationServerName:8172/MSDeploy.axd
  
  To specify a user name and password, include the u and p flags. Add the a flag to specify basic authentication. The following example shows how to use these flags.
  
  ProjectName.deploy.cmd /t /m:DestinationServerName /u:User /p:Password /a:basic
  
  To allow untrusted certificates, add -AllowUntrusted=True, as shown in the following example:
  
  ProjectName.deploy.cmd /t /m:DestinationServerName /u:User /p:Password /a:basic -AllowUntrusted=True
- For the Web Deployment Agent Service (MSDepSvc), include the m flag and specify the destination server name or a service URL as MSDeployAgentService, using the following syntax:
  
  ProjectName.deploy.cmd /t /m:DestinationServerName
  
  ProjectName.deploy.cmd /t /m:https://DestinationServerName/MSDeployAgentService
  
  To specify a user name and password, include the u and p flags. (Do not add the a flag as you do for WMSvc.)
- For the tempAgent provider setting, include the g flag and an m flag to specify a computer name, using the following syntax:
  
  ProjectName.deploy.cmd /t /m:DestinationServerName /g:true
  
  To specify a user name and password, include the u and p flags. (Do not add the a flag as you do for WMSvc.)
- To skip the database provider, include a Web Deploy skip command for the SQL Server provider, using the following syntax:
  
  ProjectName.deploy.cmd /t "-skip:objectName=dbFullSql"
  
  You might do this if you are deploying to a Web farm, you only want to deploy the database one time.
- To skip updating Web.config, include a Web Deploy skip command for a file. You might do this to avoid overwriting Web.config file settings that are configured manually on the destination server.
  
  The following example shows how to skip all Web.config files in the application.
  
  ProjectName.deploy.cmd /t "-skip:objectName= filePath,absolutePath=\\ApplicationFolder\\[\w\s]+web\.config$"
  
  The following example shows how to skip only the application Web.config file.
  
  ProjectName.deploy.cmd /t "-skip:objectName= filePath,absolutePath=\\ApplicationFolder\\web\.config$"
Review the log that is produced by the trial mode deployment, make any changes that are required, and run the command file again using the t flag.
Repeat the previous step until the log reflects exactly the deployment changes that you want.
Execute the command file, using the y flag ("yes", or update mode) instead of the t flag, and using the optional flags that you have selected.

Web Deploy performs the deployment and displays a log of what it does.

The previous procedure provides syntax examples for typical scenarios and shows how to use the flags that are defined in the .cmd file. For other scenarios, you can pass any Web Deploy command to Web Deploy. You are not limited to the flags that are defined in the .cmd file. If you specify a command that includes an equal sign (=), the flag must be enclosed in quotation marks, as shown in the previous examples.

You can also specify Web Deploy commands by setting the __MsDeployAdditionalFlags environment variable.

For more information about other Web Deploy commands that you can use, see Web Deploy Command Line Reference.