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

  • [アーティクル]

WinGet 構成を作成するには:

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

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

ファイル形式

Windows パッケージ マネージャーでは、マニフェスト (YAML ファイル) を使用し、Windows ユーザー用のパッケージを検索してインストールします。 WinGet 構成ファイルでは、同じ YAML スタイル形式が使用され、ファイルの構造と検証の定義に役立つ JSON スキーマ仕様が追加されます。 WinGet 構成ファイルの形式が有効かどうかを検出をさらに支援するために、適切な構文をサポートし、書式設定エラーを検出し、ホバーサポートとオートコンプリート(JSON スキーマ ファイルにリンクされている場合)を提供し、有効な書式を確認するには、RedHat によって YAML 拡張機能を持つ Visual Studio Code を使用することをお勧めします。

ファイルの名前付け規則

WinGet 構成ファイルの名前付け規則は configuration.dsc.yaml です。 Git ベースのプロジェクトの場合、既定の構成は、./configurations/configuration.dsc.yaml の "configurations" ディレクトリに格納する必要があります。

WinGet 構成ファイルのセクション

WinGet 構成ファイルは、次の 2 つの主要なセクションに分かれています。

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

アサーション セクション

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

アサーションの例:

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

システムが目的の状態ではないことを示すためにアサーションから "false" が返された場合、dependsOn フィールドを使用してそのアサーションを依存関係として識別するリソースはすべてスキップされ、実行に失敗します。 この場合、Windows 環境に構成の変更が適用されなかった場合でも、この構成は成功した結果と見なされます。

resources セクション

リソースの一覧には、ソフトウェア、ツール、パッケージなどのインストールする必要のあるもの、および 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

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

  1. スキーマ: 後にファイルが続く DSC スキーマを確立するため、構成ファイルの最初の行には、次のコメントを含める必要があります: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/<most recent schema version #>。 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 値を使用すると、構成で PowerShell ギャラリーの "プレリリース" モジュールの使用を許可する (true) かどうかを選択できます。

  6. 設定: リソースの settings 値は、PowerShell DSC リソースに渡される名前と値のペアのコレクションを表します。 設定には、開発者モードが有効かどうか、レジストリ キーの適用、または特定のネットワーク設定の確立まで、あらゆるものを表すことができます。

  7. 依存関係: リソースの dependsOn 値は、このタスクを開始する前に他のアサーションまたはリソースを完了する必要があるかどうかを決定します。 依存関係が失敗した場合、このリソースも自動的に失敗します。

  8. ID: 特定のリソース インスタンスの一意識別子です。 id 値は、最初に適用されるこのリソースと依存関係にある別のリソースがある場合に使用できます。

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

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

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

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

変数 ${WinGetConfigRoot} の使用

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

PowerShell DSC リソース モジュールを入手できる場所

Microsoft でサポートされている、すぐに使用できる ("インボックス") PowerShell Desired State Configuration リソースの一覧を確認します。次のものが含まれます。

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

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