Extensibilidad de configuración declarada

Artículo
10/15/2024
Se aplica a:

✅ Windows 11, ✅ Windows 10

La inscripción de configuración declarada de Windows (WinDC) ofrece extensibilidad a través de proveedores WMI nativos. Esta característica crea instancias e interfaces con un proveedor de Instrumental de administración de Windows (WMI) que implementa una interfaz de infraestructura de administración (MI). La interfaz debe implementar los métodos GetTargetResource, TestTargetResource y SetTargetResource, y puede implementar cualquier número de propiedades de cadena.

Nota

Actualmente, los proveedores de extensibilidad solo admiten las propiedades de cadena.

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

Creación de recursos de configuración de estado deseados

Para crear un proveedor WMI nativo, siga los pasos descritos en Implementación de un proveedor de MI. Estos pasos incluyen cómo generar el código fuente de una interfaz mi mediante la Convert-MofToProvider.exe herramienta para generar el archivo DLL y prepararlo para la selección de ubicación.

Cree un archivo de formato de objeto administrado (MOF) que defina el esquema para el recurso de configuración de estado deseado, incluidos los parámetros y métodos. Este archivo incluye los parámetros necesarios para el recurso.
Copie el archivo MOF de esquema junto con los archivos necesarios en el directorio de herramientas del proveedor, por ejemplo: ProviderGenerationTool.
Edite los archivos necesarios e incluya los nombres de archivo y de clase correctos.
Invoque la herramienta generadora del proveedor para generar los archivos de proyecto del proveedor.
Copie los archivos generados en la carpeta del proyecto del proveedor.
Inicie el proceso de desarrollo.

Proveedor de MI de ejemplo

En este ejemplo se proporcionan más detalles sobre cada paso para demostrar cómo implementar un recurso nativo de ejemplo denominado MSFT_FileDirectoryConfiguration.

Paso 1: Creación del archivo MOF de esquema de recursos

Cree un archivo MOF de esquema de ejemplo que se usa para generar el código fuente inicial para el MSFT_FileDirectoryConfiguration recurso nativo. Colócelo en el directorio del proyecto denominado 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
    );
};

Nota

El nombre de clase y el nombre de archivo DLL deben ser los mismos, tal como se define en el Provider.DEF archivo.
El calificador [Key] de tipo de una propiedad indica que identifica de forma única la instancia de recurso. Se requiere al menos una [Key] propiedad.
El [Required] calificador indica que la propiedad es necesaria. Es decir, se debe especificar un valor en cualquier script de configuración que use este recurso.
El [write] calificador indica que la propiedad es opcional cuando se usa el recurso personalizado en un script de configuración. El [read] calificador indica que una configuración no puede establecer una propiedad y es solo para fines de informes.
El [Values] calificador restringe los valores que se pueden asignar a la propiedad . Defina la lista de valores permitidos en [ValueMap]. Para obtener más información, vea ValueMap y calificadores de valor.

Cualquier nuevo archivo MOF debe incluir las siguientes líneas en la parte superior del archivo:

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

Los nombres de método y sus parámetros deben ser iguales para cada recurso. Cambie MSFT_FileDirectoryConfiguration del valor EmbeddedInstance al nombre de clase del proveedor deseado. Solo debe haber un proveedor por archivo MOF.

Paso 2: Copiar los archivos MOF de esquema

Copie estos archivos y carpetas necesarios en el directorio del proyecto que creó en el paso 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 obtener más información sobre cómo obtener los archivos necesarios, consulte Cómo implementar un proveedor de MI.

Paso 3: Editar los archivos necesarios

Modifique los siguientes archivos en el directorio del proyecto:

MSFT_FileDirectoryConfiguration.mof: ha creado este archivo en el paso 1.
Provider.DEF: este archivo contiene el nombre del archivo DLL, por ejemplo, MSFT_FileDirectoryConfiguration.dll.

codegen.cmd: este archivo contiene el 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

Paso 4: Ejecución de la herramienta generador de proveedores

Ejecute codegen.cmd, que ejecuta el convert-moftoprovider.exe comando . Como alternativa, puede ejecutar el comando directamente.

Paso 5: Copia de los archivos de origen generados

El comando del paso 3 especifica el -OutPath parámetro , que en este ejemplo es una carpeta denominada temp. Al ejecutar la herramienta en el paso 4, se crean nuevos archivos en esta carpeta. Copie los archivos generados de esta temp carpeta en el directorio del proyecto. Ha creado el directorio del proyecto en el paso 1, que en este ejemplo es MSFT_FileDirectoryConfiguration.

Nota

Cada vez que actualice el archivo MOF de esquema, ejecute el codegen.cmd script para volver a generar los archivos de origen. Al volver a ejecutar la herramienta generador, se sobrescriben los archivos de origen existentes. Para evitar este comportamiento, en este ejemplo se usa una carpeta temporal. Minimice las actualizaciones del archivo MOF de esquema, ya que la implementación principal debe combinarse con los archivos de origen generados automáticamente más recientes.

Acerca del `MSFT_FileDirectoryConfiguration` recurso

Después de ejecutar la herramienta generadora de proveedores, crea varios archivos de origen y encabezado:

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

En esta lista, solo tiene que modificar MSFT_FileDirectoryConfiguration.c y MSFT_FileDirectoryConfiguration.h. También puede cambiar la extensión de los archivos de origen de .c a .cpp, que es el caso de este recurso. La lógica de negocios de este recurso se implementa en MSFT_FileDirectoryConfigurationImp.cpp y MSFT_FileDirectoryConfigurationImp.h. Estos nuevos archivos se agregan al directorio del MSFT_FileDirectoryConfiguration proyecto después de ejecutar la herramienta generador de proveedores.

Para un recurso de configuración de estado deseado nativo, tiene que implementar tres funciones generadas automáticamente en MSFT_FileDirectoryConfiguration.cpp:

MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource
MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource
MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource

A partir de estas tres funciones, solo MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource es necesario para un escenario Get. MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource y MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource se usan cuando se necesita la corrección.

Hay otras funciones generadas automáticamente en MSFT_FileDirectoryConfiguration.cpp que no necesitan implementación para un recurso de configuración de estado deseado nativo. No es necesario modificar las siguientes funciones:

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`

La MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource función realiza los pasos siguientes para completar su tarea:

Valide el recurso de entrada.
Asegúrese de que las claves y los parámetros necesarios están presentes.
Cree una instancia de recurso que se use como salida del método Get. Esta instancia es de tipo MSFT_FileDirectoryConfiguration, que se deriva de MI_Instance.
Cree la instancia de recurso de salida a partir de la instancia de recurso modificada y devuévalo al cliente de MI llamando a estas funciones:
- MSFT_FileDirectoryConfiguration_GetTargetResource_Construct
- MSFT_FileDirectoryConfiguration_GetTargetResource_SetPtr_OutputResource
- MSFT_FileDirectoryConfiguration_GetTargetResource_Set_MIReturn
- MSFT_FileDirectoryConfiguration_GetTargetResource_Post
- MSFT_FileDirectoryConfiguration_GetTargetResource_Destruct
Limpie los recursos, por ejemplo, la memoria asignada libre.

Documento de WinDC

Importante

El destino de la configuración del escenario solo puede ser todo el dispositivo para la extensibilidad. El ámbito de CSP definido en <LocURI> y el contexto de WinDC debe ser Device.

El valor del Document nodo hoja del CSP DeclaredConfiguration es un documento XML que describe la solicitud. Este es un documento de WinDC de ejemplo con los datos de configuración especificados para la extensibilidad.

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

Solo se pueden usar los valores admitidos para osdefinedscenario . Los valores no admitidos dan como resultado un mensaje de error similar a Invalid scenario name.

osdefinedscenario	Descripción
MSFTExtensibilityMIProviderConfig	Se usa para configurar los valores del proveedor de MI.
MSFTExtensibilityMIProviderInventory	Se usa para recuperar los valores de configuración del proveedor de MI.

Escenarios y MSFTExtensibilityMIProviderConfigMSFTExtensibilityMIProviderInventory que requieren las mismas etiquetas y atributos.

La <DSC> etiqueta XML describe el proveedor WMI de destino expresado por un espacio de nombres y un nombre de clase junto con los valores que se van a aplicar al dispositivo o consultados por el proveedor de MI.

Esta etiqueta tiene los siguientes atributos:

Atributo Descripción

namespace Especifica el espacio de nombres del proveedor de MI de destino.

classname Proveedor de MI de destino.
La <Key> etiqueta XML describe el nombre y el valor de parámetro necesarios. Solo necesita un valor para la configuración. El nombre es un atributo y el valor es <Key> contenido.

Esta etiqueta tiene los siguientes atributos:

Atributo Descripción

name Especifica el nombre de un parámetro de proveedor de MI.
La <Value> etiqueta XML describe el nombre y el valor del parámetro opcional. Solo necesita un valor para la configuración. El nombre es un atributo y el valor es <Value> contenido.

Esta etiqueta tiene los siguientes atributos:

Atributo Descripción

name Especifica el nombre de un parámetro de proveedor de MI.

Atributo	Descripción
`namespace`	Especifica el espacio de nombres del proveedor de MI de destino.
`classname`	Proveedor de MI de destino.

Atributo	Descripción
`name`	Especifica el nombre de un parámetro de proveedor de MI.

Atributo	Descripción
`name`	Especifica el nombre de un parámetro de proveedor de MI.

Ejemplos de SyncML

La sintaxis syncML estándar de OMA-DM se usa para especificar las operaciones de CSP DeclaredConfiguration, como Replace, Add y Delete. La carga del elemento de <Data> SyncML debe estar codificada en XML. Para esta codificación XML, hay varios codificadores en línea que puede usar. Para evitar la codificación de la carga, puede usar la sección CDATA como se muestra en los siguientes ejemplos de SyncML.

Solicitud de configuración

En este ejemplo se muestra cómo enviar una solicitud de configuración mediante el MSFT_FileDirectoryConfiguration proveedor de MI con el MSFTExtensibilityMIProviderConfig escenario .

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

Solicitud de inventario

En este ejemplo se muestra cómo enviar una solicitud de inventario mediante el proveedor MSFT_FileDirectoryConfiguration MI con el escenario 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>

Recuperar resultados

En este ejemplo se recuperan los resultados de una solicitud de configuración o inventario:

Solicitud:

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

Respuesta:

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

Compartir a través de

Extensibilidad de configuración declarada

Creación de recursos de configuración de estado deseados

Proveedor de MI de ejemplo

Paso 1: Creación del archivo MOF de esquema de recursos

Paso 2: Copiar los archivos MOF de esquema

Paso 3: Editar los archivos necesarios

Paso 4: Ejecución de la herramienta generador de proveedores

Paso 5: Copia de los archivos de origen generados

Acerca del `MSFT_FileDirectoryConfiguration` recurso

Acerca de `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`

Documento de WinDC

Ejemplos de SyncML

Solicitud de configuración

Solicitud de inventario

Recuperar resultados

Referencias de implementación de MI

Comentarios

Recursos adicionales

Compartir a través de

Extensibilidad de configuración declarada

Creación de recursos de configuración de estado deseados

Proveedor de MI de ejemplo

Paso 1: Creación del archivo MOF de esquema de recursos

Paso 2: Copiar los archivos MOF de esquema

Paso 3: Editar los archivos necesarios

Paso 4: Ejecución de la herramienta generador de proveedores

Paso 5: Copia de los archivos de origen generados

Acerca del MSFT_FileDirectoryConfiguration recurso

Acerca de MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource

Documento de WinDC

Ejemplos de SyncML

Solicitud de configuración

Solicitud de inventario

Recuperar resultados

Referencias de implementación de MI

Comentarios

Recursos adicionales

Acerca del `MSFT_FileDirectoryConfiguration` recurso

Acerca de `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`