如何撰寫 WinGet 組態檔

發行項
03/13/2024

若要建立 WinGet 組態檔：

遵循 WinGet 組態檔案命名慣例建立 YAML 檔案。
熟悉 WinGet 組態檔的格式，並連結目前的檔案結構描述。
決定要納入檔案中的判斷提示 (所需的前置條件) 和資源 (要讓電腦的開發環境達到預期狀態所需要的安裝和設定組態清單) 的清單。
識別要完成預期組態工作所需的 PowerShell 模組和 Desired State Configuration (DSC) 資源。
決定每個組態資源所需的指示詞和設定。
決定每個資源的相依性。

File format

Windows 封裝管理員會使用資訊清單 (YAML 檔案) 來為 Windows 使用者尋找和安裝封裝。 WinGet 組態檔使用相同的 YAML 樣式格式，新增 JSON 結構描述規格以協助定義檔案的結構和驗證。為了進一步協助偵測 WinGet 設定檔案的格式是否有效，建議您搭配使用 Visual Studio Code 與 RedHat 的 YAML 延伸模組以支援適當的語法、協助偵測任何格式錯誤、提供暫留支援和自動完成 (連結至 JSON 結構描述檔案時)，以及確保格式有效。

檔案命名慣例

WinGet 組態檔的命名慣例是 configuration.dsc.yaml。針對 Git 架構的專案，預設組態應儲存在以下「configurations」目錄中：./configurations/configuration.dsc.yaml。

WinGet 組態檔的區段

WinGet 組態檔分為兩大區段：

判斷提示：要執行組態所需的前置條件。
資源：要安裝的軟體和工具清單、這些安裝的組態設定，以及 Windows 作業系統的組態設定。

判斷提示區段

判斷提示清單涵蓋要讓此 WinGet 組態檔中所列資源在執行此檔案的電腦上成功所需的前置條件 (或必要條件)。判斷提示可以平行完成，且完全不需要循序進行。

判斷提示範例：

作業系統版本：電腦上所安裝作業系統* 的最低版本。當功能隨著時間不斷新增至作業系統時，有些功能會進行反向修補以支援較舊的作業系統版本，有些功能則不會。因此，檢查最低作業系統版本以確定組態所需的特定工具或功能是否可能受到支援，這樣的做法一直很有用。例如，WinGet (Windows 封裝管理員) 至少需要 Windows 10 版本 1809 或更新版本。任何較舊版本的 Windows 都不支援 WinGet。 *PowerShell DSC 資源可以變更系統的狀態，但不適合在開放原始碼專案的專案組態中呼叫 Windows Update 和修改作業系統版本。

如果判斷提示傳回「false」以表示系統未處於預期狀態，則系統會略過任何使用 dependsOn 欄位將判斷提示識別為相依性的資源，且這些資源無法執行。在此情況下，即使未對 Windows 環境套用任何組態變更，此組態仍會被視為是成功的結果。

資源區段

[資源] 清單涵蓋了需要安裝的所有軟體、工具、套件等，以及 Windows 作業系統或已安裝應用程式的組態設定。需要為每個資源提供名稱、要執行的指令的說明、負責執行該指令的 PowerShell 模組，以及任何關聯的設定或相依性。

WinGet 組態檔範例

以下是 WinGet 組態 configuration.dsc.yaml 格式化檔案範例：

# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2
properties:
  assertions:
    - resource: Microsoft.Windows.Developer/OsVersion
      directives:
        description: Verify min OS version requirement
        allowPrerelease: true
      settings:
        MinVersion: '10.0.22000'
  resources:
    - resource: Microsoft.Windows.Developer/DeveloperMode
      directives:
        description: Enable Developer Mode
        allowPrerelease: true
      settings:
        Ensure: Present
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: vsPackage
      directives:
        description: Install Visual Studio 2022 Community
        allowPrerelease: true
      settings:
        id: Microsoft.VisualStudio.2022.Community
        source: winget
    - resource: Microsoft.VisualStudio.DSC/VSComponents
      dependsOn:
        - vsPackage
      directives:
        description: Install required VS workloads from vsconfig file
        allowPrerelease: true
      settings:
        productId: Microsoft.VisualStudio.Product.Community
        channelId: VisualStudio.17.Release
        vsConfigFile: '${WinGetConfigRoot}\..\.vsconfig'
        includeRecommended: true
  configurationVersion: 0.2.0

此檔案的元件包含：

結構描述：組態檔中的第一行應該包含下列註解：# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/<most recent schema version #>，以建立此檔案所遵循的 DSC 結構描述。若要尋找最新版的 WinGet 組態結構描述，請移至 https://aka.ms/configuration-dsc-schema/。此範例推出時，最新的結構描述編號是 0.2，因此所輸入的結構描述是：# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2。
屬性：組態檔的根節點是properties，必須包含設定版本 configurationVersion: 0.2.0 (在此範例中)。請根據組態檔的更新來更新這個版本。屬性節點應包含一個 assertions 節點和一個 resources 節點。
判斷提示：在本區段中列出此組態所需的前置條件 (或必要條件)。
資源：assertions 清單部分和 resources 清單部分都由表示設定任務的單個 resource 節點組成。您應該為 resource 提供 PowerShell 模組的名稱加上為了套用預期狀態而會叫用的模組 DSC 資源的名稱：{ModuleName}/{DscResource}。每個資源都必須包含 directives 和 settings。或者，它也可以包含 id 值。在套用組態時，WinGet 會知道要安裝 PowerShell 資源庫中的模組，並叫用指定的 DSC 資源。
指示詞：directives 區段會提供模組和資源的相關資訊。本區段應包含 description 值，以描述模組會完成的組態工作。 allowPrerelease 值可讓您選擇是否允許 (true) 使用 PowerShell 資源庫中的「發行前版本」模組。
設定：資源的 settings 值代表會傳遞至 PowerShell DSC 資源的名稱/值組集合。設定可以代表任何事情，例如是否啟用開發人員模式、套用 reg 機碼，或建立特定網路設定。
相依性：資源的 dependsOn 值會決定在開始這項工作之前，是否必須先完成任何其他判斷提示或資源。如果相依性失敗，此資源也會自動失敗。
識別碼：特定資源執行個體的唯一識別碼。如果另一個資源依賴於首先應用的此資源，則可以使用 id 值。

組織資源區段

在決定如何組織 WinGet 組態檔的資源區段時，有多個可以考慮使用的方法。您可以依下列方式組織檔案清單：

執行順序：根據執行資源時應採用的邏輯順序來組織資源清單。此方法可協助使用者了解並遵循檔案執行後所會執行的自動化步驟，先安裝什麼項目、其次安裝什麼項目、第三要更新什麼設定等等。
失敗可能性：根據潛在失敗的可能性來組織資源清單可協助使用者在組態程序早期發現問題，並協助他們了解剩餘步驟可能會失敗的原因，讓他們在投入大量時間之前就先找出並進行必要變更。
將類似的資源類型組成群組：將類似的資源類型組成群組以組織資源清單是軟體工程方法論中的常見方法，對您或其他使用您組態檔的開發人員來說，這可能也是最熟悉的方法。

建議您將 README.md 檔案與任何包含檔案結構組織方法的開放原始碼已發佈 WinGet 組態檔一起納入。

使用變數 ${WinGetConfigRoot}

某些 DSC 資源可能會採用指定檔案路徑的參數。您不必指定完整路徑，而是可以使用變數 ${WinGetConfigRoot} 來定義會在其中執行 winget configure 命令的工作目錄，並附加指向該檔案的相對路徑。這很適合用於將組態檔一般化，使其不受電腦限制。上述範例中的 Microsoft.VisualStudio.DSC/VSComponents 資源會利用 ${WinGetConfigRoot} 指向專案根目錄中的 .vsconfig 檔案，以展示這項功能。這也表示使用者在執行 winget configure命令之前，應該先確定目標檔案存在於以目前工作目錄為基礎的相對路徑上。

哪裡可以找到 PowerShell DSC 資源模組

請查看 Microsoft 所支援的現成可用 (「隨附」) PowerShell Desired State Configuration 資源清單，包括：

環境：管理電腦或處理序的環境變數。
MsiPackage：安裝或解除安裝 MSI 封裝。
登錄：管理登錄機碼或值。
指令碼：執行 PowerShell 指令碼區塊。
服務：管理 Windows 服務。
WindowsFeature：安裝或解除安裝 Windows 角色或功能。
WindowsProcess：啟動或停止 Windows 處理序。

您也可以在 PowerShell 資源庫中尋找 PowerShell DSC 資源模組。此資源庫裝載了使用者社群所提交的數百個包含 Desired State Configuration (DSC) 資源的 PowerShell 模組。您可以在「類別」底下套用「DSC 資源」篩選條件，以篩選搜尋結果。此存放庫「未」經 Microsoft 驗證，其中所含的資源來自各式各樣的作者和發行者。請一律先檢閱 PowerShell 模組是否安全可信，再納入作為任意指令碼。如需更多有關建立可信任 WinGet 組態檔的提示，請參閱如何檢查 WinGet 組態檔是否值得信賴。

共用方式為