Estendibilità della configurazione dichiarata

Articolo
10/15/2024
Si applica a:

✅ Windows 11, ✅ Windows 10

La registrazione della configurazione dichiarata da Windows (WinDC) offre estendibilità tramite provider WMI nativi. Questa funzionalità crea un'istanza e si interfaccia con un provider WMI (Windows Management Instrumentation) che implementa un'interfaccia dell'infrastruttura di gestione (MI). L'interfaccia deve implementare i metodi GetTargetResource, TestTargetResource e SetTargetResource e può implementare un numero qualsiasi di proprietà stringa.

Nota

Solo le proprietà stringa sono attualmente supportate dai provider di estendibilità.

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

Creare le risorse di configurazione dello stato desiderate

Per creare un provider WMI nativo, seguire i passaggi descritti in Come implementare un provider mi. Questi passaggi includono come generare il codice sorgente per un'interfaccia MI usando lo Convert-MofToProvider.exe strumento per generare la DLL e prepararla per il posizionamento.

Creare un file MOF (Managed Object Format) che definisce lo schema per la risorsa di configurazione dello stato desiderata, inclusi parametri e metodi. Questo file include i parametri necessari per la risorsa.
Copiare il file MOF dello schema insieme a tutti i file necessari nella directory degli strumenti del provider, ad esempio ProviderGenerationTool.
Modificare i file necessari e includere i nomi di file e di classe corretti.
Richiamare lo strumento generatore di provider per generare i file di progetto del provider.
Copiare i file generati nella cartella del progetto del provider.
Avviare il processo di sviluppo.

Provider MI di esempio

In questo esempio vengono forniti altri dettagli su ogni passaggio per illustrare come implementare una risorsa nativa di esempio denominata MSFT_FileDirectoryConfiguration.

Passaggio 1: Creare il file MOF dello schema di risorse

Creare un file MOF dello schema di esempio usato per generare il codice sorgente iniziale per la MSFT_FileDirectoryConfiguration risorsa nativa. Inserirlo nella directory del progetto denominata 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

Il nome della classe e il nome del file DLL devono essere gli stessi, come definito nel Provider.DEF file.
Il qualificatore [Key] di tipo in una proprietà indica che identifica in modo univoco l'istanza della risorsa. È necessaria almeno una [Key] proprietà.
Il [Required] qualificatore indica che la proprietà è obbligatoria. In altre parole, è necessario specificare un valore in qualsiasi script di configurazione che usa questa risorsa.
Il [write] qualificatore indica che la proprietà è facoltativa quando si usa la risorsa personalizzata in uno script di configurazione. Il [read] qualificatore indica che una proprietà non può essere impostata da una configurazione ed è solo a scopo di creazione di report.
Il [Values] qualificatore limita i valori che possono essere assegnati alla proprietà. Definire l'elenco di valori consentiti in [ValueMap]. Per altre informazioni, vedere ValueMap e qualificatori di valore.

Qualsiasi nuovo file MOF deve includere le righe seguenti nella parte superiore del file:

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

I nomi dei metodi e i relativi parametri devono essere uguali per ogni risorsa. Passare MSFT_FileDirectoryConfiguration dal valore EmbeddedInstance al nome della classe del provider desiderato. Deve essere presente un solo provider per ogni file MOF.

Passaggio 2: Copiare i file MOF dello schema

Copiare i file e le cartelle necessari nella directory del progetto creata nel passaggio 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

Per altre informazioni su come ottenere i file necessari, vedere Come implementare un provider mi.

Passaggio 3: Modificare i file necessari

Modificare i file seguenti nella directory del progetto:

MSFT_FileDirectoryConfiguration.mof: questo file è stato creato nel passaggio 1.
Provider.DEF: questo file contiene il nome della DLL, ad esempio MSFT_FileDirectoryConfiguration.dll.

codegen.cmd: questo file contiene il comando per richiamare 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

Passaggio 4: Eseguire lo strumento generatore di provider

Eseguire codegen.cmd, che esegue il convert-moftoprovider.exe comando . In alternativa, è possibile eseguire il comando direttamente.

Passaggio 5: Copiare i file di origine generati

Il comando nel passaggio 3 specifica il -OutPath parametro , che in questo esempio è una cartella denominata temp. Quando si esegue lo strumento nel passaggio 4, vengono creati nuovi file in questa cartella. Copiare i file generati da questa temp cartella nella directory del progetto. La directory del progetto è stata creata nel passaggio 1, che in questo esempio è MSFT_FileDirectoryConfiguration.

Nota

Ogni volta che si aggiorna il file MOF dello schema, eseguire lo codegen.cmd script per rigenerare i file di origine. La riesecuzione dello strumento generatore sovrascrive tutti i file di origine esistenti. Per evitare questo comportamento, in questo esempio viene utilizzata una cartella temporanea. Ridurre al minimo gli aggiornamenti al file MOF dello schema poiché l'implementazione principale deve essere unita ai file di origine generati automaticamente più recenti.

Informazioni sulla `MSFT_FileDirectoryConfiguration` risorsa

Dopo aver eseguito lo strumento generatore di provider, vengono creati diversi file di origine e di intestazione:

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

Da questo elenco è sufficiente modificare MSFT_FileDirectoryConfiguration.c e MSFT_FileDirectoryConfiguration.h. È anche possibile modificare l'estensione per i file di origine da .c a .cpp, come nel caso di questa risorsa. La logica di business per questa risorsa viene implementata in MSFT_FileDirectoryConfigurationImp.cpp e MSFT_FileDirectoryConfigurationImp.h. Questi nuovi file vengono aggiunti alla directory del MSFT_FileDirectoryConfiguration progetto dopo l'esecuzione dello strumento generatore di provider.

Per una risorsa di configurazione dello stato desiderata nativa, è necessario implementare tre funzioni generate automaticamente in MSFT_FileDirectoryConfiguration.cpp:

MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource
MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource
MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource

Da queste tre funzioni, è necessario solo MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource per uno scenario Get. MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource e MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource vengono usati quando è necessaria la correzione.

Esistono diverse altre funzioni generate automaticamente in MSFT_FileDirectoryConfiguration.cpp che non richiedono l'implementazione per una risorsa di configurazione dello stato desiderata nativa. Non è necessario modificare le funzioni seguenti:

MSFT_FileDirectoryConfiguration_Load
MSFT_FileDirectoryConfiguration_Unload
MSFT_FileDirectoryConfiguration_EnumerateInstances
MSFT_FileDirectoryConfiguration_GetInstance
MSFT_FileDirectoryConfiguration_CreateInstance
MSFT_FileDirectoryConfiguration_ModifyInstance
MSFT_FileDirectoryConfiguration_DeleteInstance

Circa `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`

La MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource funzione esegue i passaggi seguenti per completare l'attività:

Convalidare la risorsa di input.
Verificare che le chiavi e i parametri necessari siano presenti.
Creare un'istanza di risorsa usata come output del metodo Get. Questa istanza è di tipo MSFT_FileDirectoryConfiguration, derivato da MI_Instance.
Creare l'istanza della risorsa di output dall'istanza di risorsa modificata e restituirla al client MI chiamando queste funzioni:
- MSFT_FileDirectoryConfiguration_GetTargetResource_Construct
- MSFT_FileDirectoryConfiguration_GetTargetResource_SetPtr_OutputResource
- MSFT_FileDirectoryConfiguration_GetTargetResource_Set_MIReturn
- MSFT_FileDirectoryConfiguration_GetTargetResource_Post
- MSFT_FileDirectoryConfiguration_GetTargetResource_Destruct
Pulire le risorse, ad esempio la memoria allocata gratuita.

Documento WinDC

Importante

La destinazione delle impostazioni dello scenario può essere estesa solo al dispositivo per l'estendibilità. L'ambito CSP definito in e il <LocURI>contesto WinDC devono essere Device.

Il valore del Document nodo foglia nel provider di servizi di configurazione DeclaredConfiguration è un documento XML che descrive la richiesta. Ecco un documento WinDC di esempio con i dati di configurazione specificati per l'estendibilità.

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

È possibile usare solo i valori supportati per osdefinedscenario . I valori non supportati generano un messaggio di errore simile a Invalid scenario name.

osdefinedscenario	Descrizione
MSFTExtensibilityMIProviderConfig	Usato per configurare le impostazioni del provider mi.
MSFTExtensibilityMIProviderInventory	Usato per recuperare i valori delle impostazioni del provider MI.

Scenari MSFTExtensibilityMIProviderConfig e MSFTExtensibilityMIProviderInventory che richiedono gli stessi tag e attributi.

Il <DSC> tag XML descrive il provider WMI di destinazione espresso da uno spazio dei nomi e da un nome di classe insieme ai valori da applicare al dispositivo o sottoposti a query dal provider MI.

Questo tag ha gli attributi seguenti:

Attributo Descrizione

namespace Specifica lo spazio dei nomi del provider MI di destinazione.

classname Provider mi di destinazione.
Il <Key> tag XML descrive il nome e il valore del parametro necessari. Richiede solo un valore per la configurazione. Il nome è un attributo e il valore è <Key> contenuto.

Questo tag ha gli attributi seguenti:

Attributo Descrizione

name Specifica il nome di un parametro del provider MI.
Il <Value> tag XML descrive il nome e il valore del parametro facoltativo. Richiede solo un valore per la configurazione. Il nome è un attributo e il valore è <Value> contenuto.

Questo tag ha gli attributi seguenti:

Attributo Descrizione

name Specifica il nome di un parametro del provider MI.

Attributo	Descrizione
`namespace`	Specifica lo spazio dei nomi del provider MI di destinazione.
`classname`	Provider mi di destinazione.

Attributo	Descrizione
`name`	Specifica il nome di un parametro del provider MI.

Attributo	Descrizione
`name`	Specifica il nome di un parametro del provider MI.

Esempi di SyncML

La sintassi Standard OMA-DM SyncML viene usata per specificare le operazioni CSP DeclaredConfiguration, ad esempio Sostituisci, Aggiungi ed Elimina. Il payload dell'elemento di <Data> SyncML deve essere codificato in XML. Per questa codifica XML, è possibile usare diversi codificatori online. Per evitare la codifica del payload, è possibile usare la sezione CDATA come illustrato negli esempi SyncML seguenti.

Richiesta di configurazione

Questo esempio illustra come inviare una richiesta di configurazione usando il MSFT_FileDirectoryConfiguration provider MI con lo MSFTExtensibilityMIProviderConfig scenario.

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

Richiesta di inventario

Questo esempio illustra come inviare una richiesta di inventario usando il provider mi MSFT_FileDirectoryConfiguration con lo scenario 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>

Recuperare i risultati

Questo esempio recupera i risultati di una richiesta di configurazione o inventario:

Richiesta:

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

Risposta:

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

Condividi tramite

Estendibilità della configurazione dichiarata

Creare le risorse di configurazione dello stato desiderate

Provider MI di esempio

Passaggio 1: Creare il file MOF dello schema di risorse

Passaggio 2: Copiare i file MOF dello schema

Passaggio 3: Modificare i file necessari

Passaggio 4: Eseguire lo strumento generatore di provider

Passaggio 5: Copiare i file di origine generati

Informazioni sulla `MSFT_FileDirectoryConfiguration` risorsa

Circa `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`

Documento WinDC

Esempi di SyncML

Richiesta di configurazione

Richiesta di inventario

Recuperare i risultati

Riferimenti all'implementazione mi

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Estendibilità della configurazione dichiarata

Creare le risorse di configurazione dello stato desiderate

Provider MI di esempio

Passaggio 1: Creare il file MOF dello schema di risorse

Passaggio 2: Copiare i file MOF dello schema

Passaggio 3: Modificare i file necessari

Passaggio 4: Eseguire lo strumento generatore di provider

Passaggio 5: Copiare i file di origine generati

Informazioni sulla MSFT_FileDirectoryConfiguration risorsa

Circa MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource

Documento WinDC

Esempi di SyncML

Richiesta di configurazione

Richiesta di inventario

Recuperare i risultati

Riferimenti all'implementazione mi

Commenti e suggerimenti

Risorse aggiuntive

Informazioni sulla `MSFT_FileDirectoryConfiguration` risorsa

Circa `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`