Объявленные поставщики расширяемости конфигурации

• Применяется к:

  ✅ Windows 11, ✅ Windows 10

Объявленная регистрация конфигурации, которая поддерживает объявленный стек клиента конфигурации, обеспечивает расширяемость через собственные поставщики WMI. Эта функция создает экземпляры и взаимодействует с поставщиком инструментария управления Windows (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 и подготовки ее к размещению.

1. Создайте MOF-файл, который определяет схему для требуемого ресурса конфигурации состояния, включая параметры и методы. Этот файл содержит необходимые параметры для ресурса.
2. Скопируйте MOF-файл схемы вместе с любыми необходимыми файлами в каталог средств поставщика, например ProviderGenerationTool.
3. Измените необходимые файлы и включите правильные имена файлов и классов.
4. Вызовите средство генератора поставщиков, чтобы создать файлы проекта поставщика.
5. Скопируйте созданные файлы в папку проекта поставщика.
6. Запустите процесс разработки.

Пример

В этом примере содержатся дополнительные сведения о каждом шаге, чтобы продемонстрировать реализацию примера собственного ресурса с именем MSFT_FileDirectoryConfiguration.

Шаг 1. Создание MOF-файла схемы ресурсов

Создайте пример MOF-файла схемы, который используется для создания исходного кода для собственного MSFT_FileDirectoryConfiguration ресурса. Поместите его в каталог проекта с именем 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")
  

• Имена методов и его параметры должны быть одинаковыми для каждого ресурса. Измените MSFT_FileDirectoryConfiguration значение EmbeddedInstance на имя класса нужного поставщика. На 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.cpp и MSFT_FileDirectoryConfigurationImp.h. Эти новые файлы добавляются в 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

• Знакомство с API инфраструктуры управления (MI)
• Реализация поставщика MI (1) — обзор
• Реализация поставщика MI (2) — определение схемы
• Реализация поставщика MI (3) — создание кода
• Реализация поставщика MI (4) — создание кода (продолжение)
• Реализация поставщика MI (5) — реализация
• Реализация поставщика MI (6) — сборка, регистрация и отладка
• Интерфейсы mi
• Типы данных MI
• Структуры и объединения mi
• перечисление MI_Result (mi.h)
• перечисление MI_Type (mi.h)