声明的配置扩展性

项目
10/15/2024
适用于:

✅ Windows 11, ✅ Windows 10

Windows 声明的配置 (WinDC) 注册通过本机 WMI 提供程序提供扩展性。此功能与 Windows Management Instrumentation (WMI) 提供程序实例化和接口，该提供程序实现管理基础结构 (MI) 接口。接口必须实现 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 接口 Convert-MofToProvider.exe 生成源代码，以生成 DLL 并准备放置 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] 指示它唯一标识资源实例。至少需要一个 [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")

每个资源的方法名称及其参数都应相同。从 EmbeddedInstance 值更改为 MSFT_FileDirectoryConfiguration 所需提供程序的类名称。每个 MOF 文件应只有一个提供程序。

步骤 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：运行提供程序生成器工具

运行 codegen.cmd，它运行命令 convert-moftoprovider.exe 。或者，可以直接运行命令。

步骤 5：复制生成的源文件

步骤 3 中的命令指定 -OutPath 参数，在此示例中为名为 temp的文件夹。在步骤 4 中运行该工具时，它会在此文件夹中创建新文件。将生成的文件从此 temp 文件夹复制到项目目录。在步骤 1 中创建了项目目录，在此示例中为 MSFT_FileDirectoryConfiguration。

注意

每当更新架构 MOF 文件时，请 codegen.cmd 运行脚本以重新生成源文件。重新运行生成器工具将覆盖任何现有的源文件。为了防止此行为，此示例使用临时文件夹。尽量减少对架构 MOF 文件的更新，因为应将main实现与最近自动生成的源文件合并。

关于资源`MSFT_FileDirectoryConfiguration`

运行提供程序生成器工具后，它会创建多个源文件和头文件：

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

在此列表中，只需修改 MSFT_FileDirectoryConfiguration.c 和 MSFT_FileDirectoryConfiguration.h。还可以将源文件的扩展名从 .c 更改为 .cpp，此资源就是这种情况。此资源的业务逻辑在和 MSFT_FileDirectoryConfigurationImp.h中MSFT_FileDirectoryConfigurationImp.cpp实现。运行提供程序生成器工具后， MSFT_FileDirectoryConfiguration 这些新文件将添加到项目目录。

对于本机所需状态配置资源，必须在中 MSFT_FileDirectoryConfiguration.cpp实现三个自动生成的函数：

MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource
MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource
MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource

在这三个函数中，只有 MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource Get 方案需要。 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 文档

重要提示

方案设置的目标只能是设备范围的扩展性。和 WinDC 上下文中<LocURI>定义的 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> content。

此标记具有以下属性：

属性说明

name 指定 MI 提供程序参数的名称。
<Value> XML 标记描述可选的参数名称和值。它只需要一个值进行配置。名称是属性，值为 <Value> content。

此标记具有以下属性：

属性说明

name 指定 MI 提供程序参数的名称。

属性	说明
`namespace`	指定目标 MI 提供程序命名空间。
`classname`	目标 MI 提供程序。

属性	说明
`name`	指定 MI 提供程序参数的名称。

属性	说明
`name`	指定 MI 提供程序参数的名称。

SyncML 示例

标准 OMA-DM SyncML 语法用于指定 DeclaredConfiguration CSP 操作，例如替换、添加和删除。 SyncML <Data> 元素的有效负载必须是 XML 编码的。对于此 XML 编码，可以使用各种联机编码器。若要避免对有效负载进行编码，可以使用 CDATA 节，如以下 SyncML 示例所示。

配置请求

此示例演示如何在方案中使用 MSFT_FileDirectoryConfiguration MI 提供程序 MSFTExtensibilityMIProviderConfig 发送配置请求。

<?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 实现参考

反馈

其他资源

关于资源`MSFT_FileDirectoryConfiguration`

大约 `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`