为 Web 程序包部署配置参数

项目
07/13/2023

本主题介绍如何在将 Web 包部署到远程 IIS Web 服务器时设置参数值，例如 Internet Information Services (IIS) Web 应用程序名称、连接字符串和服务终结点。

生成 Web 应用程序项目时，生成和打包过程将生成三个关键文件：

[项目名称].zip 文件。这是 Web 应用程序项目的 Web 部署包。此包包含在远程 IIS Web 服务器上重新创建 Web 应用程序所需的所有程序集、文件、数据库脚本和资源。
[项目名称].deploy.cmd 文件。它包含一组参数化 Web 部署 (MSDeploy.exe) 命令，用于将 Web 部署包发布到远程 IIS Web 服务器。
[项目名称].SetParameters.xml 文件。这为 MSDeploy.exe 命令提供一组参数值。部署 Web 包时，可以更新此文件中的值，并将其作为命令行参数传递给 Web 部署。

注意

有关生成和打包过程的详细信息，请参阅生成和打包 Web 应用程序项目。

SetParameters.xml文件是从 Web 应用程序项目文件和项目内的任何配置文件动态生成的。生成和打包项目时，Web 发布管道 (WPP) 将自动检测部署环境（例如目标 IIS Web 应用程序和任何数据库连接字符串）之间可能更改的许多变量。这些值在 Web 部署包中自动参数化，并添加到 SetParameters.xml 文件中。例如，如果将连接字符串添加到 Web 应用程序项目中 的web.config 文件，则生成过程将检测此更改，并将相应地向 SetParameters.xml 文件添加一个条目。

在许多情况下，这种自动参数化就足够了。但是，如果用户需要在部署环境之间更改其他设置（如应用程序设置或服务终结点 URL），则需要告知 WPP 在部署包中参数化这些值，并将相应的条目添加到 SetParameters.xml 文件。以下各节介绍了如何执行此操作。

自动参数化

生成和打包 Web 应用程序时，WPP 将自动参数化这些内容：

目标 IIS Web 应用程序路径和名称。
web.config 文件中的任何连接字符串。
添加到项目属性页中 “包/发布 SQL ”选项卡的任何数据库的连接字符串。

例如，如果要生成和打包 Contact Manager 示例解决方案，而不以任何方式接触参数化过程，则 WPP 将生成以下 ContactManager.Mvc.SetParameters.xml 文件：

<parameters>
  <setParameter 
    name="IIS Web Application Name" 
    value="Default Web Site/ContactManager.Mvc_deploy" />  
  <setParameter 
    name="ApplicationServices-Web.config Connection String" 
    value="Data Source=DEVWORKSTATION\SQLEXPRESS;Initial Catalog=CMAppServices;
           Integrated Security=true;" />
</parameters>

在这种情况下：

IIS Web 应用程序名称参数是要在其中部署 Web 应用程序的 IIS 路径。默认值取自项目属性页中的 “包/发布”网页 。
ApplicationServices-Web.config连接字符串参数是从web.config文件中的 connectionStrings/add 元素生成的。它表示应用程序应用于联系成员资格数据库的连接字符串。此处提供的值将替换为已部署 的web.config 文件中。默认值取自预部署 web.config 文件。

WPP 还在它生成的部署包中参数化这些属性。安装部署包时，可以为这些属性提供值。如果按照手动安装 Web 包中所述，通过 IIS 管理器手动安装包，安装向导会提示你提供任何参数的值。如果使用 .deploy.cmd 文件远程安装包（如部署 Web 包中所述），Web 部署将查找此 SetParameters.xml 文件来提供参数值。可以手动编辑 SetParameters.xml 文件中的值，也可以在自动生成和部署过程中自定义该文件。本主题稍后将更详细地介绍此过程。

自定义参数化

在更复杂的部署方案中，通常需要在部署项目之前参数化其他属性。一般来说，应参数化目标环境之间将变化的任何属性和设置。其中包括：

web.config 文件中的服务终结点。
web.config 文件中的应用程序设置。
要提示用户指定的任何其他声明性属性。

参数化这些属性的最简单方法是将 parameters.xml 文件添加到 Web 应用程序项目的根文件夹。例如，在 Contact Manager 解决方案中，ContactManager.Mvc 项目在根文件夹中包含 parameters.xml 文件。

在 Contact Manager 解决方案中，ContactManager.Mvc 项目在根文件夹中包含一个 parameters.xml 文件。

如果打开此文件，将看到它包含单个参数条目。条目使用 XML 路径语言 (XPath) 查询在 web.config 文件中查找和参数化 ContactService Windows Communication Foundation (WCF) 服务的终结点 URL。

<parameters>
  <parameter name="ContactService Service Endpoint Address"
             description="Specify the endpoint URL for the ContactService WCF 
                          service in the destination environment"
             defaultValue="http://localhost/ContactManagerService">
    <parameterEntry kind="XmlFile" scope="Web.config"
                    match="/configuration/system.serviceModel/client
                           /endpoint[@name='BasicHttpBinding_IContactService']
                           /@address" />
  </parameter>
</parameters>

除了参数化部署包中的终结点 URL 外，WPP 还会向与部署包一起生成的 SetParameters.xml 文件添加相应的条目。

<parameters>
  ...  
  <setParameter 
    name="ContactService Service Endpoint Address" 
    value="http://localhost/ContactManagerService" />
  ...
</parameters>

如果手动安装部署包，IIS 管理器将提示你提供服务终结点地址以及自动参数化的属性。如果通过运行 .deploy.cmd 文件安装部署包，则可以编辑 SetParameters.xml 文件，以便为服务终结点地址提供值以及自动参数化的属性的值。

有关如何创建 parameters.xml 文件的完整详细信息，请参阅如何：在安装包时使用参数配置部署设置。名为“ 将部署参数用于Web.config文件设置 ”的过程提供了分步说明。

修改SetParameters.xml文件

如果计划手动部署 Web 应用程序包（通过运行 .deploy.cmd 文件或从命令行运行MSDeploy.exe），则没有什么可以阻止你在部署前手动编辑 SetParameters.xml 文件。但是，如果使用的是企业级解决方案，则可能需要在更大的自动生成和部署过程中部署 Web 应用程序包。在这种情况下，需要Microsoft 生成引擎 (MSBuild) 来修改SetParameters.xml文件。可以使用 MSBuild XmlPoke 任务执行此操作。

联系人管理器示例解决方案演示了此过程。下面的代码示例已编辑为仅显示与此示例相关的详细信息。

注意

有关示例解决方案中项目文件模型的更广泛概述，以及自定义项目文件的一般介绍，请参阅了解项目文件和了解生成过程。

首先，相关参数值定义为特定于环境的项目文件中的属性， (例如 Env-Dev.proj) 。

<PropertyGroup> 
  <ContactManagerIisPath Condition=" '$(ContactManagerIisPath)'=='' ">
    DemoSite/ContactManager
  </ContactManagerIisPath>
  <ContactManagerTargetUrl Condition =" '$(ContactManagerTargetUrl)'=='' ">
    http://localhost:85/ContactManagerService/ContactService.svc
  </ContactManagerTargetUrl>
  <MembershipConnectionString Condition=" '$(MembershipConnectionString)'=='' ">
    Data Source=TESTDB1;Integrated Security=true;Initial Catalog=CMAppServices
  </MembershipConnectionString>  
</PropertyGroup>

注意

有关如何为自己的服务器环境自定义特定于环境的项目文件的指南，请参阅为目标环境配置部署属性。

接下来， Publish.proj 文件导入这些属性。由于每个SetParameters.xml文件都与 .deploy.cmd 文件相关联，因此我们最终希望项目文件调用每个 .deploy.cmd 文件，因此项目文件为每个 .deploy.cmd 文件创建一个 MSBuild 项，并将感兴趣的属性定义为项元数据。

<ItemGroup>
  <PublishPackages Include="$(_ContactManagerDest)ContactManager.Mvc.deploy.cmd"> 
    <ParametersXml>
      $(_ContactManagerDest)ContactManager.Mvc.SetParameters.xml
    </ParametersXml>
    <IisWebAppName>
      $(ContactManagerIisPath)
    </IisWebAppName> 
    <MembershipDBConnectionName>
      ApplicationServices-Web.config Connection String
    </MembershipDBConnectionName>
    <MembershipDBConnectionString>
      $(MembershipConnectionString.Replace(";","%3b"))
    </MembershipDBConnectionString>
    <ServiceEndpointParamName>
      ContactService Service Endpoint Address
    </ServiceEndpointParamName>
    <ServiceEndpointValue>
      $(ContactManagerTargetUrl)
    </ServiceEndpointValue>
  </PublishPackages>
  ...
</ItemGroup>

在这种情况下：

ParametersXml 元数据值指示SetParameters.xml文件的位置。
IisWebAppName 值是要将 Web 应用程序部署到的 IIS 路径。
MembershipDBConnectionString 值是成员资格数据库的连接字符串，MembershipDBConnectionName 值是SetParameters.xml文件中相应参数的 name 属性。
ServiceEndpointValue 值是目标服务器上的 WCF 服务的终结点地址，ServiceEndpointParamName 值是SetParameters.xml文件中相应参数的 name 属性。

最后，在 Publish.proj 文件中， PublishWebPackages 目标使用 XmlPoke 任务修改 SetParameters.xml 文件中的这些值。

<Target Name="PublishWebPackages" Outputs="%(PublishPackages.Identity)">
  <XmlPoke 
    XmlInputPath="%(PublishPackages.ParametersXml)"
    Query="//parameters/setParameter[@name='%(PublishPackages.ConnectionName)']
           /@value"
    Value="%(PublishPackages.ConnectionString)"
    Condition =" '%(PublishPackages.ConnectionName)'!=''" 
  />
  <XmlPoke 
    XmlInputPath="%(PublishPackages.ParametersXml)"
    Query="//parameters/setParameter
           [@name='%(PublishPackages.MembershipDBConnectionName)']/@value"
    Value='%(PublishPackages.MembershipDBConnectionString)'
    Condition =" '%(PublishPackages.MembershipDBConnectionName)'!=''" 
  />
  <XmlPoke 
    XmlInputPath="%(PublishPackages.ParametersXml)"
    Query="//parameters/setParameter[@name='IIS Web Application Name']/@value"
    Value="%(PublishPackages.IisWebAppName)"
    Condition =" '%(PublishPackages.IisWebAppName)'!=''" 
  />
  <XmlPoke 
    XmlInputPath="%(PublishPackages.ParametersXml)"
    Query="//parameters/setParameter
           [@name='%(PublishPackages.ServiceEndpointParamName)']/@value"
    Value="%(PublishPackages.ServiceEndpointValue)"
    Condition =" '%(PublishPackages.ServiceEndpointParamName)'!=''" 
  /> 
  <!--Execute the .deploy.cmd file--> 
  ...
</Target>

你会注意到，每个 XmlPoke 任务指定四个属性值：

XmlInputPath 属性指示任务在何处查找要修改的文件。
Query 属性是一个 XPath 查询，用于标识要更改的 XML 节点。
Value 属性是要插入到所选 XML 节点中的新值。
Condition 属性是任务应运行或不运行的条件。在这些情况下，条件可确保不会尝试在 SetParameters.xml 文件中插入 null 或空值。

结论

本主题介绍了 SetParameters.xml 文件的角色，并介绍了生成 Web 应用程序项目时该文件的生成方式。它介绍了如何通过向项目添加 parameters.xml 文件来参数化其他设置。它还介绍了如何使用项目文件中的 XmlPoke 任务修改 SetParameters.xml 文件作为更大的自动生成过程的一部分。

下一主题部署 Web 包介绍了如何通过运行 .deploy.cmd 文件或直接使用 MSDeploy.exe 命令来部署 Web 包。在这两种情况下，都可以将 SetParameters.xml 文件指定为部署参数。

深入阅读

有关如何创建 Web 包的信息，请参阅生成和打包 Web 应用程序项目。有关如何实际部署 Web 包的指南，请参阅部署 Web 包。有关如何创建 parameters.xml 文件的分步演练，请参阅如何：在安装包时使用参数配置部署设置。

有关 Web 部署中参数化的更多常规信息，请参阅 Web 部署参数化在操作 (博客文章) 。

为 Web 程序包部署配置参数

自动参数化

自定义参数化

修改SetParameters.xml文件

结论

深入阅读

反馈

反馈

其他资源