WinGet 構成ファイルを作成する方法

2025-06-11

WinGet 構成ファイルを作成するには:

WinGet 構成ファイルの名前付け規則に従って YAML ファイルを作成します。
WinGet 構成ファイルの形式を理解し、現在のファイルスキーマをリンクします。
ファイルに含めるアサーション (必須の前提条件) とリソース (マシンの開発環境を目的の状態にするための必要なインストールと設定の構成の一覧) の一覧を決定します。
目的の構成タスクを実行するために必要な PowerShell モジュールと Desired State Configuration (DSC) リソースを特定します。
各構成リソースに必要なディレクティブと設定を決定します。
各リソースの依存関係を決定します。

WinGet 構成コマンドの使用の詳細について説明します。

ファイル形式

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 構成ファイルは、次の 2 つの主要なセクションに分かれています。

アサーション: 構成を実行するために必要な前提条件。
リソース: インストールするソフトウェアとツールの一覧、それらのインストールの構成設定、および Windows オペレーティングシステムの構成設定。

Assertions セクション

アサーションの一覧には、この WinGet 構成ファイルに記載されているリソースがファイルを実行しているコンピューターで成功するために必要な前提条件 (または前提条件) が記載されています。アサーションは並列で完了でき、順番を必要としません。

アサーションの例:

OS バージョン: コンピューターにインストールされているオペレーティングシステムの最小バージョン* です。 OS に時間の経過と同時に機能が追加されるため、以前のバージョンをサポートするためにバックポートされる機能もあれば、サポートされていないものもあります。 OS の最小バージョンを確認して、構成に必要な特定のツールまたは機能がサポートされているかどうかを判断すると、常に役立ちます。たとえば、WinGet (Windows パッケージマネージャー) には、Windows 10 バージョン 1809 以降以上が必要です。以前のバージョンの Windows では、WinGet はサポートされていません。 * PowerShell DSC リソースでシステムの状態を変更することはできますが、Windows Update を呼び出して、オープンソースプロジェクトのプロジェクト構成で OS バージョンを変更することは適切ではありません。

アサーションが "false" を返してシステムが目的の状態にないことを示す場合、フィールドを使用してアサーションを依存関係として識別、リソースはスキップされ、実行に失敗します。この場合、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

このファイルのコンポーネントは次で構成されます。

スキーマ: 構成ファイルの最初の行には、次のコメントを含める必要があります。# 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からの "プレリリース" モジュールの使用を構成で許可 () するかどうかを選択できます。一部の DSC リソースは、管理者特権で実行する必要があります。リソースのディレクティブセクションの securityContext: elevated フィールドは、この要件を示します。 elevatedに設定すると、WinGet は構成の開始時に 1 つの UAC 承認を求められます。その後、WinGet は、昇格された特権でリソースを実行するプロセスと、現在のユーザーの特権でリソースを実行するプロセスの 2 つのプロセスを起動します。
設定: リソースの settings 値は、PowerShell DSC リソースに渡される名前と値のペアのコレクションを表します。設定は、開発者モードが有効かどうか、reg キーの適用、または特定のネットワーク設定の確立まで、あらゆるものを表します。
依存関係: リソースの dependsOn 値は、このタスクを開始する前に他のアサーションまたはリソースを完了する必要があるかどうかを決定します。依存関係が失敗した場合、このリソースも自動的に失敗します。
ID: リソースインスタンスの一意の識別子。 id値は、別のリソースがこのリソースに最初に適用されている依存関係を持っている場合に使用できます。

[リソース] セクションの整理

WinGet 構成ファイルの [リソース] セクションを整理する方法を決定する際には、複数の方法を考慮する必要があります。次の方法でファイルの一覧を整理できます。

実行順序: リソースを実行する論理的な順序に従ってリソースの一覧を整理します。この方法は、ファイルの実行後に実行される自動化手順 (最初にインストールされるもの、2 番目にインストールされるもの、3 番目に更新される設定など) をユーザーが理解し、それに従うのに役立ちます。
失敗の可能性: 潜在的な障害の可能性に応じてリソースの一覧を整理すると、ユーザーが構成プロセスの早い段階で問題をキャッチし、残りの手順が失敗する可能性がある理由を理解するのに役立ち、多くの時間が費やされる前に必要な変更を特定して行うことができます。
類似するリソースの種類をグループ化する: 類似のリソースの種類をグループ化してリソースの一覧を整理することは、ソフトウェアエンジニアリング手法の一般的なアプローチであり、構成ファイルを使用する他の開発者にとって最も使い慣れている可能性があります。

ファイル構造の組織のアプローチを含む、オープンソースで発行された WinGet 構成ファイルを含む README.md ファイルを含することをお勧めします。

変数 ${WinGetConfigRoot} の使用

特定の DSC リソースは、ファイルのパスを指定するパラメーターを受け取ることができます。完全パスを指定する代わりに、変数${WinGetConfigRoot}を使用して、winget configure コマンドを実行する作業ディレクトリを定義し、そのファイルを指す相対パスを追加できます。これは、コンピューターに依存しないように構成ファイルを一般化する場合に便利です。上記の例の Microsoft.VisualStudio.DSC/VSComponents リソースでは、 ${WinGetConfigRoot} を使用してプロジェクトのルートディレクトリ内の .vsconfig ファイルを指すことで、この機能を紹介しています。つまり、ユーザーは、 winget configure コマンドを実行する前に、現在の作業ディレクトリに基づく相対パスにターゲットファイルが存在することを確認する必要があります。

PowerShell DSC リソースモジュールの場所

次に示す Microsoft でサポートされている、("受信トレイ") のすぐに利用可能な PowerShell Desired State Configuration Resources の一覧を確認してください。

環境: マシンまたはプロセスの環境変数を管理します。
MsiPackage: MSI パッケージをインストールまたはアンインストールします。
レジストリ: レジストリキーまたは値を管理します。
スクリプト: PowerShell スクリプトブロックを実行します。
サービス: Windows サービスを管理します。
WindowsFeature: Windows の役割または機能をインストールまたはアンインストールします。
WindowsProcess: Windows プロセスを開始または停止します。

PowerShell DSC リソースモジュールは、 PowerShell ギャラリーでも確認できます。このギャラリーは、ユーザーコミュニティによって送信された Desired State Configuration (DSC) リソースを含む数百の PowerShell モジュールをホストします。 [カテゴリ] の下にある [DSC リソース] フィルターを適用して、検索結果をフィルター処理できます。このリポジトリは Microsoft によって検証 されておらず 、さまざまな作成者や発行元のリソースが含まれています。任意のスクリプトを含めることができるため、PowerShell モジュールを使用する前に、セキュリティと信頼性を常に確認する必要があります。信頼できる WinGet 構成ファイルの作成に関するその他のヒントについては、WinGet 構成ファイルの信頼性を確認する方法を参照してください。