Extensibilidade de configuração declarada

Artigo
10/15/2024
Aplica-se a:

✅ Windows 11, ✅ Windows 10

A inscrição de configuração declarada do Windows (WinDC) oferece extensibilidade através de fornecedores WMI nativos. Esta funcionalidade instancia e interfaces com um fornecedor do Windows Management Instrumentation (WMI) que implementa uma interface de infraestrutura de gestão (MI). A interface tem de implementar os métodos GetTargetResource, TestTargetResource e SetTargetResource e pode implementar qualquer número de propriedades de cadeia.

Observação

Atualmente, apenas as propriedades de cadeia são suportadas por fornecedores de extensibilidade.

[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
);

Criar recursos de configuração de estado pretendidos

Para criar um fornecedor WMI nativo, siga os passos descritos em Como implementar um fornecedor de MI. Estes passos incluem como gerar o código fonte para uma interface MI com a Convert-MofToProvider.exe ferramenta para gerar o DLL e prepará-lo para colocação.

Crie um ficheiro MOF (Managed Object Format) que defina o esquema para o recurso de configuração de estado pretendido, incluindo parâmetros e métodos. Este ficheiro inclui os parâmetros necessários para o recurso.
Copie o ficheiro MOF de esquema juntamente com todos os ficheiros necessários para o diretório de ferramentas do fornecedor, por exemplo: ProviderGenerationTool.
Edite os ficheiros necessários e inclua os nomes de ficheiro e os nomes de classe corretos.
Invoque a ferramenta geradora do fornecedor para gerar os ficheiros de projeto do fornecedor.
Copie os ficheiros gerados para a pasta de projeto do fornecedor.
Inicie o processo de desenvolvimento.

Exemplo de fornecedor de MI

Este exemplo fornece mais detalhes sobre cada passo para demonstrar como implementar um recurso nativo de exemplo com o nome MSFT_FileDirectoryConfiguration.

Passo 1: Criar o ficheiro MOF do esquema de recursos

Crie um ficheiro MOF de esquema de exemplo utilizado para gerar o código fonte inicial para o MSFT_FileDirectoryConfiguration recurso nativo. Coloque-o no diretório do projeto com o nome 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
    );
};

Observação

O nome da classe e o nome do ficheiro DLL devem ser os mesmos, conforme definido no Provider.DEF ficheiro.
O qualificador [Key] de tipo numa propriedade indica que identifica exclusivamente a instância de recurso. É necessária, pelo menos, uma [Key] propriedade.
O [Required] qualificador indica que a propriedade é necessária. Por outras palavras, um valor tem de ser especificado em qualquer script de configuração que utilize este recurso.
O [write] qualificador indica que a propriedade é opcional ao utilizar o recurso personalizado num script de configuração. O [read] qualificador indica que uma propriedade não pode ser definida por uma configuração e destina-se apenas a relatórios.
O [Values] qualificador restringe os valores que podem ser atribuídos à propriedade . Defina a lista de valores permitidos em [ValueMap]. Para obter mais informações, veja ValueMap e qualificadores de valor.

Qualquer novo ficheiro MOF deve incluir as seguintes linhas na parte superior do ficheiro:

#pragma include ("cim_schema_2.26.0.mof")
#pragma include ("OMI_BaseResource.mof")
#pragma include ("MSFT_Credential.mof")

Os nomes dos métodos e os respetivos parâmetros devem ser os mesmos para cada recurso. Mude MSFT_FileDirectoryConfiguration do valor EmbeddedInstance para o nome da classe do fornecedor pretendido. Deve existir apenas um fornecedor por ficheiro MOF.

Passo 2: Copiar os ficheiros MOF de esquema

Copie estes ficheiros e pastas necessários para o diretório do projeto que criou no passo 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

Para obter mais informações sobre como obter os ficheiros necessários, veja Como implementar um fornecedor de MI.

Passo 3: Editar os ficheiros necessários

Modifique os seguintes ficheiros no diretório do projeto:

MSFT_FileDirectoryConfiguration.mof: criou este ficheiro no passo 1.
Provider.DEF: este ficheiro contém o nome DLL, por exemplo, MSFT_FileDirectoryConfiguration.dll.

codegen.cmd: este ficheiro contém o comando para invocar 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

Passo 4: Executar a ferramenta geradora de fornecedores

Execute codegen.cmd, que executa o convert-moftoprovider.exe comando . Em alternativa, pode executar o comando diretamente.

Passo 5: Copiar os ficheiros de origem gerados

O comando no passo 3 especifica o -OutPath parâmetro , que neste exemplo é uma pasta chamada temp. Quando executa a ferramenta no passo 4, esta cria novos ficheiros nesta pasta. Copie os ficheiros gerados desta temp pasta para o diretório do projeto. Criou o diretório do projeto no passo 1, que neste exemplo é MSFT_FileDirectoryConfiguration.

Observação

Sempre que atualizar o ficheiro MOF do esquema, execute o codegen.cmd script para regenerar os ficheiros de origem. Executar novamente a ferramenta gerador substitui todos os ficheiros de origem existentes. Para impedir este comportamento, este exemplo utiliza uma pasta temporária. Minimize as atualizações ao ficheiro MOF de esquema, uma vez que a implementação do main deve ser intercalada com os ficheiros de origem gerados automaticamente mais recentemente.

Acerca do `MSFT_FileDirectoryConfiguration` recurso

Depois de executar a ferramenta geradora de fornecedores, esta cria vários ficheiros de origem e cabeçalho:

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

Nesta lista, só precisa de modificar MSFT_FileDirectoryConfiguration.c e MSFT_FileDirectoryConfiguration.h. Também pode alterar a extensão dos ficheiros de origem de .c para .cpp, o que é o caso deste recurso. A lógica de negócio para este recurso é implementada no e MSFT_FileDirectoryConfigurationImp.hno MSFT_FileDirectoryConfigurationImp.cpp . Estes novos ficheiros são adicionados ao diretório do MSFT_FileDirectoryConfiguration projeto depois de executar a ferramenta geradora de fornecedores.

Para um recurso de configuração de estado pretendido nativo, tem de implementar três funções geradas automaticamente no MSFT_FileDirectoryConfiguration.cpp:

MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource
MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource
MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource

A partir destas três funções, só MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource é necessário para um cenário Obter. MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource e MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource são utilizados quando a remediação é necessária.

Existem várias outras funções geradas automaticamente que MSFT_FileDirectoryConfiguration.cpp não precisam de implementação para um recurso de configuração de estado pretendido nativo. Não precisa de modificar as seguintes funções:

MSFT_FileDirectoryConfiguration_Load
MSFT_FileDirectoryConfiguration_Unload
MSFT_FileDirectoryConfiguration_EnumerateInstances
MSFT_FileDirectoryConfiguration_GetInstance
MSFT_FileDirectoryConfiguration_CreateInstance
MSFT_FileDirectoryConfiguration_ModifyInstance
MSFT_FileDirectoryConfiguration_DeleteInstance

Acerca de `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`

A MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource função efetua os seguintes passos para concluir a tarefa:

Valide o recurso de entrada.
Certifique-se de que as chaves e os parâmetros necessários estão presentes.
Crie uma instância de recurso que é utilizada como a saída do método Get. Esta instância é do tipo MSFT_FileDirectoryConfiguration, que deriva de MI_Instance.
Crie a instância do recurso de saída a partir da instância de recurso modificada e devolva-a ao cliente MI ao chamar estas funções:
- MSFT_FileDirectoryConfiguration_GetTargetResource_Construct
- MSFT_FileDirectoryConfiguration_GetTargetResource_SetPtr_OutputResource
- MSFT_FileDirectoryConfiguration_GetTargetResource_Set_MIReturn
- MSFT_FileDirectoryConfiguration_GetTargetResource_Post
- MSFT_FileDirectoryConfiguration_GetTargetResource_Destruct
Limpe os recursos, por exemplo, a memória alocada gratuita.

Documento WinDC

Importante

O destino das definições do cenário só pode ser de toda a extensibilidade do dispositivo. O âmbito CSP definido no e o <LocURI>contexto WinDC tem de ser Device.

O valor do Document nó de folha no CSP DeclaredConfiguration é um documento XML que descreve o pedido. Eis um documento WinDC de exemplo com os dados de configuração especificados para extensibilidade.

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

Só podem ser utilizados valores suportados para osdefinedscenario . Os valores não suportados resultam numa mensagem de erro semelhante a Invalid scenario name.

osdefinedscenario	Descrição
MSFTExtensibilityMIProviderConfig	Utilizado para configurar as definições do fornecedor de MI.
MSFTExtensibilityMIProviderInventory	Utilizado para obter valores de definição do fornecedor mi.

Cenários MSFTExtensibilityMIProviderConfig e MSFTExtensibilityMIProviderInventory que requerem as mesmas etiquetas e atributos.

A <DSC> etiqueta XML descreve o fornecedor WMI de destino expresso por um espaço de nomes e um nome de classe, juntamente com os valores a aplicar ao dispositivo ou consultados pelo fornecedor de MI.

Esta etiqueta tem os seguintes atributos:

Atributo Descrição

namespace Especifica o espaço de nomes do fornecedor de MI de destino.

classname O fornecedor de MI de destino.
A <Key> etiqueta XML descreve o nome e o valor do parâmetro necessários. Só precisa de um valor para a configuração. O nome é um atributo e o valor é <Key> conteúdo.

Esta etiqueta tem os seguintes atributos:

Atributo Descrição

name Especifica o nome de um parâmetro de fornecedor de MI.
A <Value> etiqueta XML descreve o nome e o valor do parâmetro opcional. Só precisa de um valor para a configuração. O nome é um atributo e o valor é <Value> conteúdo.

Esta etiqueta tem os seguintes atributos:

Atributo Descrição

name Especifica o nome de um parâmetro de fornecedor de MI.

Atributo	Descrição
`namespace`	Especifica o espaço de nomes do fornecedor de MI de destino.
`classname`	O fornecedor de MI de destino.

Atributo	Descrição
`name`	Especifica o nome de um parâmetro de fornecedor de MI.

Atributo	Descrição
`name`	Especifica o nome de um parâmetro de fornecedor de MI.

Exemplos de SyncML

A sintaxe OMA-DM SyncML padrão é utilizada para especificar as operações CSP DeclaredConfiguration, tais como Substituir, Adicionar e Eliminar. O payload do elemento do <Data> SyncML tem de ter codificação XML. Para esta codificação XML, existem vários codificadores online que pode utilizar. Para evitar codificar o payload, pode utilizar a Secção CDATA , conforme mostrado nos seguintes exemplos de SyncML.

Pedido de configuração

Este exemplo demonstra como enviar um pedido de configuração com o MSFT_FileDirectoryConfiguration fornecedor de MI com o MSFTExtensibilityMIProviderConfig cenário.

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

Pedido de inventário

Este exemplo demonstra como enviar um pedido de inventário com o fornecedor MSFT_FileDirectoryConfiguration MI com o cenário 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>

Obter resultados

Este exemplo obtém os resultados de um pedido de configuração ou inventário:

Pedido:

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

Resposta:

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

Compartilhar via

Extensibilidade de configuração declarada

Criar recursos de configuração de estado pretendidos

Exemplo de fornecedor de MI

Passo 1: Criar o ficheiro MOF do esquema de recursos

Passo 2: Copiar os ficheiros MOF de esquema

Passo 3: Editar os ficheiros necessários

Passo 4: Executar a ferramenta geradora de fornecedores

Passo 5: Copiar os ficheiros de origem gerados

Acerca do `MSFT_FileDirectoryConfiguration` recurso

Acerca de `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`

Documento WinDC

Exemplos de SyncML

Pedido de configuração

Pedido de inventário

Obter resultados

Referências de implementação de MI

Comentários

Recursos adicionais

Compartilhar via

Extensibilidade de configuração declarada

Criar recursos de configuração de estado pretendidos

Exemplo de fornecedor de MI

Passo 1: Criar o ficheiro MOF do esquema de recursos

Passo 2: Copiar os ficheiros MOF de esquema

Passo 3: Editar os ficheiros necessários

Passo 4: Executar a ferramenta geradora de fornecedores

Passo 5: Copiar os ficheiros de origem gerados

Acerca do MSFT_FileDirectoryConfiguration recurso

Acerca de MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource

Documento WinDC

Exemplos de SyncML

Pedido de configuração

Pedido de inventário

Obter resultados

Referências de implementação de MI

Comentários

Recursos adicionais

Acerca do `MSFT_FileDirectoryConfiguration` recurso

Acerca de `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`