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

Регистрация, объявленная Windows (WinDC), обеспечивает расширяемость через собственные поставщики 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. Запустите процесс разработки.

Пример поставщика MI

В этом примере содержатся дополнительные сведения о каждом шаге, чтобы продемонстрировать реализацию примера собственного ресурса с именем 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
    );
};

Шаг 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.

Сведения о ресурсе 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. Очистите ресурсы, например свободную выделенную память.

Документ WinDC

Значение конечного Document узла в поставщике CSP DeclaredConfiguration представляет собой 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.

MSFTExtensibilityMIProviderInventory И MSFTExtensibilityMIProviderConfig сценарии, для которых требуются одни и те же теги и атрибуты.

• <DSC> Xml-тег описывает целевой поставщик WMI, выраженный пространством имен и именем класса, а также значения, которые должны применяться к устройству или запрашиваться поставщиком MI.

  Этот тег имеет следующие атрибуты:

  Атрибут	Описание
  namespace	Указывает целевое пространство имен поставщика MI.
  classname	Целевой поставщик MI.

• XML-тег <Key> описывает имя и значение требуемого параметра. Ему требуется только значение для конфигурации. Имя — это атрибут, а значение — содержимое <Key> .

  Этот тег имеет следующие атрибуты:

  Атрибут	Описание
  name	Указывает имя параметра поставщика MI.

• Xml-тег <Value> описывает необязательное имя и значение параметра. Ему требуется только значение для конфигурации. Имя — это атрибут, а значение — содержимое <Value> .

  Этот тег имеет следующие атрибуты:

  Атрибут	Описание
  name	Указывает имя параметра поставщика MI.

Примеры SyncML

Стандартный синтаксис OMA-DM SyncML используется для указания операций CSP DeclaredConfiguration, таких как Replace, Add и Delete. Полезные данные элемента 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>

Запрос на инвентаризацию

В этом примере показано, как отправить запрос инвентаризации с помощью поставщика MSFT_FileDirectoryConfiguration MI со сценарием MSFTExtensibilityMIProviderInventory.

<?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

• 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)