FileTransform@2 - 檔案轉換 v2 工作

使用此工作將令牌取代為 XML 或 JSON 組態檔中的變數值。

語法

# File transform v2
# Replace tokens with variable values in XML or JSON configuration files.
- task: FileTransform@2
  inputs:
    folderPath: '$(System.DefaultWorkingDirectory)/**/*.zip' # string. Required. Package or folder. Default: $(System.DefaultWorkingDirectory)/**/*.zip.
    #enableXmlTransform: true # boolean. XML transformation. Default: true.
    #xmlTransformationRules: '-transform **\*.Release.config -xml **\*.config' # string. Optional. Use when enableXmlTransform == true. XML Transformation rules. Default: -transform **\*.Release.config -xml **\*.config.
  # Variable Substitution
    #jsonTargetFiles: # string. JSON target files. 
    #xmlTargetFiles: # string. XML target files.

輸入

folderPath - 套件或資料夾
string。 必填。 預設值：$(System.DefaultWorkingDirectory)/**/*.zip。

封裝或資料夾的檔案路徑。

變數 組建，版本。 支援通配符。

例如，$(System.DefaultWorkingDirectory)/**/*.zip。 對於壓縮的資料夾，內容會擷取至 TEMP 位置、執行轉換，以及壓縮原始成品位置的結果。

enableXmlTransform - XML 轉換
boolean。 預設值：true。

組態轉換將會在變數替代之前執行。

只有 Windows 平臺才支援 XML 轉換。

xmlTransformationRules - XML 轉換規則
string。 自選。 enableXmlTransform == true時使用 。 預設值：-transform **\*.Release.config -xml **\*.config。

使用 語法提供換行符分隔的轉換檔案規則清單：-transform <pathToTransformFile> -xml <pathToSourceConfigurationFile>。 結果檔路徑是選擇性的，如果未指定，來源組態檔將會取代為轉換的結果檔。

jsonTargetFiles - JSON 目標檔案
string。

提供以換行符分隔的檔案清單，以取代變數值。 檔名會相對於根資料夾提供。

例如，若要取代下列範例中的 ConnectionString 值，您必須在組建或發行管線中將變數定義為 Data.DefaultConnection.ConnectionString（或發行管線的環境）。

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Server=(localdb)\SQLEXPRESS;Database=MyDB;Trusted_Connection=True"
    }
  }
}

變數替代會在組態轉換之後執行。

注意：只有建置/發行管線中定義的自定義變數才會用於替代。 排除預設/系統定義的管線變數。 如果在發行管線和階段中定義相同的變數，則階段變數將會取代發行管線變數。

xmlTargetFiles - XML 目標檔案
string。

提供以換行符分隔的檔案清單，以取代變數值。 檔名會相對於根資料夾提供。

針對 XML，建置或發行管線中定義的變數將會比對任何組態檔和 parameters.xml中 appSettings、applicationSettings和 connectionStrings 區段中的 key 或 name 專案。

變數替代會在組態轉換之後執行。

注意：只有建置/發行管線中定義的自定義變數才會用於替代。 排除預設/系統定義的管線變數。 如果在發行管線和階段中定義相同的變數，則階段變數將會取代發行管線變數。

工作控制選項

除了工作輸入之外，所有工作都有控制選項。 如需詳細資訊，請參閱 控制項選項和一般工作屬性。

輸出變數

沒有。

言論

檔案轉換第 2 版的新功能：

• 更優化的工作欄位，可讓使用者在單一工作實例中啟用任何/所有轉換 （XML）、變數替代 （JSON 和 XML） 功能。
• 當未套用任何已設定的轉換/替代或工作 no-op時，工作就會失敗。

使用此工作，在組態和參數檔案上套用檔案轉換和變數替代。 如需翻譯處理方式的詳細資訊，請參閱 檔案轉換和變數替代參考。

重要

這項工作適用於 Web 套件，而且需要 Web 套件檔案。 它不適用於獨立 JSON 檔案。

檔案轉換

• 目前，只有 XML 檔案支援檔案轉換。
• 若要將 XML 轉換套用至組態檔 （*.config），您必須使用語法指定換行分隔的轉換檔案規則清單：-t ransform <path to the transform file> -xml <path to the source file> -result <path to the result file>
• 檔案轉換在許多案例中都很有用，特別是當您部署至 App Service，並且想要新增、移除或修改不同環境的組態（例如開發、測試或 Prod），方法是遵循標準 Web.config 轉換語法。
• 您也可以使用這項功能來轉換其他檔案，包括主控台或 Windows 服務應用程式組態檔（例如，FabrikamService.exe.config）。
• 組態檔轉換會在變數替代之前執行。

變數替代

• 目前只有 XML 和 JSON 檔案格式支援變數替代。
• 目標組態檔中定義的令牌會更新，然後取代為變數值。
• 變數替代會在組態檔轉換之後執行。
• 變數替代只會套用至物件階層中預先定義的 JSON 索引鍵。 它不會建立新的金鑰。

注意

只有建置和發行管線中定義的自定義變數才會用於替代。 默認和系統管線變數會排除。

以下是目前排除的前置詞清單：

• agent.
• azure_http_user_agent
• build.
• common.
• release.
• system.
• tf_

如果在發行管線和階段中定義相同的變數，階段定義的變數會取代管線定義的變數。

另請參閱：檔案轉換和變數替代參考。

例子

如果您需要 XML 轉換以模式 .Production.config在所有名為 的組態檔上執行，則轉換規則應指定為：

-transform **\*.Production.config -xml **\*.config

如果您的組態檔是以管線中的階段名稱為基礎來命名，您可以使用：

-transform **\*.$(Release.EnvironmentName).config -xml **\*.config

若要取代巢狀或階層式的 JSON 變數，請使用 JSONPath 運算式加以指定。 例如，若要取代下列範例中的 ConnectionString 值，您必須在組建或發行管線中將變數定義為 Data.DefaultConnection.ConnectionString（或在發行管線內的階段）。

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Server=(localdb)\SQLEXPRESS;Database=MyDB;Trusted_Connection=True"
    }
  }
}

要求

要求	描述
管線類型	YAML、傳統組建、傳統版本
執行於	Agent、DeploymentGroup
需求	沒有
功能	此工作不符合作業中後續工作的任何需求。
命令限制	任何
Settable 變數	任何
代理程式版本	所有支援的代理程式版本。
工作類別	效用

另請參閱

• 檔案轉換和變數替代參考