共用方式為

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

  • 發行項

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

使用自定義檔案的方式有兩種：小組自定義會在集區上自動套用一次，以及在使用者建立開發方塊時套用的個別自定義。

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

重要

開發箱小組自定義目前處於預覽狀態。 如需預覽狀態的詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。 本文件定義適用於 Azure 功能 (搶鮮版 (Beta)、預覽版，或尚未正式發行的版本) 的法律條款。

必要條件

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

設定自定義所需的許可權

若要執行建立自訂內容並套用至開發箱所需的動作，您需要特定權限。 下表描述設定自訂內容所需的動作以及權限或角色。

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

什麼是自定義檔案？

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

下列範例會使用 winget 工作來安裝 Visual Studio Code，以及用來複製存放庫的 Git 複製工作。

# 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 映射作為基底映像。 若要取得 DevCenter 可存取的映射清單，請使用下列 az cli 命令：

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

建立自定義檔案

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

  1. 建立開發箱 (或使用現有的開發箱) 以進行測試。

  2. 在測試開發方塊上，安裝 Visual Studio Code，然後安裝 Dev Box VS Code 延伸模組。

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

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

    Visual Studio Code 中 Dev Box 命令選擇區的螢幕快照，其中顯示 [開發方塊：列出此開發方塊可用的工作] 命令。

  5. 使用 f5/命令選擇區在 Visual Studio Code 中測試自定義。 從 [檢視]>[命令選擇區]，選取 [開發箱: 套用自訂工作]。

    Visual Studio Code 中 Dev Box 命令選擇區的螢幕快照，其中顯示 [開發方塊：套用自定義工作] 命令。

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

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

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

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

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

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

若要設定您的 金鑰保存庫 秘密，以用於 yaml 自定義：

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

如需詳細資訊，請參閱

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

$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 存放庫，則不需要在 金鑰保存庫 中設定秘密。 相反地，您可以使用 {{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}}'

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

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

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

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

WinGet 組態採用組態即程式代碼方法，定義讓 Windows 環境處於現成程式代碼狀態所需的唯一軟體和組態設定。 這些設定檔也可用來設定開發箱，方法是使用稍早所述 Microsoft 提供快速入門目錄中包含的 WinGet 工作。 下列範例示範開發方塊自定義檔案，該檔案會呼叫現有的 WinGet Desired 狀態設定 （DSC） 檔案。

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

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

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

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

相關內容