為 DevTest Labs 虛擬機建立自訂工件

成品是您可以新增至 Azure DevTest Labs VM 的工具、動作或軟體。 例如，工件可以執行腳本、安裝工具，或執行加入網域等操作。 DevTest Labs 的使用者可以 將工件加入他們的虛擬機，實驗室管理員也可以 指定必須在所有實驗室虛擬機中新增的工件。

本文說明如何建立用於實驗室虛擬機配置的工件。 產物由產物定義 JSON 檔案及其他腳本檔案組成，這些檔案存放在 Git 儲存庫資料夾中。 你可以將產物存放在私人或公開的 Git 倉庫中。 實驗室管理員可以 將工件儲存庫加入實驗室 ，讓所有實驗室使用者都能存取。

先決條件

• 要建立並處理工件定義檔案，你需要一個 JSON 編輯器。 Visual Studio Code 支援 Windows、Linux 和 macOS。
• 要儲存工件定義和腳本檔案，你需要一個 GitHub 帳號。

了解工件定義檔案

工件定義檔案由一個 JSON 表達式組成，用以指定要對虛擬機執行的動作。 該檔案定義了一個工件名稱、一個要執行的指令，以及該指令可用的參數。 如果工件包含其他腳本檔，你可以在工件定義檔中以名稱來引用這些檔案。

以下範例展示了 artifactfile.json 工件定義檔案的基本結構。

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

該定義包含以下必要及可選元素：

成品參數

定義檔案的 parameters 部分定義了使用者安裝工件時可指定的選項與值。 你可以在runCommand中參考這些參數。

以下結構定義了一個參數：

  "parameters": {
    "<name>": {
      "type": "<type>",
      "displayName": "<display name>",
      "description": "<description>"
    }
  }

每個參數都需要名稱，參數定義則需要以下元素：

安全字串參數

若要在工件定義中包含祕密，請使用 secureStringParam 定義檔案區段中的 parameters 語法，將祕密宣告為安全字串。 該 description 元素允許任何文字字串，包括空格，並在使用者介面中以遮罩字元呈現字串。

    "securestringParam": {
      "type": "securestring",
      "displayName": "Secure String Parameter",
      "description": "<any text string>",
      "allowEmpty": false
    },

以下 runCommand 使用 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'), '\"')]"
  }

工件表達式與函式

你可以用表達式和函式來建構 artifact 安裝指令。 運算式在成品安裝時進行評估。

表達式可以出現在 JSON 字串值的任何地方，並且總是回傳另一個 JSON 值。 用括號包住表達式。 [ ] 如果你需要用以括號開頭的字串，就用兩個括號 [[。

你通常會用帶有函數的表達式來構造一個值。 函式呼叫格式為 functionName(arg1, arg2, arg3)。

常見功能包括：

以下範例使用帶有函數的 concat 表達式來構造一個值。

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

建立自訂工件

你可以從範例 artifactfile.json 定義檔案開始建立自訂工件。 公開的 DevTest Labs 產物庫 有一個產物函式庫。 你可以下載一個工件定義檔，並自訂它來創造你自己的工件。

1. 下載 artifactfile.json 定義檔並 artifact.ps1 PowerShell 腳本。https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes

2. 編輯工件定義檔，對元素和值做一些有效的修改。 在 Visual Studio Code 中，你可以使用 IntelliSense 查看有效的元素和值選項。 例如，當你編輯targetOsType元素時，IntelliSense 會顯示Windows或Linux選項。

3. 將你的產物存放在公開或私人的 Git 產物倉庫中。

   • 將每個 artifactfile.json 工件定義檔案存放在與工件名稱相同的獨立目錄中。
   • 將安裝指令所參考的腳本存放在與工件定義檔案相同的目錄中。

   以下截圖展示了一個範例 artifact 資料夾：

   

   備註

   要將自訂產物加入公開的 DevTest Labs 產物庫，請對該倉庫開啟拉取請求。

後續步驟

• 將成品新增至 DevTest Labs VM
• 指定必須新增到所有實驗室虛擬機的工件
• 在實驗室新增一個工件資料庫

相關內容

• 在實驗室診斷工件故障
• 針對套用成品時遇到的問題進行疑難排解