共用方式為

如何撰寫 WinGet 組態檔

若要建立 WinGet 組態檔：

  1. 依循 WinGet 組態 檔案命名慣例，建立 YAML 檔案。
  2. 熟悉 WinGet 組態檔 的 格式，並連結目前 檔案架構。
  3. 判斷 斷言清單（必要先決條件）和 資源（必要的安裝和設定配置清單，以將電腦的開發環境設為所需的狀態），以包含在檔案中。
  4. 識別完成所需設定工作所需的 PowerShell 模組和預期狀態設定 （DSC） 資源。
  5. 判斷每個組態資源所需的指令和設定。
  6. 判斷每個資源的相依性。

深入瞭解如何使用 WinGet configure 命令。

檔案格式

Windows 套件管理員會使用指令清單 （YAML 檔案） 來尋找及安裝適用於 Windows 使用者的套件。 WinGet 組態檔使用相同的 YAML 樣式格式，新增 JSON 架構規格以協助定義檔案的結構和驗證。 為了進一步協助偵測 WinGet 組態檔的格式是否有效，我們建議使用 Visual Studio Code 搭配 RedHat 的 YAML 擴充功能 來支援適當的語法、協助偵測任何格式錯誤、提供暫留支援和自動完成（連結至 JSON 架構檔案時），並確保有效的格式設定。

檔案命名慣例

命名 WinGet 組態檔的慣例是使用 「.winget」 擴展名 （例如 configuration.winget）。 針對 Git 型項目，預設組態應該儲存在位於 的 「.config」 目錄中： ./config/configuration.winget。 在某些情況下，可能會根據不同的工具鏈或用戶喜好設定，適當地使用多個組態檔。 這些額外的組態檔也應該位於 「.config」 目錄中。

WinGet 組態檔的區段

WinGet 組態檔分成兩個主要區段：

  1. 斷言：執行組態所需滿足的前提條件。
  2. 資源：要安裝的軟體和工具清單、這些安裝的組態設定，以及 Windows作系統的組態設定。

斷言區段

斷言清單涵蓋此 WinGet 組態檔中所列資源在執行檔案的計算機上成功運作所需的前置條件（或必要條件）。 斷言可以並行完成，而且不需要按順序進行。

範例陳述：

  • 作系統版本：電腦上安裝的最低作系統版本* 。 隨著功能隨時間新增至作業系統，有些功能會被移植以支援舊版本，而有些則不會。 檢查最低作業系統版本是否符合要求永遠是有幫助的，以確定特定工具或功能是否受支持，這對配置是必需的。 例如，WinGet （Windows 套件管理員） 至少需要 Windows 10 版本 1809 或更新版本。 任何舊版的 Windows 都不支援 WinGet。 * PowerShell DSC 資源可以變更系統的狀態，但不適合在開放原始碼專案的項目組態中呼叫 Windows Update 和修改 OS 版本。

如果斷言返回「false」，表示系統未處於預期狀態，則會略過任何使用 欄位識別該斷言為相依性的 dependsOn，並且無法執行。 在此情況下，即使未對 Windows 環境套用任何設定變更，此設定仍會被視為成功的結果。

資源部分

資源清單涵蓋需要安裝的所有軟體、工具、套件等，以及 Windows作系統或已安裝應用程式的組態設定。 每個資源都必須指定名稱、要執行的指示詞描述，以及負責執行該指示詞的 PowerShell 模組，以及任何相關聯的設定或相依性。

範例 WinGet 組態檔

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

# 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.Settings/WindowsSettings
      directives:
        description: Enable Developer Mode
        allowPrerelease: true
        securityContext: elevated
      settings:
        DeveloperMode: true
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: vsPackage
      directives:
        description: Install Visual Studio 2022 Community
        securityContext: elevated
      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
        securityContext: elevated
      settings:
        productId: Microsoft.VisualStudio.Product.Community
        channelId: VisualStudio.17.Release
        vsConfigFile: '${WinGetConfigRoot}\..\.vsconfig'
        includeRecommended: true
  configurationVersion: 0.2.0

此檔案的元件包含：

  1. 架構：組態檔中的第一行應該包含下列批注：# 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。

  2. 屬性：組態檔的根節點必須 properties 包含組態版本（configurationVersion: 0.2.0 在此範例中）。 此版本應根據組態檔的更新進行更新。 屬性節點應該包含 assertions 節點和 resources 節點。

  3. 判斷提示：列出本節中此組態所需的先決條件（或必要條件）。

  4. 資源： assertions 和 resources 清單區段都包含代表設定工作的個別 resource 節點。 resource 應指定 PowerShell 模組的名稱，然後接著指定將用於達成所需狀態的模組 DSC 資源名稱：{ModuleName}/{DscResource}。 每個資源都必須包含 directives 和 settings。 或者，它也可以包含值 id 。 套用設定時，WinGet 會知道從 PowerShell 資源庫安裝模組， 並叫用指定的 DSC 資源。

  5. 指令：[directives] 區段提供有關模組和資源的相關資訊。 本節應包含值 description ，以描述模組所完成的設定工作。 allowPrerelease 值可讓您選擇是否允許使用來自 true的「發行前版本」模組（）。 某些 DSC 資源可能需要以系統管理員許可權執行。 資源的指令區段下的securityContext: elevated欄位表示這項需求。 當設定為 elevated時，WinGet 會在組態開始時提示一個 UAC 核准。 WinGet 接著會啟動兩個程式：一個執行具有較高許可權的資源，另一個會以目前使用者的許可權執行資源。

  6. 設定：資源的 settings 值代表要傳遞至 PowerShell DSC 資源的名稱/值組集合。 設定可能代表的選項包括是否啟用開發人員模式、套用註冊表機碼，或建立特定的網路設定。

  7. 相依需求：資源的 dependsOn 值決定在開始此任務之前，是否需要完成任何其他斷言或資源。 如果相依性失敗，此資源也會自動失敗。

  8. 標識碼：特定資源實例的唯一標識符。 如果另一個資源需要優先套用這個資源，則可以使用id值。

整理資源部分

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

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

我們建議將 README.md 檔案納入任何開放原始碼已發佈的 WinGet 組態檔，其中包含檔案結構的組織方法。

使用變數 ${WinGetConfigRoot}

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

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

請參閱Microsoft支援的PowerShell預期狀態設定 資源 立即使用 （“收件匣”） 清單，包括：

  • 環境：管理機器或進程的環境變數。
  • MsiPackage：安裝或卸載 MSI 套件。
  • 登錄：管理登錄機碼或值。
  • 腳本：執行 PowerShell 腳本區塊。
  • 服務：管理 Windows 服務。
  • WindowsFeature：安裝或卸載 Windows 角色或功能。
  • WindowsProcess：啟動或停止 Windows 進程。

您也可以在 PowerShell Gallery找到 PowerShell DSC 資源模組。 此展示廳主辦數百個由使用者社群提交，內含理想狀態配置（DSC）資源的 PowerShell 模組。 您可以在 [類別] 底下套用 「DSC 資源」 篩選條件，以篩選搜尋結果。 此存放庫 Microsoft未 驗證，且包含來自各種作者和發行者的資源。 PowerShell 模組在使用前應一律檢查其安全性及可靠性，因為其中可能包含任意的腳本。 如需建立可信任 的 WinGet 組態檔的詳細資訊，請參閱如何檢查 WinGet 組態檔的可信度 。

  • Last updated on