如何在 Web 部署包中使用 Web 部署参数

本主题解释了当您创建和安装 Web Deploy 包时，如何使用“Web Deploy”参数。 当您必须安装包并且不知道安装该包所需的某些值时，Web Deploy 包将十分有用。 例如，包的创建者可能不知道安装包时所需的密码。 当您必须多次安装该包，每次都必须指定不同的设置时，“Web Deploy”参数也十分有用。 例如，您可能计划在测试环境和生产环境中安装该包，但您需要为这两个环境指定不同的 WCF 终结点。

本主题假定您知道如何创建和安装部署包。 有关更多信息，请参见 如何：在 Visual Studio 中创建 Web 部署包。

使用数据库脚本参数进行部署

您可以将参数包含在 SQL Server 脚本中。 下面的示例演示如何在“SQL Server”脚本中包含一个名为 logText 的变量以及如何将默认值“DefaultText”分配给该变量。

:setvar logText DefaultText

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

在 Visual Studio 中，您可以指定一个“SQL Server”脚本，在部署过程中应通过选择运行的**“更新数据库”，然后单击“配置数据库更新”**。 如果脚本包含参数，Visual Studio 会自动为部署包创建“Web Deploy”参数。 无论是使用 IIS 管理器还是命令行过程进行安装，都可以在安装包时为这些参数提供值。

使用数据库脚本参数进行部署

1. 创建包含一个或多个参数的自定义 SQL 脚本。

2. 当您配置发布配置文件时，为**“配置数据库更新”**对话框添加脚本。

3. 创建部署包。

4. 如果使用 deploy.cmd 文件安装包，并且希望提供与默认值不同的值，请在安装包之前更改 SetParameters.xml 文件中的默认值。

   例如，如果添加了前面示例所示的脚本，则 SetParameters.xml 文件可能类似于下面的示例：

   <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>
   

   您可以更改突出显示的 XML 元素的 value 特性，设置在脚本运行时将使用的 logText 参数的值。

5. 如果使用 IIS 管理器安装包，系统会提示您在**“输入应用程序包信息”**对话框中输入参数值，如下图所示：

   

对 Web.Config 文件设置使用部署参数

如果事先知道值应该是什么，则可以使用 Web.config 文件转换更改所部署的 Web.config 文件中的设置。 （有关更多信息，请在 ASP.NET 站点上参见 Web.config 文件转换。）但是，如果要在安装包（而不是创建包）时指定某些设置的值，使用部署参数是更好的方法。 例如，您可能需要在安装包时配置以下设置：

• WCF 服务终结点。

• Web 服务终结点。

• 与安全相关的信息（如加密密钥）。

若要使用部署参数，必须在项目目录中的 XML 文件中声明这些参数。 声明参数时，可以提供默认值。 之后在安装包时，可以更改实际部署的值。

对 Web.config 文件设置使用部署参数

1. 创建一个空文本文件，将其命名为 parameters.xml，然后将其保存在项目文件夹（包含项目的 .csproj 或 .vbproj 文件的文件夹）中。

2. 将根元素 parameters 添加到该文件，如下面的示例所示：

   <parameters>
   </parameters>
   

3. 对要添加的每一个参数执行以下步骤：

   1. 在 parameters 根元素中，创建具有 name、description、defaultValue 和 tags 特性的 parameter 元素，如下面的示例所示：

      <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>
      

      使用 IIS 管理器安装包时，UI 中会显示 name 特性值和 description 特性值，以及一个可供输入参数值的文本框。 defaultValue 特性值会预加载在该文本框中。

      如果省略 defaultValue 特性，或如果将该特性设置为空字符串，或将其设置为只包含空格的字符串，则该参数为必需值。 使用 Visual Studio deploy.cmd 文件安装包时，必须在 SetParameters.xml 文件中输入值。

      使用 tags 特性可以指定参数表示的数据类型，以便 UI 可以尽可能帮助进行数据输入。 例如，如果指定 Boolean，则 UI 会显示包含**“True”和“False”**选项的下拉列表。 如果指定 DBConnectionString，则 UI 会在文本框旁显示一个按钮，单击该按钮可以显示连接字符串对话框。 有关可用标记的列表，请参见 Microsoft TechNet 网站上的 DeploymentWellKnownTag Enumeration（DeploymentWellKnownTag 枚举）。

   2. 在 parameter 元素中，创建具有 kind、scope 和 match 特性的 parameterEntry 元素，如下面的示例所示：

      <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>
      

      kind 特性指定参数值将应用于哪种类型的资源。 Web.config 文件是 XML 文件，因此此特性设置为“XmlFile”。

      scope 特性是正则表达式，用于标识要更改的特定文件的路径。 在本例中，只更改应用程序 Web.config 文件（不是子文件夹中的 Web.config 文件）。 表达式匹配的路径是创建包时在 .zip 文件中存储的路径。 示例中的正则表达式反映了“调试”生成配置的默认包创建位置。

      match 特性一个 XPath 表达式，用于选择要更改的 XML 节点。 该表达式必须选择文本节点或特性节点而不是元素。

   3. 如果要在多个位置更新同一个参数值，请为要更新参数值的每个位置都创建一个附加 parameterEntry 元素。

4. 生成包。

如果使用 deploy.cmd 文件安装包，可以通过编辑 SetParameters.xml 文件来提供与默认值不同的值。 （在 parameters.xml 文件中手动创建参数后，Visual Studio 自动在生成包时将这些参数添加到 SetParameters.xml 文件中。 例如，上一个与数据库脚本参数有关的过程。）

如果使用 IIS 管理器安装包，系统会提示您在**“输入应用程序包信息”**对话框中输入参数值。 该对话框显示您指定的名称、描述和默认值，如下图所示：

其他参数使用方案

前面的过程介绍了一些非常有用的常见参数使用方案说明。 除此之外，还有其他参数使用方案，例如，需要更新 Web.config 文件以外的文本文件或 XML 文件的内容。 下面的过程介绍其他参数使用方案。

使用其他类型的参数

1. 通过将 parameter 元素添加到 parameters.xml 文件创建参数，如针对 Web.config 文件设置的前一个过程所述。

2. 添加一个或多个 parameterEntry 元素，用于指示参数值的使用位置。

   有关可以分配给 parameterEntry 元素的其他特性和特性值的信息，请参见 Microsoft TechNet 网站上的 Using declareParam and setParam（使用 declareParam 和 setParam）。

请参见

概念

用于 Visual Studio 和 ASP.NET 的 Web 部署内容映射

其他资源

Vishal Joshi 博客上的“参数化”与“Web.config 转换”

Vishal Joshi 博客上“执行过程中 Web Deploy 参数化”