Condividi tramite

Provider di estendibilità della configurazione dichiarati

La registrazione di configurazione dichiarata, che supporta lo stack client di configurazione dichiarato, offre estendibilità tramite provider WMI nativi. Questa funzionalità crea un'istanza e si interfaccia con un provider WMI (Windows Management Instrumentation) che ha implementato 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.

  1. Creare un file MOF 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.
  2. Copiare il file MOF dello schema insieme a tutti i file necessari nella directory degli strumenti del provider, ad esempio ProviderGenerationTool.
  3. Modificare i file necessari e includere i nomi di file e di classe corretti.
  4. Richiamare lo strumento generatore di provider per generare i file di progetto del provider.
  5. Copiare i file generati nella cartella del progetto del provider.
  6. Avviare il processo di sviluppo.

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

  1. Convalidare la risorsa di input.

  2. Verificare che le chiavi e i parametri necessari siano presenti.

  3. Creare un'istanza di risorsa usata come output del metodo Get. Questa istanza è di tipo MSFT_FileDirectoryConfiguration, derivato da MI_Instance.

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

  5. Pulire le risorse, ad esempio la memoria allocata gratuita.

Riferimenti all'implementazione mi