檔案轉換和變數替代參考

發行項
04/04/2024

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

某些工作，例如 Azure App 服務部署工作第 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 轉換將會在名為 *.Release.config 或 *.<stage>.config 的轉換組態檔上*.config執行，並依下列順序執行：

*.Release.config （例如 fabrikam。Release.config）
*.<stage>.config （例如 fabrikam。Production.config）

例如，如果您的套件包含下列檔案：

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

而您的階段名稱為 [生產]，則會套 Web.config 用轉換， Web.Release.config 後面接著 Web.Production.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專案部署的Web.config轉換語法

使用名為 Release 的階段建立發行管線。
新增 Azure App 服務部署工作並設定 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 轉換才會生效。
根據預設，如果 <DependentUpon> 元素已存在於檔案中的轉換檔案 *.csproj 中，MSBuild 就會套用轉換，因為它會產生 Web 套件。在這種情況下，Azure App 服務部署工作將會失敗，因為檔案上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 變數替代

此功能可讓您在 Web 套件和 XML 參數檔案內parameters.xml修改元件檔（*.config檔案）中的組態設定。如此一來，就可以根據部署套件的環境來設定相同的套件。

變數替代只會對組態檔的applicationSettings、 connectionStringsappSettings、和 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 App 服務部署工作並設定 XML 變數替代選項（刻度）。

在發行管線變數中定義必要值：

名稱	值	安全	範圍
Default 連線 ion	數據源=（ProdDB）\MSSQLProdDB;AttachFileName=Local.mdf	No	版本
AdminUserName	Prod 管理員 Name	No	版本
AdminPassword	[your-password]	Yes	版本
invariantName	System.Data.SqlClientExtension	No	版本

儲存發行管線並啟動新版本。

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 應用程式具有預設參數化連接屬性。這些值只會在 Web 套件內的檔案中 parameters.xml 覆寫。
由於替代會在部署之前發生，因此使用者可以使用（Web 套件內部）或setparameters檔案來覆寫中的Web.configparameters.xml 值。

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 檔案階層中個別位置的連線 ionString、DebugMode、Users 值的第一個值，以及 NewWelcomeMessage 的值。

傳統
YAML

使用名為 Release 的階段建立發行管線。
新增 Azure App 服務部署工作，並輸入以換行符分隔的 JSON 檔案清單，以取代 JSON 變數替代文字框中的變數值。檔名必須相對於根資料夾。您可以使用通配符來搜尋 JSON 檔案。例如： **/*.json 表示封裝內所有 JSON 檔案中的替代值。

在發行管線或階段變數中定義必要的替代值。

名稱	值	安全	範圍
Data.DebugMode	停用	No	版本
Data.Default 連線 ion.連線ionString	數據源=（prodDB）\MSDB;AttachDbFilename=prod.mdf;	No	版本
Data.DBAccess.Users.0	管理員-3	Yes	版本
Data.FeatureFlags.Preview.1.NewWelcomeMessage	AllAccounts	No	版本

儲存發行管線並啟動新版本。

轉換之後，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 物件可能包含數位，其值可由其索引參考。例如，若要取代上述 Users 陣列中的第一個值，請使用變數名稱 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"。