How to: Use Parameters to Configure Deployment Settings When a Package is Installed

Article
02/13/2013

When you create a Web deployment package, you might not know some of the values that will be needed when the package is installed. Or you might have to install the same package multiple times and have to specify different settings each time. For example, the person who creates a package might not know a password that is required for installation of the package. Or you might plan to install the same package in the test environment and in the production environment, but you need to specify different WCF endpoints for each environment. This topic explains how you can use parameters to create a package that can be used in these cases.

To create and install Web deployment packages, you must be familiar with the information that is available in the following topics:

For more information, see ASP.NET Deployment Content Map.

Using Database Script Parameters for Deployment

You can include parameters in a SQL Server script. The following example shows how to include a variable that is named logText and how to assign the default value "DefaultText" to it.

:setvar logText DefaultText

INSERT [dbo].[Log] ([LogText]) VALUES (N'$(logText)')
GO

In Visual Studio, if you add a script that contains parameters to the Database Scripts grid on the Package/Publish SQL tab, Visual Studio automatically creates deployment package parameters. You can provide values for these parameters when you install the package, whether you use IIS Manager or a command-line process to do that.

To use database script parameters for deployment

Create a custom SQL script that has one or more parameters.
Add the script to the Database Scripts grid on the Package/Publish SQL tab.
Create the deployment package.

If you use the deploy.cmd file to install the package, and if you want to provide a value that is different from the default value, change the default value in the SetParameters.xml file before you install the package.

For example, if you added the script that is shown in the preceding example, the SetParameters.xml file might resemble the following example:

<parameters>
  <setParameter name="IIS Web Application Name" 
    value="Default Web Site/WebApplication1_deploy" />
  <setParameter name="ApplicationServices-Deployment Connection String"
    value="" />
  <setParameter name="Sql script variable $(logText) in ApplicationServices-Deployment scripts"
    value="DefaultText" />
  <setParameter name="ApplicationServices-Deployment Connection String"
    value="data source=.\SQLEXPRESS;Integrated Security=SSPI;AttachDBFilename=|DataDirectory|\aspnetdb.mdf;User Instance=true" />
</parameters>

You can change the value attribute of the highlighted XML element to set the value of the logText parameter that will be used when the script is run.

If you use IIS Manager to install the package, you will be prompted to enter a value for the parameter in the Enter Application Package Information dialog box, as shown in the following illustration:

Using Deployment Parameters for Web.Config File Settings

You can use Web.config file transforms to change settings in the deployed Web.config file when you know in advance what the values should be. (For more information, see How to: Transform Web.config When Deploying a Web Application Project.) However, if you want to specify values for certain settings when you install a package instead of when you create the package, deployment parameters are a better choice. For example, you might want to configure the following settings when the package is installed:

WCF service endpoints.
Web service endpoints.
Security-related information such as encryption keys.

To use deployment parameters, you have to declare them in an XML file in your project directory. When you declare them, you can provide a default value. You can then change the value that is actually deployed when you install the package.

To use deployment parameters for Web.config file settings

Create an empty text file, name it parameters.xml, and save it in the project folder (the same folder that contains your project's .csproj or .vbproj file).
Add a root element named parameters to the file, as shown in the following example:
```
<parameters>
</parameters>
```
For each parameter that you want to add, perform the following steps:
1. In the parameters root element, create a parameter element with name, description, defaultValue, and tags attributes, as shown in the following example:
```
<parameters>
  <parameter name="WebService1 Endpoint Address" 
    description="Please provide the endpoint address for the Web service that you want to call."
    defaultValue=https://contoso.com/WebService1.asmx
    tags="">
  </parameter>
</parameters>
```
  When you install the package by using IIS Manager, the name attribute value and the description attribute value are shown in the UI, along with a text box in which you can enter a value for the parameter. The defaultValue attribute value is preloaded in the text box.
  
  If you omit the defaultValue attribute, or if you set it to an empty string, or if you set it to a string that contains only spaces, the parameter is treated as a required value. When you install the package by using the Visual Studio deploy.cmd file, you will then have to enter a value in IIS Manager or in the SetParameters.xml file.
  
  The tags attribute enables you to specify the kind of data that the parameter represents, so that the UI can assist with data entry if possible. For example, if you specify Boolean, the UI displays a drop-down list with True and False options. If you specify DBConnectionString, the UI displays a button next to the text box that you can click to display a connection-string dialog box. For a list of tags that you can use, see DeploymentWellKnownTag Enumeration on the Microsoft TechNet Web site.
2. In the parameter element, create a parameterEntry element with kind, scope, and match attributes, as shown in the following example:
```
<parameters>
  <parameter name="WebService1 Endpoint Address"
    description="Please provide the endpoint address for the Web service that you want to call."
    defaultValue="https://contoso.com/WebService1.asmx"
    tags="">
  <parameterEntry 
    kind="XmlFile"
    scope="obj\\Debug\\Package\\PackageTmp\\Web\.config$"
    match="//setting[@name='WebService1EndPoint']/value/text()" />
  </parameter>
</parameters>
```
  The kind attribute specifies what kind of resource the parameter value will be applied to. Web.config files are XML files, so this attribute is set to "XmlFile".
  
  The scope attribute is a regular expression that identifies the path to the specific file that you want to change. In this case, the intention is to change only the application Web.config file (not Web.config files in subfolders). The path that the expression will match against is the one that was stored in the .zip file when the package was created. The regular expression in the example reflects the default package creation location for the Debug build configuration.
  
  The match attribute is an XPath expression that selects the XML node that you want to change. The expression must select a text node or an attribute node, not an element.
3. If you want the same parameter value to be updated in multiple places, create an additional parameterEntry element for each place where you want the parameter value to be updated.
Build the package.

If you use the deploy.cmd file to install the package, you can provide a value that is different from the default value by editing the SetParameters.xml file. (When you create parameters manually in the parameters.xml file, Visual Studio automatically adds them to the SetParameters.xml file when it builds the package. For an example, see the preceding procedure that applies to database script parameters.)

If you use IIS Manager to install the package, you are prompted to enter a value for the parameter in the Enter Application Package Information dialog box. The dialog box displays the name, description, and default value that you specified, as shown in the following illustration:

IIS Manager Package Information dialog box

Using Parameters for Other Scenarios

The preceding procedures provide detailed instructions for common scenarios where parameters are useful. Parameters can also be used for other scenarios, such as when you need to update the contents of text file or XML files other than Web.config files. The following procedure describes how to use parameters for other scenarios.

To use other kinds of parameters

Create a parameter by adding a parameter element to the parameters.xml file as described in the preceding procedure for Web.config file settings.
Add one or more parameterEntry elements that indicate where the parameter value is to be used.

For information about other attributes and attribute values that you can assign to the parameterEntry element, see Using declareParam and setParam on the Microsoft TechNet Web site.