共用方式為

撰寫開發方塊的自定義檔案

  • 發行項

在本文中，您將瞭解如何使用 Visual Studio Code （VS Code） 和 開發人員首頁，為您的開發方塊建立及測試自定義檔案。

在開發方塊Microsoft有兩種方式可以使用自定義檔案。 當開發人員在集區上設定自定義專案時，系統會自動套用小組自定義 。 當使用者建立開發方塊時，會套用個別自定義 專案。

本文可協助您在自定義檔案中定義新工作、將它們套用至您的開發方塊，以及直接在 VS Code 中測試這些自定義。

重要

開發箱小組自定義功能目前為預覽狀態。 如需預覽狀態的詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。 本檔會定義適用於 Beta 版、預覽版或尚未發行至正式運作的 Azure 功能的法律條款。

必要條件

若要完成本文中的步驟，您必須：

設定自定義所需的許可權

若要執行建立和套用自定義至開發方塊的必要動作，您需要下列許可權：

動作 許可權/角色
啟用開發人員中心的專案層級目錄。 在訂用帳戶上具有寫入許可權的平台工程師。
啟用項目的目錄同步設定。 在訂用帳戶上具有寫入許可權的平台工程師。
將目錄附加至專案。 專案上的專案管理員或參與者許可權。
建立自定義檔案。 未指定任何專案。 任何人都可以建立自定義檔案。
使用開發人員入口網站在開發方塊建立期間上傳並套用 YAML 檔案。 開發方塊使用者。
將工作新增至目錄。 將 新增至裝載目錄之存放庫的許可權。

什麼是自定義檔案？

開發方塊自定義會使用YAML格式的檔案來指定開發人員建立開發方塊時要套用的工作清單。 這些工作可以像安裝套件一樣簡單，也可以像執行一組複雜的腳本一樣複雜，以設定程式代碼基底。 工作會識別目錄，並提供參數，例如要安裝的軟體名稱。 然後，自定義檔案可供建立開發方塊的開發人員使用。

下列範例會使用工作 winget 來安裝 VS Code，以及 git-clone 複製存放庫的工作：

# From https://github.com/microsoft/devcenter-examples
$schema: 1.0
tasks:
  - name: winget
    parameters:
      package: Microsoft.VisualStudioCode
      runAsUser: true
  - name: git-clone
    description: Clone this repository into C:\Workspaces
    parameters:
      repositoryUrl: https://github.com/OrchardCMS/OrchardCore.git
      directory: C:\Workspaces

有兩種方式可以使用自定義檔案：個別自定義會套用至單一開發方塊，而小組自定義則套用至整個小組。

個別自定義檔案

  • 包含開發人員建立開發方塊時所套用的工作。
  • 開發人員會在建立開發方塊期間上傳。

小組自定義檔案

  • 包含開發人員建立開發方塊時所套用的工作。
  • 會跨小組或項目共用。
  • 包含指定基底映像的欄位。
  • 命名為 imagedefinition.yaml。
  • 會上傳至裝載目錄的存放庫。
  • 當開發人員從設定的集區建立開發方塊時，會自動使用。

重要

映像定義只能使用 Dev Box Marketplace 映射作為基底映像。 若要取得開發人員中心可存取的映像清單，請使用此 Azure CLI 命令：

az devcenter admin image list --dev-center-name CustomizationsImagingHQ --resource-group TeamCustomizationsImagingRG --query "[].name"

建立自定義檔案

您可以使用 VS Code 來建立和管理自訂檔案。 您可以使用 VS Code 中的 Microsoft Dev Box 擴充功能來探索附加目錄中的工作，並測試自定義檔案。

  1. 建立開發方塊（或使用現有的開發方塊）進行測試。

  2. 在測試開發方塊上，安裝 VS Code，然後安裝 開發箱擴充功能。

  3. 從範例存放庫下載範例 YAML 自定義檔案，並在 VS Code 中開啟它。

  4. 使用命令選擇區探索目錄中可用的工作。 選取 [ 檢視>命令選擇區>開發方塊：列出此開發方塊可用的工作]。

    Visual Studio Code 中 Dev Box 命令選擇區的螢幕快照，其中顯示列出可用工作的命令。

  5. 使用命令選擇區測試 VS Code 中的自定義。 選取 [檢視>命令選擇區>開發方塊：套用自定義工作]。

    Visual Studio Code 中開發人員 Box 命令選擇區的螢幕快照，其中顯示用於套用自定義工作的命令。

  6. 自定義檔案會立即執行，並將指定的工作套用至您的測試開發方塊。 檢查變更，並檢查 VS Code 終端機是否有工作執行期間所產生的任何錯誤或警告。

  7. 當自訂檔案成功執行時，請將它上傳至您的目錄。

使用自定義檔案複製私人存放庫

您可以在 YAML 自定義中使用來自 Azure 金鑰保存庫的秘密來複製私人存放庫，或使用您撰寫的任何需要存取令牌的自定義工作。 在小組自定義檔案中，您可以使用儲存在密鑰保存庫中的個人存取令牌（PAT）來存取私人存放庫。

在小組自定義檔案中使用金鑰保存庫秘密

若要複製私人存放庫，請將 PAT 儲存為金鑰保存庫秘密，並在自定義中叫 git-clone 用工作時使用它。

若要設定金鑰保存庫秘密，以用於 YAML 自訂：

  1. 請確定開發人員中心專案的受控識別具有 金鑰保存庫 讀取者角色，以及密鑰保存庫中 金鑰保存庫 秘密使用者角色。
  2. 將密鑰保存庫密碼的 金鑰保存庫 秘密使用者角色授與每個使用者或使用者群組，這些使用者或使用者群組應該能夠在開發方塊自定義期間取用秘密。 獲授與角色的使用者或群組必須包含開發人員中心的受控識別、您自己的用戶帳戶，以及自定義開發方塊期間需要秘密的任何使用者或群組。

如需詳細資訊，請參閱

您可以使用下列格式來參考 YAML 自訂中的秘密，其使用工作 git-clone 做為範例：

$schema: "1.0"
tasks:
   name: git-clone
   description: Clone this repository into C:\Workspaces
      parameters:
         repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
         directory: C:\Workspaces
         pat: '{{KEY_VAULT_SECRET_URI}}'

在個別自定義檔案中使用金鑰保存庫秘密

如果您想要從個別自定義檔案複製私人 Azure Repos 存放庫，則不需要在 Azure 金鑰保存庫 中設定秘密。 相反地，您可以使用 {{ado}} 或 {{ado://your-ado-organization-name}} 作為參數。 當您建立開發方塊時，此參數會代表您擷取存取令牌。 存取令牌具有存放庫的唯讀許可權。

git-clone快速入門目錄中的工作會使用存取令牌來複製您的存放庫。 以下是範例：

tasks:
   name: git-clone
   description: Clone this repository into C:\Workspaces
      parameters:
         repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
         directory: C:\Workspaces
         pat: '{{ado://YOUR_ADO_ORG}}'

您的開發人員中心需要存取金鑰保存庫。 開發人員中心不支援服務標籤，因此如果您的金鑰保存庫保持私人，您必須允許受信任的 Microsoft 服務 略過防火牆。

顯示允許受信任 Microsoft 服務 略過 Azure 金鑰保存庫 設定中防火牆的選項螢幕快照。

若要了解如何允許受信任的 Microsoft 服務略過防火牆，請參閱設定 Azure Key Vault 網路設定。

使用現有的 WinGet 設定檔自訂您的開發箱

WinGet 組態採用組態即程式代碼方法，定義讓 Windows 環境處於現成程式代碼狀態所需的唯一軟體和組態設定。 您也可以使用這些組態檔來設定開發方塊，方法是使用隨附於Microsoft快速入門目錄中的 WinGet 工作。

下列範例顯示呼叫現有 WinGet Desired 狀態設定 （DSC） 檔案的開發方塊自定義檔案：

tasks:
    - name: winget
      parameters:
          configure: "projectConfiguration.dsc.yaml"

若要深入瞭解，請參閱 WinGet 設定。

從程式代碼存放庫共用自定義檔案

將自定義檔案命名為 imagedefinition.yaml，並將它上傳至裝載目錄的存放庫，讓您的自定義檔案可供開發方塊集區使用。 當您建立開發方塊集區時，您可以從目錄選取自定義檔案，以套用至集區中的開發方塊。

相關內容