文件转换和变量替换引用

项目
07/19/2022

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018

注意

在 Microsoft Team Foundation Server (TFS) 2018 和更低版本中，生成和发布管道被称为“定义”，运行被称为“生成”，服务连接被称为“服务终结点”，阶段被称为“环境”，而作业被称为“阶段” 。

某些任务（例如Azure 应用服务部署任务版本 3 及更高版本和 IIS Web 应用部署任务）允许用户根据指定的环境配置包。这些任务使用 msdeploy.exe，它支持将 web.config 文件中的值替换为 parameters.xml 文件中的值。但是，文件转换和变量替换 不局限于 Web 应用文件。可以将这些技术用于任何 XML 或 JSON 文件。

注意

单独的文件转换任务也支持文件转换和变量替换，以便在Azure Pipelines中使用。可以使用文件转换任务对任何配置和参数文件应用文件转换和变量替换。

配置替换是在任务设置的文件 转换和变量替换选项 部分中指定的。转换和替换选项包括：

XML 转换
XML 变量替换
JSON 变量替换

任务运行时，它首先对配置和参数文件执行 XML 转换、XML 变量替换和 JSON 变量替换。接下来，它会调用 msdeploy.exe，该文件使用 parameters.xml 文件替换 web.config 文件中的值。

XML 转换

XML 转换支持按照Web.config转换语法转换配置文件 (*.config文件) 转换，并且基于 Web 包将部署到的环境。如果要为不同的环境添加、删除或修改配置，此选项非常有用。转换将应用于其他配置文件，包括控制台或Windows服务应用程序 (配置文件，例如 FabrikamService.exe.config) 。

配置转换文件命名约定

XML 转换将在名为或*.<stage>.config按以下顺序执行的转换配置文件的文件*.Release.config上运行*.config：

*.Release.config 例如， (fabrikam.Release.config)
*.<stage>.config 例如， (fabrikam.Production.config)

例如，如果包包含以下文件：

Web.config
Web.Debug.config
Web.Release.config
Web.Production.config

阶段名称为“生产”，转换后跟Web.Production.config应用Web.configWeb.Release.config。

XML 转换示例

使用必要的配置和转换文件创建 Web 应用程序包。例如，使用以下配置文件：

配置文件

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <add name="DefaultConnection"
         connectionString="Data Source=(LocalDb)\\MSDB;DbFilename=aspcore-local.mdf;" />
  </connectionStrings>
  <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="false" />
  </appSettings>
  <system.web>
    <authentication mode="None" />
    <compilation targetFramework="4.5" debug="true" />
  </system.web>
</configuration>

转换文件

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <connectionStrings>
      <add name="MyDB"
           connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True"
           xdt:Transform="Insert" />
    </connectionStrings>
  <appSettings>
    <add xdt:Transform="Replace" xdt:Locator="Match(key)" key="webpages:Enabled" value="true" />
  </appSettings>
  <system.web>
    <compilation xdt:Transform="RemoveAttributes(debug)" />
  </system.web>
</configuration>

此示例转换配置文件执行三项操作：

它会在元素中添加 ConnectionStrings 一个新的数据库连接字符串。
它修改元素内appSettings的值Webpages:Enabled。
它将从compilation元素内的System.Web元素中删除debug该属性。

有关详细信息，请参阅使用 Visual Studio 为 Web Project 部署Web.config转换语法

使用名为 Release 的阶段创建发布管道。
添加Azure 应用服务部署任务，并在 XML 转换选项) 设置 (刻度。
保存发布管道并启动新版本。

Web.config打开文件以查看转换的转换。Web.Release.config

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <add name="DefaultConnection"
         connectionString="Data Source=(LocalDb)\\MSDB;DbFilename=aspcore-local.mdf;" />
  <add name="MyDB"
       connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True" />
  </connectionStrings>
  <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="true" />
  </appSettings>
  <system.web>
    <authentication mode="None" />
    <compilation targetFramework="4.5" />
  </system.web>
</configuration>

XML 转换说明

可以使用此方法创建默认包并将其部署到多个阶段。
仅当配置文件和转换文件位于指定包中的同一文件夹中时，XML 转换才生效。
默认情况下，如果元素已存在于文件中的转换文件中*.csproj，则MSBuild应用转换，因为它会生成 Web 包<DependentUpon>。在这种情况下，Azure 应用服务部署任务将失败，因为文件中没有进一步应用的Web.config转换。因此，建议 <DependentUpon> 从所有转换文件中删除该元素，以在使用 XML 转换时禁用任何生成时配置。

将每个转换文件的 生成操作 属性 (Web.config) 设置为 “内容 ”，以便将文件复制到根文件夹。

...
<Content Include="Web.Debug.config">
   <DependentUpon>Web.config</DependentUpon>
</Content>
<Content Include="Web.Release.config">
   <DependentUpon>Web.config</DependentUpon>
</Content>
...

XML 变量替换

此功能使你能够修改配置文件中的配置设置 (*.config 文件) web 包和 XML 参数文件 (parameters.xml) 。这样，就可以根据要部署到的环境来配置同一包。

变量替换仅对配置文件的applicationSettings元素appSettingsconnectionStrings和configSections元素生效。如果要替换这些元素之外的值，可以使用 () parameters.xml 文件，但需要使用第三方管道任务来处理变量替换。

XML 变量替换示例

例如，请考虑在以下值中 Web.config更改以下值的任务：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <configSection>
        <section name="entityFramework" />
    </configSection>
    <connectionStrings>
        <!-- Change connectionString in this line: --> 
        <add name="DefaultConnection"
             connectionString="Data Source=(LocalDB)\LocalDB;FileName=Local.mdf" />
    </connectionStrings>
    <appSettings>
        <add key="ClientValidationEnabled" value="true" />
        <add key="UnobstructiveJavascriptEnabled" value="true" />
        <!-- Change AdminUserName in this line: --> 
        <add key="AdminUserName" value="__AdminUserName__" />
        <!-- Change AdminPassword in this line: --> 
        <add key="AdminPassword" value="__AdminPassword__" />
    </appSettings>
    <entityFramework>
        <defaultConnectionFactory type="System.Data.Entity.LocalDbConnectionFactory">
            <parameters></parameters>
        </defaultConnectionFactory>
        <providers>
            <!-- Change invariantName in this line: --> 
            <provider invariantName="System.Data.SqlClient" type="System.Data.Entity.SqlServer" />
        </providers>
    </entityFramework>
</configuration>

使用名为 Release 的阶段创建发布管道。
添加Azure 应用服务部署任务，并在 XML 变量替换选项) 设置 (刻度。

在发布管道变量中定义所需的值：

“属性”	值	安全	范围
DefaultConnection	数据源= (ProdDB) \MSSQLProdDB;AttachFileName=Local.mdf	否	发布
AdminUserName	ProdAdminName	否	发布
AdminPassword	[your-password]	是	发布
invariantName	System.Data.SqlClientExtension	否	发布

保存发布管道并启动新版本。

Web.config打开该文件以查看变量替换。

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <configSection>
        <section name="entityFramework" />
    </configSection>
    <connectionStrings>
        <add name="DefaultConnection"
             connectionString="Data Source=(ProdDB)\MSSQLProdDB;AttachFileName=Local.mdf" />
    </connectionStrings>
    <appSettings>
        <add key="ClientValidationEnabled" value="true" />
        <add key="UnobstructiveJavascriptEnabled" value="true" />
        <add key="AdminUserName" value="ProdAdminName" />
        <add key="AdminPassword" value="*password_masked_for_display*" />
    </appSettings>
    <entityFramework>
        <defaultConnectionFactory type="System.Data.Entity.LocalDbConnectionFactory">
            <parameters></parameters>
        </defaultConnectionFactory>
        <providers>
            <provider invariantName="System.Data.SqlClientExtension"
                      type="System.Data.Entity.SqlServer" />
        </providers>
    </entityFramework>
</configuration>

XML 变量替换说明

默认情况下，ASP.NET 应用程序具有默认参数化连接属性。这些值仅在 parameters.xml Web 包内的文件中被重写。
由于在部署之前发生替换，因此用户可以在 web 包内 Web.config 使用 parameters.xml (替代值，) 或 setparameters 文件。

JSON 变量替换

此功能替换 JSON 配置文件中的值。它替代指定 JSON 配置文件中的值 (例如， appsettings.json) 与发布管道和阶段变量的值匹配的值。

若要替换特定 JSON 文件中的变量，请提供 JSON 文件的新行分隔列表。必须指定相对于根文件夹的文件名。例如，如果包具有以下结构：

/WebPackage(.zip)
  /---- content
    /----- website
      /---- appsettings.json
      /---- web.config
      /---- [other folders] 
  /--- archive.xml
  /--- systeminfo.xml

并且想要替换 appsettings.json 中的值，请输入根文件夹中的相对路径;例如 content/website/appsettings.json。或者，使用通配符模式搜索特定的 JSON 文件。例如， **/appsettings.json 返回名为 appsettings.json 的文件的相对路径和名称。

JSON 变量替换示例

例如，请考虑重写此 JSON 文件中的值的任务：

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Data Source=(LocalDb)\\MSDB;AttachDbFilename=aspcore-local.mdf;"
    },
    "DebugMode": "enabled",
    "DBAccess": {
      "Administrators": ["Admin-1", "Admin-2"],
      "Users": ["Vendor-1", "vendor-3"]
    },
    "FeatureFlags": {
      "Preview": [
        {
          "newUI": "AllAccounts"
        },
        {
          "NewWelcomeMessage": "Newusers"
        }
      ]
    }
  }
}

任务是在 JSON 文件层次结构中的相应位置重写 ConnectionString、 DebugMode、 Users 值的第一个值和 NewWelcomeMessage 的值。

经典
YAML

使用名为 Release 的阶段创建发布管道。
添加Azure 应用服务部署任务，并输入 JSON 文件换行列表以替换 JSON 变量替换文本框中的变量值。文件名必须相对于根文件夹。可以使用通配符搜索 JSON 文件。例如： **/*.json 表示包中所有 JSON 文件中的替换值。

在发布管道或阶段变量中定义所需的替换值。

“属性”	值	安全	范围
Data.DebugMode	disabled	否	发布
Data.DefaultConnection.ConnectionString	数据源= (prodDB) \MSDB;AttachDbFilename=prod.mdf;	否	发布
Data.DBAccess.Users.0	Admin-3	是	发布
Data.FeatureFlags.Preview.1.NewWelcomeMessage	AllAccounts	否	发布

保存发布管道并启动新版本。

转换后，JSON 将包含以下项：

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;"
    },
    "DebugMode": "disabled",
    "DBAccess": {
      "Administrators": ["Admin-1", "Admin-2"],
      "Users": ["Admin-3", "vendor-3"]
    },
    "FeatureFlags": {
      "Preview": [
        {
          "newUI": "AllAccounts"
        },
        {
          "NewWelcomeMessage": "AllAccounts"
        }
      ]
    }
  }
}
'''

以下 YAML 代码片段显示了 JSON 变量替换。

variables:
  Data.DebugMode: disabled
  Data.DefaultConnection.ConnectionString: 'Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;'
  Data.DBAccess.Users.0: Admin-3
  Data.FeatureFlags.Preview.1.NewWelcomeMessage: AllAccounts

# Update appsettings.json via FileTransform task.
- task: FileTransform@1
  displayName: 'File transformation: appsettings.json'
  inputs:
    folderPath: '$(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip'
    targetFiles: '**/appsettings.json'
    fileType: json
  
# Deploy web app
- task: AzureWebApp@1
  inputs:
    azureSubscription: <Name of the Azure subscription>
    appName: <Name of the Azure WebApp>
    package: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip

JSON 变量替换注释

若要替换文件嵌套级别中的值，请按分层顺序将名称与句点 (.) 连接。
JSON 对象可能包含一个数组，其值可由其索引引用。例如，若要替换上面所示 的用户 数组中的第一个值，请使用变量名称 DBAccess.Users.0。若要更新 NewWelcomeMessage 中的值，请使用变量名称 FeatureFlags.Preview.1.NewWelcomeMessage。但是，文件转换任务能够转换 JSON 文件中的整个数组。还可以使用 DBAccess.Users = ["NewUser1","NewUser2","NewUser3"]。
JSON 变量替换仅支持 字符串 替换。
仅 UTF-8 和 UTF-16 LE 编码文件支持替换。
如果输入的文件规范与任何文件不匹配，则任务将失败。
变量名称匹配区分大小写。
变量替换仅适用于对象层次结构中预定义的 JSON 键。它不会创建新密钥。
如果变量名称包含句点 (“。”) ，转换将尝试找到层次结构中的项。例如，如果变量名称为 first.second.third，转换过程将搜索：
```
"first" : {
  "second": {
    "third" : "value"
  }
}
```
以及 "first.second.third" : "value"。