宣言された構成の拡張性

[アーティクル]
10/15/2024
適用対象:

✅ Windows 11, ✅ Windows 10

Windows 宣言構成 (WinDC) の登録では、ネイティブ WMI プロバイダーを使用した拡張性が提供されます。この機能は、管理インフラストラクチャ (MI) インターフェイスを実装する Windows Management Instrumentation (WMI) プロバイダーとインスタンス化およびインターフェイスします。インターフェイスは、GetTargetResource、TestTargetResource、および SetTargetResource メソッドを実装する必要があり、任意の数の文字列プロパティを実装できます。

注

現在、拡張プロバイダーでは、文字列プロパティのみがサポートされています。

[static, Description ("Get resource state based on input configuration file." )]
uint32 GetTargetResource(
    [in, EmbeddedInstance ("MSFT_FileDirectoryConfiguration"), Description ("Configuration document that is to be applied.")]
    string InputResource,
    [in, Description ("Flags passed to the provider. Reserved for future use." )]
    uint32 Flags,
    [out, EmbeddedInstance ("MSFT_FileDirectoryConfiguration"), Description ("The current state of the specified configuration resources." )]
    string OutputResource
);

[static, Description ("Test resource state based on input configuration file." )]
uint32 TestTargetResource(
    [in, EmbeddedInstance("MSFT_FileDirectoryConfiguration"), Description ("Configuration document to be applied." )]
    string InputResource,
    [in, Description ("Flags passed to the provider. reserved for future use." )]
    uint32 Flags,
    [out, Description ("True if identical. False otherwise." )]
    boolean Result,
    [out, Description ("Context information the provider can use to optimize the set. This is optional." )]
    uint64 ProviderContext
);

[static, Description ("Set resource state based on input configuration file." )]
uint32 SetTargetResource(
    [in, EmbeddedInstance ("MSFT_FileDirectoryConfiguration"),
    Description ("Configuration document to be applied." )]
    string InputResource,
    [in, Description ("Context information the provider can use to optimize the set from SetTargetResource. This is optional." )]
    uint64 ProviderContext,
    [in, Description ("Flags passed to the provider. reserved for future use." )]
    uint32 Flags
);

目的の状態構成リソースを作成する

ネイティブ WMI プロバイダーを作成するには、「 MI プロバイダーを実装する方法」で説明されている手順に従います。これらの手順には、ツールを使用して MI インターフェイスのソースコードを生成して DLL を生成し、配置用に準備する方法が含まれます。

パラメーターとメソッドを含む目的の状態構成リソースのスキーマを定義するマネージドオブジェクト形式 (MOF) ファイルを作成します。このファイルには、リソースに必要なパラメーターが含まれています。
必要なファイルと共にスキーマ MOF ファイルをプロバイダーツールディレクトリ (ProviderGenerationTool など) にコピーします。
必要なファイルを編集し、正しいファイル名とクラス名を含めます。
プロバイダージェネレーターツールを呼び出して、プロバイダーのプロジェクトファイルを生成します。
生成されたファイルをプロバイダーのプロジェクトフォルダーにコピーします。
開発プロセスを開始します。

MI プロバイダーの例

この例では、 MSFT_FileDirectoryConfiguration という名前のサンプルネイティブリソースを実装する方法を示す各手順の詳細を示します。

手順 1: リソーススキーマ MOF ファイルを作成する

MSFT_FileDirectoryConfiguration ネイティブリソースの初期ソースコードを生成するために使用するサンプルスキーマ MOF ファイルを作成します。 MSFT_FileDirectoryConfiguration という名前のプロジェクトディレクトリに配置します。

#pragma include ("cim_schema_2.26.0.mof")
#pragma include ("OMI_BaseResource.mof")
#pragma include ("MSFT_Credential.mof")

[ClassVersion("1.0.0"), Description("The configuration provider for files and directories.")]
class MSFT_FileDirectoryConfiguration : OMI_BaseResource
{
    [Key, Description("File name and path on target node to copy or create.")]
    string DestinationPath;

    [Write, Description("The name and path of the file to copy from.")]
    string SourcePath;

    [Write, Description("Contains a string that represents the contents of the file. To create an empty file, the string must be empty. The contents will be written and compared using UTF-8 character encoding.")]
    string Contents;

    [static, Description ("Get resource states based on input configuration file." )]
    uint32 GetTargetResource(
        [in, EmbeddedInstance ("MSFT_FileDirectoryConfiguration"), Description ("Configuration document that is to be applied." )]
        string InputResource,

        [in,Description ("Flags passed to the providers. Reserved for future use." )]
        uint32 Flags,

        [out, EmbeddedInstance ("MSFT_FileDirectoryConfiguration"), Description ("The current state of the specified configuration resources." )]
        string OutputResource
    );

    [static, Description ("Test resource states based on input configuration file." )]
    uint32 TestTargetResource(
        [in, EmbeddedInstance("MSFT_FileDirectoryConfiguration"), Description ("Configuration document that to be applied." )]
        string InputResource,

        [in, Description ("Flags passed to the providers. reserved for future use." )]
        uint32 Flags,

        [out, Description ("True if identical. False otherwise." )]
        boolean Result,

        [out, Description ("Context information that the provider can use to optimize the set, This is optional." )]
        uint64 ProviderContext
    );

    [static, Description ("Set resource states based on input configuration file." )]
    uint32 SetTargetResource(
        [in, EmbeddedInstance ("MSFT_FileDirectoryConfiguration"), Description ("Configuration document that to be applied." )]
        string InputResource,

        [in, Description ("Context information that the provider can use to optimize the set from TestTargetResource, This is optional." )]
        uint64 ProviderContext,

        [in, Description ("Flags passed to the providers. reserved for future use." )]
        uint32 Flags
    );
};

注

クラス名と DLL ファイル名は、 Provider.DEF ファイルで定義されているのと同じにする必要があります。
プロパティに [Key] 型修飾子は、リソースインスタンスを一意に識別することを示します。少なくとも 1 つの [Key] プロパティが必要です。
[Required]修飾子は、プロパティが必要であることを示します。つまり、このリソースを使用する構成スクリプトで値を指定する必要があります。
[write]修飾子は、構成スクリプトでカスタムリソースを使用する場合、プロパティが省略可能であることを示します。 [read]修飾子は、プロパティを構成で設定できないことを示し、レポートのみを目的としています。
[Values]修飾子は、プロパティに割り当てることができる値を制限します。 [ValueMap]で許可される値の一覧を定義します。詳細については、「 ValueMap と値修飾子」を参照してください。

新しい MOF ファイルの先頭に次の行を含める必要があります。

#pragma include ("cim_schema_2.26.0.mof")
#pragma include ("OMI_BaseResource.mof")
#pragma include ("MSFT_Credential.mof")

メソッド名とそのパラメーターは、すべてのリソースで同じである必要があります。 MSFT_FileDirectoryConfigurationを EmbeddedInstance 値から目的のプロバイダーのクラス名に変更します。 MOF ファイルごとに 1 つのプロバイダーのみが存在する必要があります。

手順 2: スキーマ MOF ファイルをコピーする

次の必要なファイルとフォルダーを、手順 1 で作成したプロジェクトディレクトリにコピーします。

CIM-2.26.0
codegen.cmd
Convert-MofToProvider.exe
MSFT_Credential.mof
MSFT_DSCResource.mof
OMI_BaseResource.mof
OMI_Errors.mof
Provider.DEF
wmicodegen.dll

必要なファイルを取得する方法の詳細については、「 MI プロバイダーを実装する方法」を参照してください。

手順 3: 必要なファイルを編集する

プロジェクトディレクトリ内の次のファイルを変更します。

MSFT_FileDirectoryConfiguration.mof: 手順 1 でこのファイルを作成しました。
Provider.DEF: このファイルには、DLL 名 (たとえば、 MSFT_FileDirectoryConfiguration.dll) が含まれています。

codegen.cmd: このファイルには、 convert-moftoprovider.exeを呼び出すコマンドが含まれています。

"convert-moftoprovider.exe" ^
   -MofFile MSFT_FileDirectoryConfiguration.mof ^
            MSFT_DSCResource.mof ^
            OMI_Errors.mof ^
   -ClassList MSFT_FileDirectoryConfiguration ^
   -IncludePath CIM-2.26.0 ^
   -ExtraClass OMI_Error ^
               MSFT_DSCResource ^
   -OutPath temp

手順 4: プロバイダージェネレーターツールを実行する

convert-moftoprovider.exe コマンドを実行するcodegen.cmdを実行します。または、コマンドを直接実行することもできます。

手順 5: 生成されたソースファイルをコピーする

手順 3 のコマンドは、 -OutPath パラメーターを指定します。この例では、 temp という名前のフォルダーです。手順 4 でツールを実行すると、このフォルダーに新しいファイルが作成されます。生成されたファイルをこの temp フォルダーからプロジェクトディレクトリにコピーします。手順 1 でプロジェクトディレクトリを作成しました。この例では MSFT_FileDirectoryConfiguration。

注

スキーマ MOF ファイルを更新するたびに、 codegen.cmd スクリプトを実行してソースファイルを再生成します。ジェネレーターツールを再実行すると、既存のソースファイルが上書きされます。この動作を防ぐために、この例では一時フォルダーを使用します。メイン実装を最新の自動生成されたソースファイルとマージする必要があるため、スキーマ MOF ファイルの更新を最小限に抑えます。

`MSFT_FileDirectoryConfiguration` リソースについて

プロバイダージェネレーターツールを実行すると、いくつかのソースファイルとヘッダーファイルが作成されます。

MSFT_FileDirectoryConfiguration.c
MSFT_FileDirectoryConfiguration.h
module.c
schema.c
WMIAdapter.c

この一覧では、 MSFT_FileDirectoryConfiguration.c と MSFT_FileDirectoryConfiguration.hのみを変更する必要があります。ソースファイルの拡張機能を .c から .cpp に変更することもできます。これは、このリソースの場合です。このリソースのビジネスロジックは、 MSFT_FileDirectoryConfigurationImp.cpp と MSFT_FileDirectoryConfigurationImp.hに実装されます。これらの新しいファイルは、プロバイダージェネレーターツールを実行した後、 MSFT_FileDirectoryConfiguration プロジェクトディレクトリに追加されます。

ネイティブの目的の状態構成リソースの場合は、 MSFT_FileDirectoryConfiguration.cppで 3 つの自動生成された関数を実装する必要があります。

MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource
MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource
MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource

これら 3 つの関数から、Get シナリオには MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource のみが必要です。 MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource と MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource は、修復が必要な場合に使用されます。

MSFT_FileDirectoryConfiguration.cppには、ネイティブの目的の状態構成リソースの実装を必要としない、他のいくつかの自動生成された関数があります。次の関数を変更する必要はありません。

MSFT_FileDirectoryConfiguration_Load
MSFT_FileDirectoryConfiguration_Unload
MSFT_FileDirectoryConfiguration_EnumerateInstances
MSFT_FileDirectoryConfiguration_GetInstance
MSFT_FileDirectoryConfiguration_CreateInstance
MSFT_FileDirectoryConfiguration_ModifyInstance
MSFT_FileDirectoryConfiguration_DeleteInstance

に関しては `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`

MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource関数は、タスクを完了するために次の手順を実行します。

入力リソースを検証します。
キーと必要なパラメーターが存在することを確認します。
Get メソッドの出力として使用されるリソースインスタンスを作成します。このインスタンスは MSFT_FileDirectoryConfiguration 型であり、 MI_Instanceから派生します。
変更されたリソースインスタンスから出力リソースインスタンスを作成し、次の関数を呼び出して MI クライアントに返します。
- MSFT_FileDirectoryConfiguration_GetTargetResource_Construct
- MSFT_FileDirectoryConfiguration_GetTargetResource_SetPtr_OutputResource
- MSFT_FileDirectoryConfiguration_GetTargetResource_Set_MIReturn
- MSFT_FileDirectoryConfiguration_GetTargetResource_Post
- MSFT_FileDirectoryConfiguration_GetTargetResource_Destruct
リソース (割り当てられたメモリの解放など) をクリーンアップします。

WinDC ドキュメント

重要

シナリオ設定のターゲットは、拡張のためにデバイス全体に限定できます。 <LocURI>コンテキストと WinDC コンテキストで定義されている CSP スコープをDeviceする必要があります。

DeclaredConfiguration CSP のDocument リーフノードの値は、要求を記述する XML ドキュメントです。拡張のために指定された構成データを含む WinDC ドキュメントの例を次に示します。

<DeclaredConfiguration schema="1.0" context="Device" id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2" checksum="99925209110918B67FE962460137AA3440AFF4DB6ABBE15C8F499682457B9999" osdefinedscenario="MSFTExtensibilityMIProviderConfig">
    <DSC namespace="root/Microsoft/Windows/DesiredStateConfiguration" className="MSFT_FileDirectoryConfiguration">
        <Key name="DestinationPath">c:\data\test\bin\ut_extensibility.tmp</Key>
        <Value name="Contents">TestFileContent1</Value>
    </DSC>
</DeclaredConfiguration>

osdefinedscenarioでサポートされている値のみを使用できます。サポートされていない値を指定すると、 Invalid scenario nameのようなエラーメッセージが表示されます。

osdefinedscenario	説明
MSFTExtensibilityMIProviderConfig	MI プロバイダーの設定を構成するために使用されます。
MSFTExtensibilityMIProviderInventory	MI プロバイダーの設定値を取得するために使用されます。

同じタグと属性を必要とする MSFTExtensibilityMIProviderConfig シナリオと MSFTExtensibilityMIProviderInventory シナリオの両方。

<DSC> XML タグは、名前空間とクラス名で表されるターゲット WMI プロバイダーと、デバイスに適用される値、または MI プロバイダーによって照会される値を表します。

このタグには、次の属性があります。

属性説明

namespace 対象となる MI プロバイダー名前空間を指定します。

classname 対象となる MI プロバイダー。
<Key> XML タグには、必要なパラメーター名と値が記述されています。構成に必要な値のみです。名前は属性であり、値はコンテンツ <Key> 。

このタグには、次の属性があります。

属性説明

name MI プロバイダーパラメーターの名前を指定します。
<Value> XML タグには、省略可能なパラメーター名と値が記述されています。構成に必要な値のみです。名前は属性であり、値はコンテンツ <Value> 。

このタグには、次の属性があります。

属性説明

name MI プロバイダーパラメーターの名前を指定します。

属性	説明
`namespace`	対象となる MI プロバイダー名前空間を指定します。
`classname`	対象となる MI プロバイダー。

属性	説明
`name`	MI プロバイダーパラメーターの名前を指定します。

属性	説明
`name`	MI プロバイダーパラメーターの名前を指定します。

SyncML の例

標準の OMA-DM SyncML 構文は、置換、追加、削除などの DeclaredConfiguration CSP 操作を指定するために使用 されます。 SyncML の <Data> 要素のペイロードは XML エンコードされている必要があります。この XML エンコードには、さまざまなオンラインエンコーダーを使用できます。ペイロードのエンコードを回避するには、次の SyncML の例に示すように CDATA セクションを使用します。

構成要求

この例では、MSFTExtensibilityMIProviderConfig シナリオで MSFT_FileDirectoryConfiguration MI プロバイダーを使用して構成要求を送信する方法を示します。

<?xml version="1.0" encoding="utf-8"?>
<SyncML xmlns="SYNCML:SYNCML1.1">
  <SyncBody>
    <Replace>
      <CmdID>14</CmdID>
      <Item>
        <Target>
          <LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</LocURI>
        </Target>
        <Data><![CDATA[
            <DeclaredConfiguration schema="1.0" context="Device" id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2" checksum="99925209110918B67FE962460137AA3440AFF4DB6ABBE15C8F499682457B9999" osdefinedscenario="MSFTExtensibilityMIProviderConfig">
                <DSC namespace="root/Microsoft/Windows/DesiredStateConfiguration" className="MSFT_FileDirectoryConfiguration">
                    <Key name="DestinationPath">c:\data\test\bin\ut_extensibility.tmp</Key>
                    <Value name="Contents">TestFileContent1</Value>
                </DSC>
            </DeclaredConfiguration>
        ]]></Data>
      </Item>
    </Replace>
  </SyncBody>
</SyncML>

インベントリ要求

この例では、MSFTExtensibilityMIProviderInventory シナリオで、MSFT_FileDirectoryConfiguration MI プロバイダーを使用してインベントリ要求を送信する方法を示します。

<?xml version="1.0" encoding="utf-8"?>
<SyncML xmlns="SYNCML:SYNCML1.1">
  <SyncBody>
    <Replace>
      <CmdID>15</CmdID>
      <Item>
        <Target>
          <LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/12345678-1234-1234-1234-123456789012/Document</LocURI>
        </Target>
        <Data><![CDATA[
            <DeclaredConfiguration schema="1.0" context="Device" id="12345678-1234-1234-1234-123456789012" checksum="1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF" osdefinedscenario="MSFTExtensibilityMIProviderInventory">
                <DSC namespace="root/Microsoft/Windows/DesiredStateConfiguration" className="MSFT_FileDirectoryConfiguration">
                    <Key name="DestinationPath">c:\data\test\bin\ut_extensibility.tmp</Key>
                </DSC>
            </DeclaredConfiguration>
        ]]></Data>
      </Item>
    </Replace>
  </SyncBody>
</SyncML>

結果を取得する

次の例では、構成要求またはインベントリ要求の結果を取得します。

要求:

<SyncML xmlns="SYNCML:SYNCML1.1">
    <SyncBody>
    <Get>
        <CmdID>2</CmdID>
        <Item>
        <Meta>
            <Format>chr</Format>
            <Type>text/plain</Type>
        </Meta>
        <Target>
            <LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</LocURI>
        </Target>
        </Item>
    </Get>
    <Final />
    </SyncBody>
</SyncML>

応答:

<Status>
    <CmdID>2</CmdID>
    <MsgRef>1</MsgRef>
    <CmdRef>2</CmdRef>
    <Cmd>Get</Cmd>
    <Data>200</Data>
</Status>
<Results>
    <CmdID>3</CmdID>
    <MsgRef>1</MsgRef>
    <CmdRef>2</CmdRef>
    <Item>
        <Source>
            <LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</LocURI>
        </Source>
        <Data>
            <DeclaredConfigurationResult context="Device" schema="1.0" id="99988660-9080-3433-96e8-f32e85011999" osdefinedscenario="MSFTPolicies" checksum="99925209110918B67FE962460137AA3440AFF4DB6ABBE15C8F499682457B9999" result_checksum="EE4F1636201B0D39F71654427E420E625B9459EED17ACCEEE1AC9B358F4283FD" operation="Set" state="60">
                <DSC namespace="root/Microsoft/Windows/DesiredStateConfiguration" className="MSFT_FileDirectoryConfiguration" status="200" state="60">
                    <Key name="DestinationPath" />
                    <Value name="Contents" />
                </DSC>
            </DeclaredConfigurationResult>
        </Data>
    </Item>
</Results>

次の方法で共有

宣言された構成の拡張性

目的の状態構成リソースを作成する

MI プロバイダーの例

手順 1: リソーススキーマ MOF ファイルを作成する

手順 2: スキーマ MOF ファイルをコピーする

手順 3: 必要なファイルを編集する

手順 4: プロバイダージェネレーターツールを実行する

手順 5: 生成されたソースファイルをコピーする

`MSFT_FileDirectoryConfiguration` リソースについて

に関しては `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`

WinDC ドキュメント

SyncML の例

構成要求

インベントリ要求

結果を取得する

MI 実装参照

フィードバック

その他のリソース

次の方法で共有

宣言された構成の拡張性

目的の状態構成リソースを作成する

MI プロバイダーの例

手順 1: リソース スキーマ MOF ファイルを作成する

手順 2: スキーマ MOF ファイルをコピーする

手順 3: 必要なファイルを編集する

手順 4: プロバイダー ジェネレーター ツールを実行する

手順 5: 生成されたソース ファイルをコピーする

MSFT_FileDirectoryConfiguration リソースについて

に関しては MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource

WinDC ドキュメント

SyncML の例

構成要求

インベントリ要求

結果を取得する

MI 実装参照

フィードバック

その他のリソース

手順 1: リソーススキーマ MOF ファイルを作成する

手順 4: プロバイダージェネレーターツールを実行する

手順 5: 生成されたソースファイルをコピーする

`MSFT_FileDirectoryConfiguration` リソースについて

に関しては `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`