リンク

WindowsServer 2025 総合ガイド第13回
DSC構成ファイルの作成 ― YAMLの基本とリソース定義

前回（第12回）では、DSC v3の概念と基本コマンドを学びました。dsc resourceコマンドを使って個別のリソースの状態を取得・テスト・設定する方法を実践しましたが、実際の運用では複数の設定をまとめて管理したい場面がほとんどです。そこで活躍するのが「構成ファイル（Configuration Document）」です。第13回では、構成ファイルの記述に使うYAML構文の基礎を学び、実際に構成ファイルを作成してテスト・適用する方法を身につけます。

13.1 この記事で学ぶこと
13.2 前提条件
13.3 YAML構文の基礎
13.4 DSC構成ファイルの構造
13.5 最初の構成ファイル作成
13.6 構成のテスト
13.7 構成の適用
13.8 実践例：レジストリ値の設定
13.9 実践例：環境変数の設定（アダプター経由）
1. 13.9.1 環境変数リソースの構成ファイル
2. 13.9.2 テストと適用
13.10 YAMLエディタの設定
13.11 構成ファイルのベストプラクティス
13.12 よくあるエラーと対処法
13.13 まとめ
13.14 次回予告
13.15 参考リンク

13.1 この記事で学ぶこと

YAML構文の基本ルールを理解する
DSC構成ファイルの構造（$schema、metadata、resources）を理解する
構成ファイルを作成し、dsc config testでテストできる
テスト結果を読み解き、dsc config setで安全に適用できる
レジストリ設定の構成ファイルを作成できる
Visual Studio Codeを使ったYAML編集環境を構築できる

13.2 前提条件

第12回完了（DSC v3の基本コマンドを理解していること）
DSC v3がインストールされ、dsc --versionでバージョンが確認できること
PSDesiredStateConfigurationモジュールがインストールされていること
PowerShell 7.4を管理者として起動できる状態

13.3 YAML構文の基礎

DSC v3では、構成ファイルをYAML（ヤムル）形式で記述します。まず、YAML構文の基本を押さえましょう。

13.3.1 YAMLとは

YAML（YAML Ain’t Markup Language）は、人間が読み書きしやすいように設計されたデータ形式です。設定ファイルやデータの記述に広く使われており、Ansible、Kubernetes、Docker Composeなど多くのインフラ管理ツールで採用されています。

YAMLの主な特徴は以下のとおりです。

可読性が高い：インデント（字下げ）で構造を表現するため、視覚的に理解しやすい
JSONの上位互換：正しいJSONはそのままYAMLとしても有効。ただしYAMLはJSONよりも簡潔に記述できる
広く普及：多くの構成管理ツールや CI/CD パイプラインで標準的に使用されている

なぜYAMLを学ぶのか：DSC v3はYAMLとJSON両方に対応していますが、Microsoftも公式にYAMLでの記述を推奨しています。YAMLの方がJSONよりも簡潔で読みやすく、コメントも記述できるためです。また、YAMLの知識はDSCに限らず、Ansibleやコンテナ技術など他のインフラ管理技術でも活用できます。

13.3.2 基本ルール

YAMLを書く際に必ず守るべき基本ルールがあります。

インデント（字下げ）

YAMLでは、データの階層構造をスペースによるインデントで表現します。これはYAMLで最も重要なルールです。

# 正しい例：スペースでインデント
parent:
  child1: 値1
  child2: 値2
    grandchild: 値3

インデントに関する注意点は以下のとおりです。

スペースのみ使用可能：タブ文字は使用できません。タブを使うと構文エラーになります
スペース2つが標準：1つ以上のスペースであれば何文字でも構いませんが、2つのスペースが広く使われている慣習です。DSC v3の公式サンプルでも2スペースが使用されています
同じ階層は同じインデント幅：同一階層の要素は、必ず同じ数のスペースでインデントする必要があります

# 悪い例：タブ文字を使用（エラーになる）
parent:
	child: 値  # ← タブ文字。これはエラー！

# 悪い例：同じ階層なのにインデントが揃っていない
parent:
  child1: 値1
   child2: 値2  # ← スペース3つ。child1と揃っていない

重要：YAML構文エラーの大半はインデントの問題です。「タブは使わない」「スペース2つで統一する」を徹底しましょう。テキストエディタでタブをスペースに自動変換する設定を有効にすることを強く推奨します。

コロン（`:`）によるキーと値の分離

YAMLでは、キー（名前）と値をコロンとスペースで区切ります。コロンの後にスペースを入れることが必須です。

# 正しい例：コロンの後にスペースがある
name: Web-Server
version: 1.0

# 悪い例：コロンの後にスペースがない（エラーまたは意図しない解釈になる）
name:Web-Server  # ← エラー！

大文字と小文字の区別

YAMLのキーは大文字と小文字を区別します。Nameとnameは別のキーとして扱われます。DSC構成ファイルでは、リソースのプロパティ名の大文字・小文字を正確に記述する必要があります。

# これらは全て別のキー
Name: Web-Server
name: web-server
NAME: WEB-SERVER

13.3.3 データ型

YAMLで扱える主なデータ型を確認しましょう。DSC構成ファイルで頻繁に使用するものばかりです。

データ型	記述例	説明
文字列	`name: W32Time`	引用符なしで記述可能。特殊文字を含む場合は引用符で囲む
数値	`port: 443`	整数や小数を記述可能
真偽値	`enabled: true`	`true`または`false`（小文字）
null	`value: null`	値が存在しないことを表す。`~`でも表現可能

文字列の記述方法

文字列は通常そのまま記述できますが、特殊文字を含む場合は引用符で囲みます。

# 引用符なし（通常はこれで問題ない）
name: Windows Time Service

# シングルクォート（特殊文字をそのまま扱う）
path: 'C:\Windows\System32'

# ダブルクォート（エスケープシーケンスを解釈する）
message: "行1\n行2"

# コロンを含む値は引用符で囲む
description: "設定: ファイアウォール"

Tips：DSC構成ファイルでWindowsのパスを記述する際は、バックスラッシュ（\）をそのまま記述できます。ただし、値にコロン（:）やシャープ（#）などYAMLの特殊文字を含む場合は、引用符で囲む必要があります。

13.3.4 コレクション

YAMLでは、複数のデータをまとめて扱うための構造が2種類あります。

マッピング（キー: 値のペア）

マッピングは、キーと値のペアで構成される構造です。プログラミングにおける辞書（Dictionary）やハッシュテーブルに相当します。

# マッピングの例
server:
  name: WebServer01
  os: Windows Server 2025
  memory: 2GB

リスト（配列）

リストは、複数の項目を順序付きで並べる構造です。各項目の先頭にハイフンとスペース（- ）を付けます。

# リストの例
services:
  - W32Time
  - WinRM
  - Spooler

ネストされた構造

マッピングとリストを組み合わせることで、複雑な構造を表現できます。DSC構成ファイルでは、このネスト構造を頻繁に使用します。

# リストの中にマッピングをネスト（DSC構成ファイルでよく使うパターン）
resources:
  - name: リソース1
    type: タイプ1
    properties:
      key1: value1
  - name: リソース2
    type: タイプ2
    properties:
      key2: value2

上記の例は、resourcesというリストの中に2つのマッピング（name、type、propertiesをキーとするオブジェクト）が含まれている構造です。DSC構成ファイルのresourcesセクションはまさにこの形式です。

13.3.5 コメント

YAMLでは、#（シャープ）以降がコメントとして扱われます。コメントは行の途中からでも記述できます。

# 行全体がコメント
name: W32Time  # 行の途中からコメント

# 複数行のコメントは、各行に # を付ける
# このリソースはWindows Timeサービスを管理します。
# 第5回で手動設定したサービスに対応しています。

YAMLには複数行コメント（ブロックコメント）の構文はありません。複数行にわたるコメントを書く場合は、各行の先頭に#を付けます。

13.3.6 YAML構文のまとめ

ここまで学んだYAML構文の要点をまとめます。

ルール	内容	注意点
インデント	スペースのみ（2スペース推奨）	タブ文字は絶対に使わない
キーと値	`キー: 値`（コロン+スペース）	コロンの後のスペースを忘れない
リスト	`- 項目`（ハイフン+スペース）	ハイフンの後のスペースを忘れない
大文字小文字	区別される	プロパティ名は正確に記述する
コメント	`# コメント`	行全体または行末から記述可能
文字列	通常は引用符不要	特殊文字（`:`、`#`等）を含む場合は引用符で囲む

13.4 DSC構成ファイルの構造

YAML構文の基礎を理解したところで、DSC v3の構成ファイルの構造を学びましょう。構成ファイルは「構成ドキュメント（Configuration Document）」とも呼ばれ、システムの「あるべき状態」を宣言的に記述したファイルです。

13.4.1 構成ファイルの全体構造

DSC v3の構成ファイルは、以下の3つのセクションで構成されます。

# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
metadata:
  name: 構成の名前
resources:
  - name: リソースの表示名
    type: リソースタイプ
    properties:
      プロパティ名: 値

各セクションの役割を見ていきましょう。

セクション	必須	説明
`$schema`	はい	構成ファイルが準拠するJSONスキーマのURLを指定する
`metadata`	いいえ	構成の名前や説明などのメタ情報を記述する
`resources`	はい	管理するリソースのリストを定義する

13.4.2 スキーマ定義（`$schema`）

$schemaフィールドは、構成ファイルが準拠するスキーマ（構造の定義）を指定します。DSC v3はこの値を見て、構成ファイルの検証方法を決定します。

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json

スキーマの役割は以下のとおりです。

構文の検証（バリデーション）：構成ファイルの構文が正しいかどうかを自動的にチェックする
エディタ補完：Visual Studio Codeなどのエディタで、入力候補の表示やリアルタイムのエラー検出が可能になる
バージョン管理：DSC v3のどのバージョンに対応した構成ファイルかを明示する

スキーマURLについて：本シリーズでは、DSC v3の最新スキーマURL（https://aka.ms/dsc/schemas/v3/bundled/config/document.json）を使用します。この短縮URLはMicrosoftが提供するもので、常に最新のDSC v3スキーマを参照します。Visual Studio Codeでのエディタ補完を有効にしたい場合は、ファイルの1行目に# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.jsonというコメントを追加します（後述の「YAMLエディタの設定」セクションで詳しく説明します）。

13.4.3 メタデータセクション（`metadata`）

metadataセクションは任意項目ですが、構成ファイルの目的を明確にするために記述することを推奨します。

metadata:
  name: WebServer-Basic-Configuration

metadataには任意のキーと値を自由に記述できます。たとえば、作成者や作成日、変更履歴などを記録しておくと管理に役立ちます。ただし、Microsoft.DSCプロパティ配下はDSC v3が内部的に使用するため、独自の情報はそれ以外の場所に記述してください。

metadata:
  name: WebServer-Basic-Configuration
  author: admin
  created: 2026-02-08
  description: Webサーバーの基本設定を定義する構成ファイル

13.4.4 リソースセクション（`resources`）

resourcesセクションは構成ファイルの核となる部分で、管理対象のリソースをリスト形式で定義します。各リソースは以下の要素で構成されます。

要素	必須	説明
`name`	はい	リソースの表示名。構成ファイル内で一意であること
`type`	はい	リソースタイプ。`dsc resource list`で確認できる値を指定する
`properties`	はい	リソース固有の設定プロパティ

resources:
  - name: Example registry key     # リソースの表示名（わかりやすい名前を付ける）
    type: Microsoft.Windows/Registry  # リソースタイプ（第12回で学んだもの）
    properties:                      # リソース固有の設定
      keyPath: HKCU\example\key
      _exist: true

nameには日本語も使用できますが、ログやエラーメッセージでの表示を考慮して英語で記述することを推奨します。typeは第12回のdsc resource listで確認したリソースタイプを正確に記述してください。

13.4.5 ネイティブリソースとアダプター経由のリソース

第12回で学んだとおり、DSC v3にはネイティブリソース（Microsoft.Windows/Registryなど）とアダプター経由のリソース（PSDesiredStateConfiguration/Environmentなど）があります。構成ファイルでの記述方法はそれぞれ異なります。

ネイティブリソースの記述

ネイティブリソースは、resourcesに直接記述できます。

resources:
  - name: Example registry key
    type: Microsoft.Windows/Registry
    properties:
      keyPath: HKCU\example\key
      _exist: true

アダプター経由のリソースの記述

PSDesiredStateConfigurationモジュールのリソース（Environmentなど）は、アダプターを経由して利用します。アダプターのproperties内にresourcesを入れ子にする構造になります。

resources:
  - name: PSDSC resources
    type: Microsoft.Windows/WindowsPowerShell
    properties:
      resources:
        - name: DSC_EXAMPLE env variable
          type: PSDesiredStateConfiguration/Environment
          properties:
            Name: DSC_EXAMPLE
            Ensure: Present
            Value: Set by DSC

この構造を図式化すると以下のようになります。

resources（トップレベル）
  └── アダプターリソース（Microsoft.Windows/WindowsPowerShell）
        └── properties
              └── resources（アダプター内のリソース）
                    └── PSDesiredStateConfigurationのリソース
                          └── properties（リソース固有の設定）

なぜアダプターが必要か：DSC v3はRust言語で実装されたツールですが、既存のPowerShellベースのDSCリソースを活用するために「アダプター」という仕組みを提供しています。アダプターはDSC v3とPowerShellの間を橋渡しし、PSDesiredStateConfigurationモジュールのリソース（Service、WindowsFeature、Environmentなど）をDSC v3から利用可能にします。

13.5 最初の構成ファイル作成

YAML構文と構成ファイルの構造を理解したところで、実際に構成ファイルを作成してみましょう。

13.5.1 構成ファイルの命名規則

DSC v3が構成ファイルとして認識するためには、ファイル名が以下のいずれかで終わる必要があります。

ファイル名の末尾	例
`.dsc.config.yaml`	`registry.dsc.config.yaml`
`.dsc.config.yml`	`registry.dsc.config.yml`
`.dsc.config.json`	`registry.dsc.config.json`
`.dsc.yaml`	`registry.dsc.yaml`
`.dsc.yml`	`registry.dsc.yml`
`.dsc.json`	`registry.dsc.json`

本シリーズでは、以下の命名規則を使用します。

形式：機能名.dsc.config.yaml
例：registry-example.dsc.config.yaml、env-setup.dsc.config.yaml

13.5.2 作業ディレクトリの準備

構成ファイルを管理するためのディレクトリを作成しましょう。

[実行環境: PowerShell 7.4 (管理者)]

# DSC構成ファイル用のディレクトリを作成
New-Item -Path "C:\DscConfigs" -ItemType Directory -Force

# 作成したディレクトリに移動
Set-Location -Path "C:\DscConfigs"

13.5.3 最初の構成ファイル ― レジストリキーの作成

まず、最もシンプルな構成ファイルとして、レジストリキーを作成する構成を書いてみましょう。DSC v3のネイティブリソースMicrosoft.Windows/Registryを使用するため、アダプターは不要です。

以下の内容でregistry-example.dsc.config.yamlファイルを作成してください。テキストエディタ（メモ帳やVisual Studio Code）で新規ファイルを作成し、以下の内容を入力します。

[ファイル: C:\DscConfigs\registry-example.dsc.config.yaml]

# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
# 最初のDSC構成ファイル ― レジストリキーの作成
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
metadata:
  name: Registry-Example
resources:
  # テスト用のレジストリキーを作成する
  # 手動操作の場合: New-Item -Path "HKCU:\Software\DSCExample"
  - name: Create DSCExample registry key
    type: Microsoft.Windows/Registry
    properties:
      keyPath: HKCU\Software\DSCExample
      _exist: true

PowerShellのコマンドで作成する場合は、以下のようにSet-Contentコマンドレットを使用できます。

[実行環境: PowerShell 7.4 (管理者)]

# 構成ファイルの内容を作成
$yamlContent = @"
# yaml-language-server: `$schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
# 最初のDSC構成ファイル ― レジストリキーの作成
`$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
metadata:
  name: Registry-Example
resources:
  # テスト用のレジストリキーを作成する
  # 手動操作の場合: New-Item -Path "HKCU:\Software\DSCExample"
  - name: Create DSCExample registry key
    type: Microsoft.Windows/Registry
    properties:
      keyPath: HKCU\Software\DSCExample
      _exist: true
"@

# ファイルに書き出す（BOMなしUTF-8で保存）
$yamlContent | Set-Content -Path "C:\DscConfigs\registry-example.dsc.config.yaml" -Encoding utf8NoBOM

# 作成したファイルの内容を確認
Get-Content -Path "C:\DscConfigs\registry-example.dsc.config.yaml"

注意：PowerShellのヒア文字列（@" "@）内で$記号を使用する場合は、バッククォート（`）でエスケープする必要があります。上記の例では`$schemaと記述しています。テキストエディタで直接ファイルを作成する場合は、エスケープは不要です。

13.6 構成のテスト

構成ファイルを作成したら、いきなり適用するのではなく、まずテストを実行します。これが「テストファースト」の原則です。

13.6.1 テストファーストの原則

DSC構成ファイルの運用では、以下の手順を必ず守ってください。

dsc config testでテスト ― 構成ファイルの検証と、現在の状態との差分を確認する（システムへの変更は一切なし）
テスト結果を確認 ― 意図どおりの差分が表示されているかを確認する
dsc config setで適用 ― テスト結果に問題がなければ、構成を適用する
dsc config getで確認 ― 適用後の状態を確認する

この手順は、プログラミングにおける「テスト駆動開発（TDD）」の考え方と似ています。まずテストで「何が変わるか」を確認してから実行することで、予期しない変更を防ぎます。

13.6.2 `dsc config test` の実行

作成した構成ファイルをテストしてみましょう。

[実行環境: PowerShell 7.4 (管理者)]

# 構成ファイルのテスト（変更は一切行われない）
dsc config test --file C:\DscConfigs\registry-example.dsc.config.yaml

実行結果の例（レジストリキーがまだ存在しない場合）：

metadata:
  Microsoft.DSC:
    version: 3.0.0
    operation: test
    executionType: actual
    startDatetime: 2026-02-08T10:00:00.000000000+09:00
    endDatetime: 2026-02-08T10:00:01.000000000+09:00
    duration: PT1S
    securityContext: elevated
results:
  - metadata:
      Microsoft.DSC:
        duration: PT0.2S
    name: Create DSCExample registry key
    type: Microsoft.Windows/Registry
    result:
      desiredState:
        keyPath: HKCU\Software\DSCExample
        _exist: true
      actualState:
        keyPath: HKCU\Software\DSCExample
        _exist: false
      inDesiredState: false
      differingProperties:
        - _exist
messages: []
hadErrors: false

13.6.3 テスト結果の読み方

テスト結果には重要な情報が含まれています。各フィールドの意味を理解しましょう。

メタデータ部分

フィールド	説明
`version`	DSC v3のバージョン
`operation`	実行された操作（`test`、`get`、`set`）
`securityContext`	実行時の権限レベル（`elevated`=管理者、`restricted`=一般ユーザー）
`duration`	実行にかかった時間

結果部分（`results`）

フィールド	説明
`desiredState`	構成ファイルで定義した「あるべき状態」
`actualState`	現在のシステムの状態
`inDesiredState`	最も重要な項目。`true`なら既に目標状態、`false`なら変更が必要
`differingProperties`	目標状態と異なっているプロパティの一覧

判定結果の読み方

`inDesiredState`の値	意味	次のアクション
`true`	既に目標の状態になっている	`dsc config set`を実行しても何も変更されない（冪等性）
`false`	目標の状態と異なっている。変更が必要	`differingProperties`を確認し、意図どおりか確認してから`dsc config set`を実行する

先ほどのテスト結果では、inDesiredState: falseかつdifferingPropertiesに_existが表示されています。これは「レジストリキーHKCU\Software\DSCExampleが存在しない（_exist: false）が、構成ファイルでは存在すべき（_exist: true）と定義されている」ことを意味しています。

13.6.4 `hadErrors`の確認

テスト結果の最後にあるhadErrorsフィールドも確認してください。

hadErrors: false ― エラーなし。テストが正常に完了した
hadErrors: true ― エラーが発生した。messagesフィールドにエラーの詳細が記録される

13.7 構成の適用

テスト結果を確認し、意図どおりの差分であることを確認できたら、構成を適用します。

13.7.1 `dsc config set` の実行

[実行環境: PowerShell 7.4 (管理者)]

# 構成の適用（テストで確認済みの変更を実行する）
dsc config set --file C:\DscConfigs\registry-example.dsc.config.yaml

実行結果の例：

metadata:
  Microsoft.DSC:
    version: 3.0.0
    operation: set
    executionType: actual
    startDatetime: 2026-02-08T10:01:00.000000000+09:00
    endDatetime: 2026-02-08T10:01:01.000000000+09:00
    duration: PT1S
    securityContext: elevated
results:
  - metadata:
      Microsoft.DSC:
        duration: PT0.2S
    name: Create DSCExample registry key
    type: Microsoft.Windows/Registry
    result:
      beforeState:
        keyPath: HKCU\Software\DSCExample
        _exist: false
      afterState:
        keyPath: HKCU\Software\DSCExample
        _exist: true
      changedProperties:
        - _exist
messages: []
hadErrors: false

13.7.2 適用結果の読み方

dsc config setの結果には、テスト時とは異なるフィールドが含まれます。

フィールド	説明
`beforeState`	適用前の状態
`afterState`	適用後の状態
`changedProperties`	実際に変更されたプロパティの一覧

上記の結果では、_existがfalseからtrueに変わったことがわかります。レジストリキーが正常に作成されました。

13.7.3 適用後の確認（`dsc config get`）

適用後の状態を確認するには、dsc config getを使用します。

[実行環境: PowerShell 7.4 (管理者)]

# 構成ファイルに基づいた現在の状態を取得
dsc config get --file C:\DscConfigs\registry-example.dsc.config.yaml

実行結果の例：

metadata:
  Microsoft.DSC:
    version: 3.0.0
    operation: get
    executionType: actual
    startDatetime: 2026-02-08T10:02:00.000000000+09:00
    endDatetime: 2026-02-08T10:02:01.000000000+09:00
    duration: PT1S
    securityContext: elevated
results:
  - metadata:
      Microsoft.DSC:
        duration: PT0.2S
    name: Create DSCExample registry key
    type: Microsoft.Windows/Registry
    result:
      actualState:
        keyPath: HKCU\Software\DSCExample
        _exist: true
messages: []
hadErrors: false

レジストリキーが存在している（_exist: true）ことが確認できました。

13.7.4 冪等性の確認

第12回で学んだ冪等性を構成ファイルレベルでも確認してみましょう。同じ構成ファイルで再度テストを実行します。

[実行環境: PowerShell 7.4 (管理者)]

# もう一度テストを実行（既に適用済みの構成）
dsc config test --file C:\DscConfigs\registry-example.dsc.config.yaml

実行結果の例：

metadata:
  Microsoft.DSC:
    version: 3.0.0
    operation: test
    executionType: actual
    startDatetime: 2026-02-08T10:03:00.000000000+09:00
    endDatetime: 2026-02-08T10:03:01.000000000+09:00
    duration: PT1S
    securityContext: elevated
results:
  - metadata:
      Microsoft.DSC:
        duration: PT0.1S
    name: Create DSCExample registry key
    type: Microsoft.Windows/Registry
    result:
      desiredState:
        keyPath: HKCU\Software\DSCExample
        _exist: true
      actualState:
        keyPath: HKCU\Software\DSCExample
        _exist: true
      inDesiredState: true
      differingProperties: []
messages: []
hadErrors: false

今度はinDesiredState: trueとなり、differingPropertiesが空です。既に目標の状態になっているため、dsc config setを実行しても何も変更されません。これが冪等性です。安心して繰り返し実行できるということです。

13.7.5 手動操作との対応

ここまでの一連の操作を、手動（PowerShell）での操作と対比してみましょう。

操作	手動（PowerShell）	DSC構成ファイル
状態の確認	`Test-Path "HKCU:\Software\DSCExample"`	`dsc config test --file ...`
現在の状態の取得	`Get-Item "HKCU:\Software\DSCExample"`	`dsc config get --file ...`
レジストリキーの作成	`New-Item -Path "HKCU:\Software\DSCExample"`	`dsc config set --file ...`

リンク

13.8 実践例：レジストリ値の設定

最初の例ではレジストリキーの存在確認のみでしたが、次はレジストリ値（名前と値のデータ）を含む、より実践的な構成ファイルを作成します。

13.8.1 レジストリリソースのプロパティ

Microsoft.Windows/Registryリソースで使用できる主なプロパティを確認しましょう。

プロパティ	説明	例
`keyPath`	レジストリキーのパス	`HKCU\Software\DSCExample`
`valueName`	レジストリ値の名前	`TestValue`
`valueData`	レジストリ値のデータ（型を含む）	`String: Hello DSC`
`_exist`	キーまたは値が存在すべきか	`true`（存在すべき）

valueDataのデータ型は以下の形式で指定します。

レジストリの型	YAML記述	PowerShellでの対応
REG_SZ（文字列）	`String: 値`	`-PropertyType String`
REG_DWORD（32ビット整数）	`DWord: 数値`	`-PropertyType DWord`
REG_QWORD（64ビット整数）	`QWord: 数値`	`-PropertyType QWord`
REG_EXPAND_SZ（展開文字列）	`ExpandString: 値`	`-PropertyType ExpandString`

13.8.2 レジストリ値を設定する構成ファイル

以下の構成ファイルは、レジストリキーの作成と、そのキーへの値の設定を行います。

[ファイル: C:\DscConfigs\registry-values.dsc.config.yaml]

# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
# レジストリ値の設定 ― DSC構成ファイルの実践例
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
metadata:
  name: Registry-Values-Example
resources:
  # 文字列値の設定
  # 手動操作の場合: New-ItemProperty -Path "HKCU:\Software\DSCExample" -Name "AppName" -Value "MyApplication" -PropertyType String
  - name: Set AppName registry value
    type: Microsoft.Windows/Registry
    properties:
      keyPath: HKCU\Software\DSCExample
      valueName: AppName
      valueData:
        String: MyApplication
      _exist: true

  # DWORD値の設定
  # 手動操作の場合: New-ItemProperty -Path "HKCU:\Software\DSCExample" -Name "Version" -Value 1 -PropertyType DWord
  - name: Set Version registry value
    type: Microsoft.Windows/Registry
    properties:
      keyPath: HKCU\Software\DSCExample
      valueName: Version
      valueData:
        DWord: 1
      _exist: true

  # もう一つの文字列値の設定
  # 手動操作の場合: New-ItemProperty -Path "HKCU:\Software\DSCExample" -Name "Environment" -Value "Development" -PropertyType String
  - name: Set Environment registry value
    type: Microsoft.Windows/Registry
    properties:
      keyPath: HKCU\Software\DSCExample
      valueName: Environment
      valueData:
        String: Development
      _exist: true

13.8.3 テストと適用

テストファーストの原則に従い、まずテストを実行します。

[実行環境: PowerShell 7.4 (管理者)]

# Step 1: テスト（変更なし）
dsc config test --file C:\DscConfigs\registry-values.dsc.config.yaml

実行結果の例（すべてのリソースがinDesiredState: falseの場合）：

metadata:
  Microsoft.DSC:
    version: 3.0.0
    operation: test
    executionType: actual
    startDatetime: 2026-02-08T10:10:00.000000000+09:00
    endDatetime: 2026-02-08T10:10:01.000000000+09:00
    duration: PT1S
    securityContext: elevated
results:
  - metadata:
      Microsoft.DSC:
        duration: PT0.1S
    name: Set AppName registry value
    type: Microsoft.Windows/Registry
    result:
      desiredState:
        keyPath: HKCU\Software\DSCExample
        valueName: AppName
        valueData:
          String: MyApplication
        _exist: true
      actualState:
        keyPath: HKCU\Software\DSCExample
        _exist: false
      inDesiredState: false
      differingProperties:
        - valueName
        - valueData
        - _exist
  - metadata:
      Microsoft.DSC:
        duration: PT0.1S
    name: Set Version registry value
    type: Microsoft.Windows/Registry
    result:
      desiredState:
        keyPath: HKCU\Software\DSCExample
        valueName: Version
        valueData:
          DWord: 1
        _exist: true
      actualState:
        keyPath: HKCU\Software\DSCExample
        _exist: false
      inDesiredState: false
      differingProperties:
        - valueName
        - valueData
        - _exist
  - metadata:
      Microsoft.DSC:
        duration: PT0.1S
    name: Set Environment registry value
    type: Microsoft.Windows/Registry
    result:
      desiredState:
        keyPath: HKCU\Software\DSCExample
        valueName: Environment
        valueData:
          String: Development
        _exist: true
      actualState:
        keyPath: HKCU\Software\DSCExample
        _exist: false
      inDesiredState: false
      differingProperties:
        - valueName
        - valueData
        - _exist
messages: []
hadErrors: false

3つのリソースすべてがinDesiredState: falseであることを確認できました。意図どおりの差分なので、適用に進みます。

# Step 2: 適用
dsc config set --file C:\DscConfigs\registry-values.dsc.config.yaml

# Step 3: 適用後の確認
dsc config get --file C:\DscConfigs\registry-values.dsc.config.yaml

# PowerShellでも確認（手動操作での確認方法）
Get-ItemProperty -Path "HKCU:\Software\DSCExample"

実行結果の例：

AppName     : MyApplication
Version     : 1
Environment : Development
PSPath      : Microsoft.PowerShell.Core\Registry::HKEY_CURRENT_USER\Software\DSCExample
PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_CURRENT_USER\Software
PSChildName : DSCExample
PSProvider  : Microsoft.PowerShell.Core\Registry

DSC構成ファイルで定義した3つの値（AppName、Version、Environment）がすべて正しく設定されていることが確認できます。

13.8.4 テスト用レジストリの削除

テストが完了したら、作成したテスト用のレジストリキーを削除しておきましょう。

[実行環境: PowerShell 7.4 (管理者)]

# テスト用レジストリキーを削除
Remove-Item -Path "HKCU:\Software\DSCExample" -Recurse -Force

# 削除を確認
Test-Path "HKCU:\Software\DSCExample"
# 出力例: False

13.9 実践例：環境変数の設定（アダプター経由）

次に、PSDesiredStateConfigurationモジュールのEnvironmentリソースをアダプター経由で使用する例を見てみましょう。これは第12回で学んだアダプターの仕組みを構成ファイルで実践します。

13.9.1 環境変数リソースの構成ファイル

[ファイル: C:\DscConfigs\env-setup.dsc.config.yaml]

# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
# 環境変数の設定 ― アダプター経由のリソース使用例
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
metadata:
  name: Environment-Variable-Setup
resources:
  # WindowsPowerShellアダプターを使用して環境変数を設定
  - name: Configure environment variables
    type: Microsoft.Windows/WindowsPowerShell
    properties:
      resources:
        # テスト用の環境変数を作成
        # 手動操作の場合: [System.Environment]::SetEnvironmentVariable("DSC_LEARNING", "Chapter13", "Machine")
        - name: DSC_LEARNING variable
          type: PSDesiredStateConfiguration/Environment
          properties:
            Name: DSC_LEARNING
            Ensure: Present
            Value: Chapter13

この構成ファイルの構造について補足します。

トップレベルのresourcesには、アダプター（Microsoft.Windows/WindowsPowerShell）を指定しています
アダプターのproperties.resources内に、実際に使用するPSDesiredStateConfigurationリソースを記述しています
Ensure: Presentは「存在すべき」を意味し、Ensure: Absentは「存在すべきでない（削除する）」を意味します

13.9.2 テストと適用

[実行環境: PowerShell 7.4 (管理者)]

# Step 1: テスト
dsc config test --file C:\DscConfigs\env-setup.dsc.config.yaml

実行結果の例：

metadata:
  Microsoft.DSC:
    version: 3.0.0
    operation: test
    executionType: actual
    startDatetime: 2026-02-08T10:20:00.000000000+09:00
    endDatetime: 2026-02-08T10:20:05.000000000+09:00
    duration: PT5S
    securityContext: elevated
results:
  - metadata:
      Microsoft.DSC:
        duration: PT3S
    name: Configure environment variables
    type: Microsoft.Windows/WindowsPowerShell
    result:
      desiredState:
        resources:
          - name: DSC_LEARNING variable
            type: PSDesiredStateConfiguration/Environment
            properties:
              Name: DSC_LEARNING
              Ensure: Present
              Value: Chapter13
      metadata:
        Microsoft.DSC:
          context: configuration
      actualState:
        result:
          - name: DSC_LEARNING variable
            type: PSDesiredStateConfiguration/Environment
            properties:
              InDesiredState: false
      inDesiredState: false
      differingProperties:
        - resources
messages: []
hadErrors: false

注意：アダプター経由のリソースは、ネイティブリソースに比べて実行時間が長くなる場合があります。これは、アダプターがPowerShellプロセスを起動してリソースを呼び出すためです。

# Step 2: 適用
dsc config set --file C:\DscConfigs\env-setup.dsc.config.yaml

# Step 3: PowerShellで確認
[System.Environment]::GetEnvironmentVariable("DSC_LEARNING", "Machine")
# 出力例: Chapter13

# テスト後のクリーンアップ：環境変数を削除
[System.Environment]::SetEnvironmentVariable("DSC_LEARNING", $null, "Machine")

13.10 YAMLエディタの設定

ここまではメモ帳やPowerShellでの直接作成でも対応できましたが、構成ファイルが複雑になるにつれて、専用のエディタを使うことで効率が大幅に向上します。ここでは、Visual Studio Code（VS Code）でのYAML編集環境を構築します。

13.10.1 Visual Studio Codeのインストール

Visual Studio Code（VS Code）はMicrosoftが提供する無料のコードエディタです。wingetを使ってインストールできます。

[実行環境: PowerShell 7.4 (管理者)]

# Visual Studio Codeのインストール
winget install Microsoft.VisualStudioCode --source winget

Tips：既にVS Codeがインストールされている場合は、このステップはスキップしてください。インストールの確認はcode --versionで行えます。

13.10.2 YAML拡張機能のインストール

VS CodeでYAMLファイルを効率よく編集するために、Red Hat提供の「YAML」拡張機能をインストールします。この拡張機能により、以下の機能が利用可能になります。

シンタックスハイライト：YAMLの構文が色分け表示される
入力補完：スキーマに基づいた入力候補が表示される
リアルタイムバリデーション：構文エラーをリアルタイムで検出・表示する
ホバー情報：プロパティにカーソルを合わせると説明が表示される

[実行環境: PowerShell 7.4 (一般ユーザー)]

# YAML拡張機能のインストール（コマンドラインから）
code --install-extension redhat.vscode-yaml

VS Codeの画面からインストールする場合は、左側のサイドバーで「拡張機能」アイコン（四角形のアイコン）をクリックし、検索窓に「YAML」と入力して、「YAML」（Red Hat提供）をインストールします。

13.10.3 スキーマによるエディタ補完の活用

構成ファイルの1行目に以下のコメントを追加すると、VS CodeのYAML拡張機能がDSC v3のスキーマを認識し、入力補完やバリデーションが有効になります。

# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json

この行を追加するだけで、以下の恩恵が得られます。

$schema、metadata、resourcesなどのトップレベルキーの入力候補が表示される
リソースのname、type、propertiesなどのキーが自動補完される
構文エラー（インデントの不正、必須フィールドの欠落など）が赤い波線で表示される

2つのスキーマURLの違い：ファイル内の$schemaフィールドにはhttps://aka.ms/dsc/schemas/v3/bundled/config/document.jsonを指定し、1行目のコメントには末尾が.vscode.jsonのURLを指定します。.vscode.json版はVS Code向けに最適化されたスキーマで、より詳細な入力補完情報を含んでいます。

13.10.4 VS Codeでの基本操作

DSC構成ファイルの編集でよく使うVS Codeの操作を紹介します。

[実行環境: PowerShell 7.4 (一般ユーザー)]

# VS Codeで構成ファイルのディレクトリを開く
code C:\DscConfigs

VS Code内で覚えておきたい設定と操作は以下のとおりです。

操作	方法
タブをスペースに変換	右下のステータスバーで「スペース: 2」を確認。「タブのサイズ」をクリックして「スペースによるインデント」を選択
ファイルの保存	`Ctrl + S`
統合ターミナルを開く	`Ctrl + @`（日本語キーボード）またはCtrl + `
入力候補の表示	`Ctrl + Space`

推奨設定：VS Codeの設定で「Editor: Tab Size」を2に、「Editor: Insert Spaces」をtrueに設定すると、YAMLファイルの編集が快適になります。設定はCtrl + ,で開けます。

13.11 構成ファイルのベストプラクティス

最後に、構成ファイルを作成・管理する際のベストプラクティスを学びましょう。

13.11.1 コメントによる説明の追加

構成ファイルには、以下の情報をコメントとして記載しましょう。

構成の目的：この構成ファイルが何を実現するか
各リソースの役割：なぜこのリソースが必要か
手動操作との対応：同じ設定を手動で行う場合のコマンドやGUI操作
注意事項：適用時の注意点や前提条件

# =====================================================
# Webサーバー基本設定
# 目的: IIS Webサーバーの初期設定を構成する
# 前提: Windows Server 2025 Desktop Experience
# 作成日: 2026-02-08
# 更新日: 2026-02-08
# =====================================================
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
metadata:
  name: WebServer-Basic-Configuration
resources:
  # IIS Webサーバー機能のインストール
  # GUI: サーバーマネージャー > 役割と機能の追加 > Web Server (IIS)
  # CLI: Install-WindowsFeature -Name Web-Server
  - name: Install IIS
    type: Microsoft.Windows/WindowsPowerShell
    properties:
      resources:
        - name: WebServer Feature
          type: PSDesiredStateConfiguration/WindowsFeature
          properties:
            Name: Web-Server
            Ensure: Present

13.11.2 変更履歴の管理

構成ファイルの変更履歴を管理する方法として、以下の2つを推奨します。

ファイル内のコメントによる簡易管理

小規模な運用では、ファイルの冒頭にコメントで変更履歴を記録する方法が手軽です。

# =====================================================
# 変更履歴
# 2026-02-08: 初版作成（レジストリ設定3件）
# 2026-02-10: Environment値をDevelopmentからStagingに変更
# =====================================================

Gitによるバージョン管理

本格的な運用では、Gitなどのバージョン管理システムを使用することを強く推奨します。構成ファイルの変更履歴を詳細に追跡でき、変更の差分確認やロールバック（巻き戻し）が容易になります。Gitの詳細は本シリーズの範囲外ですが、構成管理のベストプラクティスとして覚えておいてください。

13.11.3 構成ファイルの分割方針

構成ファイルは、目的や管理対象ごとに分割すると管理しやすくなります。

ファイル名	内容
`registry-security.dsc.config.yaml`	セキュリティ関連のレジストリ設定
`services-baseline.dsc.config.yaml`	基本サービスの設定
`firewall-rules.dsc.config.yaml`	ファイアウォール規則
`iis-setup.dsc.config.yaml`	IIS Webサーバーの設定

ただし、あまり細かく分割すると管理が煩雑になります。関連する設定は1つのファイルにまとめ、大きな機能単位で分割するのが良いバランスです。

13.12 よくあるエラーと対処法

YAML構文やDSC構成ファイルで頻繁に発生するエラーと、その対処法を紹介します。

エラー・症状	原因	対処法
「mapping values are not allowed here」	コロン（`:`）の後にスペースがない	すべてのキーと値の間にスペースを入れる（`key: value`）
「found a tab character that violates indentation」	インデントにタブ文字が使われている	タブをスペース（2つ）に置換する。エディタの設定を変更する
「did not find expected key」	同じ階層のインデントが揃っていない	同じ階層の要素のインデント幅を統一する
`hadErrors: true`でリソースタイプエラー	`type`に指定したリソースタイプが存在しない	`dsc resource list`でリソースタイプを確認する
アダプター経由のリソースが`hadErrors: true`	PSDesiredStateConfigurationモジュールがインストールされていない	`Install-Module PSDesiredStateConfiguration`を実行する
`securityContext: restricted`でセキュリティエラー	管理者権限なしで実行している	PowerShellを管理者として起動し直す
スキーマ検証エラー	`$schema`のURLが間違っている	正しいスキーマURL（`https://aka.ms/dsc/schemas/v3/bundled/config/document.json`）を使用する

エラーが出たら確認すべき3つのポイント

インデントの確認：タブが混入していないか、スペース数は揃っているか
コロンの後のスペース：key:valueではなくkey: valueになっているか
リソースタイプの確認：dsc resource listで正しいタイプ名を確認する

デバッグに役立つコマンドも紹介します。

[実行環境: PowerShell 7.4 (管理者)]

# 詳細なトレースログを出力する（エラーの原因を特定しやすくなる）
dsc --trace-level trace config test --file C:\DscConfigs\registry-example.dsc.config.yaml

--trace-levelオプションで出力の詳細度を変更できます。使用可能な値はerror、warn、info、debug、traceです。トラブルシューティング時はtraceを指定すると、DSC v3の内部動作を詳しく確認できます。

13.13 まとめ

第13回では、DSC構成ファイルの作成に必要なYAML構文の基礎と、構成ファイルの作成・テスト・適用の一連の流れを学びました。

YAML構文の基礎
- インデントはスペースのみ（タブ不可）。2スペースが標準
- キーと値はコロン+スペースで区切る
- リストはハイフン+スペースで記述する
- コメントは#で記述できる
DSC構成ファイルの構造
- $schema：スキーマURLを指定（必須）
- metadata：構成の名前やメタ情報（任意）
- resources：管理するリソースのリスト（必須）
テストファーストの原則
- dsc config testで差分を確認してからdsc config setで適用する
- inDesiredState: trueなら変更不要、falseなら変更が必要
- dsc config getで適用後の状態を確認する
2種類のリソース記述
- ネイティブリソース（Microsoft.Windows/Registry）：直接記述
- アダプター経由リソース（PSDesiredStateConfiguration/*）：アダプターのproperties.resources内に記述
エディタ環境
- Visual Studio Code + YAML拡張機能で効率的な編集が可能
- スキーマによる入力補完とリアルタイムバリデーションを活用する

13.14 次回予告

第14回では「サービスとファイアウォールのDSC化 ― 手動設定から自動化へ」と題して、基礎編で手動設定したサービス管理（第5回）とファイアウォール設定（第7回）をDSC構成ファイルで自動化する方法を学びます。複数のリソースを組み合わせた複合構成ファイルの作成や、リソース間の依存関係の定義方法を実践し、手動設定からDSCによる自動化へのステップアップを体験しましょう。

13.15 参考リンク

リンク

WindowsServer 2025 総合ガイド 第13回

WindowsServer 2025 総合ガイド 第13回 DSC構成ファイルの作成 ― YAMLの基本とリソース定義

13.1 この記事で学ぶこと#

13.2 前提条件#

13.3 YAML構文の基礎#

13.3.1 YAMLとは#

13.3.2 基本ルール#

インデント（字下げ）

コロン（:）によるキーと値の分離

大文字と小文字の区別

13.3.3 データ型#

文字列の記述方法

13.3.4 コレクション#

マッピング（キー: 値のペア）

リスト（配列）

ネストされた構造

13.3.5 コメント#

13.3.6 YAML構文のまとめ#

13.4 DSC構成ファイルの構造#

13.4.1 構成ファイルの全体構造#

13.4.2 スキーマ定義（$schema）#

13.4.3 メタデータセクション（metadata）#

13.4.4 リソースセクション（resources）#

13.4.5 ネイティブリソースとアダプター経由のリソース#

ネイティブリソースの記述

アダプター経由のリソースの記述

13.5 最初の構成ファイル作成#

13.5.1 構成ファイルの命名規則#

13.5.2 作業ディレクトリの準備#

13.5.3 最初の構成ファイル ― レジストリキーの作成#

13.6 構成のテスト#

13.6.1 テストファーストの原則#

13.6.2 dsc config test の実行#

13.6.3 テスト結果の読み方#

メタデータ部分

結果部分（results）

判定結果の読み方

13.6.4 hadErrorsの確認#

13.7 構成の適用#

13.7.1 dsc config set の実行#

13.7.2 適用結果の読み方#

13.7.3 適用後の確認（dsc config get）#

13.7.4 冪等性の確認#

13.7.5 手動操作との対応#

13.8 実践例：レジストリ値の設定#

13.8.1 レジストリリソースのプロパティ#

13.8.2 レジストリ値を設定する構成ファイル#

13.8.3 テストと適用#

13.8.4 テスト用レジストリの削除#

13.9 実践例：環境変数の設定（アダプター経由）#

13.9.1 環境変数リソースの構成ファイル#

13.9.2 テストと適用#

13.10 YAMLエディタの設定#

13.10.1 Visual Studio Codeのインストール#

13.10.2 YAML拡張機能のインストール#

13.10.3 スキーマによるエディタ補完の活用#

13.10.4 VS Codeでの基本操作#

13.11 構成ファイルのベストプラクティス#

13.11.1 コメントによる説明の追加#

13.11.2 変更履歴の管理#

ファイル内のコメントによる簡易管理

Gitによるバージョン管理

13.11.3 構成ファイルの分割方針#

13.12 よくあるエラーと対処法#

エラーが出たら確認すべき3つのポイント

13.13 まとめ#

13.14 次回予告#

13.15 参考リンク#

WindowsServer 2025 総合ガイド第13回

WindowsServer 2025 総合ガイド第13回
DSC構成ファイルの作成 ― YAMLの基本とリソース定義

13.1 この記事で学ぶこと

13.2 前提条件

13.3 YAML構文の基礎

13.3.1 YAMLとは

13.3.2 基本ルール

コロン（`:`）によるキーと値の分離

13.3.3 データ型

13.3.4 コレクション

13.3.5 コメント

13.3.6 YAML構文のまとめ

13.4 DSC構成ファイルの構造

13.4.1 構成ファイルの全体構造

13.4.2 スキーマ定義（`$schema`）

13.4.3 メタデータセクション（`metadata`）

13.4.4 リソースセクション（`resources`）

13.4.5 ネイティブリソースとアダプター経由のリソース

13.5 最初の構成ファイル作成

13.5.1 構成ファイルの命名規則

13.5.2 作業ディレクトリの準備

13.5.3 最初の構成ファイル ― レジストリキーの作成

13.6 構成のテスト

13.6.1 テストファーストの原則

13.6.2 `dsc config test` の実行

13.6.3 テスト結果の読み方

結果部分（`results`）

13.6.4 `hadErrors`の確認

13.7 構成の適用

13.7.1 `dsc config set` の実行

13.7.2 適用結果の読み方

13.7.3 適用後の確認（`dsc config get`）

13.7.4 冪等性の確認

13.7.5 手動操作との対応

13.8 実践例：レジストリ値の設定

13.8.1 レジストリリソースのプロパティ

13.8.2 レジストリ値を設定する構成ファイル

13.8.3 テストと適用

13.8.4 テスト用レジストリの削除

13.9 実践例：環境変数の設定（アダプター経由）

13.9.1 環境変数リソースの構成ファイル

13.9.2 テストと適用

13.10 YAMLエディタの設定

13.10.1 Visual Studio Codeのインストール

13.10.2 YAML拡張機能のインストール

13.10.3 スキーマによるエディタ補完の活用

13.10.4 VS Codeでの基本操作

13.11 構成ファイルのベストプラクティス

13.11.1 コメントによる説明の追加

13.11.2 変更履歴の管理

13.11.3 構成ファイルの分割方針

13.12 よくあるエラーと対処法

13.13 まとめ

13.14 次回予告

13.15 参考リンク