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

Статья
10/15/2024
Применяется к:

✅ Windows 11, ✅ Windows 10

Регистрация, объявленная 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 и подготовки ее к размещению.

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

Пример поставщика 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
    );
};

Примечание.

Имя класса и 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 выполнения задачи функция выполняет следующие действия:

Проверьте входной ресурс.
Убедитесь, что ключи и необходимые параметры присутствуют.
Создайте экземпляр ресурса, который будет использоваться в качестве выходных данных метода 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

Важно.

Целевой объект параметров сценария может быть только на уровне устройства для расширяемости. Для область CSP, определенного в <LocURI> и контексте WinDC, должен быть Device.

Значение конечного 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.

osdefinedscenario	Описание
MSFTExtensibilityMIProviderConfig	Используется для настройки параметров поставщика mi.
MSFTExtensibilityMIProviderInventory	Используется для получения значений параметров поставщика MI.

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

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

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

Атрибут Описание

namespace Указывает целевое пространство имен поставщика MI.

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

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

Атрибут Описание

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

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

Атрибут Описание

name Указывает имя параметра поставщика MI.

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

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

Атрибут	Описание
`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

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