声明的配置扩展性提供程序

• 适用于:

  ✅ Windows 11, ✅ Windows 10

声明的配置注册支持声明的配置客户端堆栈，它通过本机 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 接口 Convert-MofToProvider.exe 生成源代码，以生成 DLL 并准备放置 DLL。

1. 创建一个 MOF 文件，该文件定义所需状态配置资源的架构，包括参数和方法。 此文件包括资源所需的参数。
2. 将架构 MOF 文件以及任何所需文件复制到提供程序工具目录中，例如：ProviderGenerationTool。
3. 编辑所需的文件，并包括正确的文件名和类名。
4. 调用提供程序生成器工具以生成提供程序的项目文件。
5. 将生成的文件复制到提供程序的项目文件夹中。
6. 启动开发过程。

示例

此示例提供有关每个步骤的更多详细信息，以演示如何实现名为 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 执行以下步骤来完成其任务：

1. 验证输入资源。

2. 确保存在密钥和所需参数。

3. 创建用作 Get 方法输出的资源实例。 此实例的类型 MSFT_FileDirectoryConfiguration为 ，派生自 MI_Instance。

4. 从修改的资源实例创建输出资源实例，并通过调用以下函数将其返回到 MI 客户端：

   • MSFT_FileDirectoryConfiguration_GetTargetResource_Construct
   • MSFT_FileDirectoryConfiguration_GetTargetResource_SetPtr_OutputResource
   • MSFT_FileDirectoryConfiguration_GetTargetResource_Set_MIReturn
   • MSFT_FileDirectoryConfiguration_GetTargetResource_Post
   • MSFT_FileDirectoryConfiguration_GetTargetResource_Destruct

5. 清理资源，例如可用分配的内存。

MI 实现参考

• 介绍管理基础结构 (MI) API
• 实现 MI 提供程序 (1) - 概述
• 实现 MI 提供程序 (2) - 定义架构
• 实现 MI 提供程序 (3) - 生成代码
• 实现 MI 提供程序 (4) - 生成代码 (继续)
• 实现 MI 提供程序 (5) - 实现
• 实现 MI 提供程序 (6) - 生成、注册和调试
• MI 接口
• MI 数据类型
• MI 结构和联合
• MI_Result 枚举 (mi.h)
• MI_Type枚举 (mi.h)