為 DevTest Labs 建立自訂成品

發行項
09/30/2023

本文說明如何為 Azure DevTest Labs 虛擬機器 (VM) 建立自訂成品檔案。 DevTest Labs 成品會指定佈建 VM 要採取的動作。成品包含成品定義檔案，以及其他儲存於 Git 存放庫資料夾中的指令檔。

如需將成品存放庫新增至實驗室的資訊，請參閱將成品存放庫新增至實驗室 (機器翻譯)。
如需將建立的成品新增至 VM 的資訊，請參閱將成品新增至 DevTest Labs VM (機器翻譯)。
如需指定要新增至所有實驗室 VM 之必要成品的資訊，請參閱指定 DevTest Labs VM 的必要成品 (機器翻譯)。

成品定義檔案

成品定義檔案是 JSON 運算式，指定您想要在 VM 上安裝的項目。這種檔案會定義成品名稱、要執行的命令，以及命令的可用參數。您可以依成品定義檔案中的名稱，參考其他指令檔。

以下範例顯示組成 artifactfile.json 成品定義檔案基本結構的區段：

  {
    "$schema": "https://raw.githubusercontent.com/Azure/azure-devtestlab/master/schemas/2016-11-28/dtlArtifacts.json",
    "title": "",
    "description": "",
    "iconUri": "",
    "targetOsType": "",
    "parameters": {
      "<parameterName>": {
        "type": "",
        "displayName": "",
        "description": ""
      }
    },
    "runCommand": {
      "commandToExecute": ""
    }
  }

元素名稱	描述
`$schema`	JSON 結構描述檔案的位置。 JSON 結構描述檔案可協助您測試定義檔是否有效。
`title`	實驗室中顯示的成品名稱。必要。
`description`	實驗室中顯示的成品說明。必要。
`iconUri`	實驗室中顯示的成品圖示 URI。
`targetOsType`	要安裝成品的 VM 作業系統。支援的值：`Windows`、`Linux`。必要。
`parameters`	要在 VM 上安裝時自訂成品的值。
`runCommand`	要在 VM 上執行的成品安裝命令。必要。

構件參數

在定義檔案的參數區段中，指定使用者可在安裝成品時輸入的值。您可以在構件安裝命令中參考這些值。

若要定義參數，請使用下列結構：

  "parameters": {
    "<parameterName>": {
      "type": "<type-of-parameter-value>",
      "displayName": "<display-name-of-parameter>",
      "description": "<description-of-parameter>"
    }
  }

元素名稱	描述
`type`	參數值類型。必要。
`displayName`	要向實驗室使用者顯示的參數名稱。必要。
`description`	要向實驗室使用者顯示的參數說明。必要。

允許的參數值類型如下：

類型	描述
`string`	任何有效的 JSON 字串
`int`	任何有效的 JSON 整數
`bool`	任何有效的 JSON 布林值
`array`	任何有效的 JSON 陣列

將秘密當作安全字串

若要在 UI 中將秘密宣告為使用遮罩字元的安全字串參數，請在 artifactfile.json 檔案的 parameters 區段中使用以下語法：


    "securestringParam": {
      "type": "securestring",
      "displayName": "Secure String Parameter",
      "description": "Any text string is allowed, including spaces, and will be presented in UI as masked characters.",
      "allowEmpty": false
    },

執行 PowerShell 指令碼的成品安裝命令，會接受使用 ConvertTo-SecureString 命令建立的安全字串。

  "runCommand": {
    "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./artifact.ps1 -StringParam ''', parameters('stringParam'), ''' -SecureStringParam (ConvertTo-SecureString ''', parameters('securestringParam'), ''' -AsPlainText -Force) -IntParam ', parameters('intParam'), ' -BoolParam:$', parameters('boolParam'), ' -FileContentsParam ''', parameters('fileContentsParam'), ''' -ExtraLogLines ', parameters('extraLogLines'), ' -ForceFail:$', parameters('forceFail'), '\"')]"
  }

請勿將秘密記錄到主控台，因為指令碼會擷取使用者偵錯的輸出。

構件運算式和函式

您可以使用運算式和函式來建構構件安裝命令。運算式會在成品安裝時評估。運算式可能會出現在 JSON 字串值中的任何一處，並一律傳回另一個 JSON 值。以括弧 [ ] 括住運算式。如果您必須使用以括弧開頭的常值字串，請使用兩個括弧 [[。

您通常會搭配函式使用運算式來建構值。函式呼叫的格式為 functionName(arg1, arg2, arg3)。

常見函式包括：

函式	描述
`parameters(parameterName)`	傳回參數值，在成品命令執行時提供。
`concat(arg1, arg2, arg3, ...)`	結合多個字串值。此函式可以接受多種引數。

以下範例使用運算式和函式來建構值：

  runCommand": {
      "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./startChocolatey.ps1'
  , ' -RawPackagesList ', parameters('packages')
  , ' -Username ', parameters('installUsername')
  , ' -Password ', parameters('installPassword'))]"
  }

建立自訂構件

若要建立自訂成品：

安裝 JSON 編輯器以使用成品定義檔案。 Visual Studio Code 適用於 Windows、Linux 和 macOS。
從範例 artifactfile.json 定義檔案開始。

公用 DevTest Labs 成品存放庫有您可使用的豐富成品。下載成品定義檔案，並加以自訂，建立您自己的成品。

本文使用 artifactfile.json 定義檔案，以及 https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes 的 artifact.ps1 PowerShell 指令碼。
使用 IntelliSense 來查看可用於建構成品定義檔案的有效元素和值選項。例如，編輯 targetOsType 元素時，IntelliSense 會向您顯示 Windows 或 Linux 選項。
將您的成品儲存在公用或私人 Git 成品存放庫中。
- 將每個 artifactfile.json 成品定義檔案儲存在與成品名稱相同的個別目錄中。
- 將安裝命令參考的指令碼儲存在與成品定義檔案相同的目錄中。
以下螢幕擷取畫面顯示範例成品資料夾：
若要將自訂成品儲存在公用 DevTest Labs 成品存放庫中，請針對存放庫建立提取要求。
若要將私人成品存放庫新增至實驗室，請參閱將成品存放庫新增至 DevTest Labs 中的實驗室 (機器翻譯)。

共用方式為