Extensibilité de configuration déclarée

S’applique à: ✅ Windows 11, ✅ Windows 10

L’inscription windows de configuration déclarée (WinDC) offre une extensibilité via des fournisseurs WMI natifs. Cette fonctionnalité instancie et s’interface avec un fournisseur WMI (Windows Management Instrumentation) qui implémente une interface d’infrastructure de gestion (MI). L’interface doit implémenter les méthodes GetTargetResource, TestTargetResource et SetTargetResource, et peut implémenter n’importe quel nombre de propriétés de chaîne.

Remarque

Seules les propriétés de chaîne sont actuellement prises en charge par les fournisseurs d’extensibilité.

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

Créer des ressources de configuration d’état souhaité

Pour créer un fournisseur WMI natif, suivez les étapes décrites dans Comment implémenter un fournisseur MI. Ces étapes incluent la façon de générer le code source d’une interface MI à l’aide de l’outil Convert-MofToProvider.exe permettant de générer la DLL et de la préparer pour le placement.

Créez un fichier MOF (Managed Object Format) qui définit le schéma pour la ressource de configuration d’état souhaitée, y compris les paramètres et les méthodes. Ce fichier inclut les paramètres requis pour la ressource.
Copiez le fichier MOF de schéma avec tous les fichiers requis dans le répertoire des outils du fournisseur, par exemple : ProviderGenerationTool.
Modifiez les fichiers requis et incluez les noms de fichiers et de classes corrects.
Appelez l’outil générateur de fournisseurs pour générer les fichiers projet du fournisseur.
Copiez les fichiers générés dans le dossier de projet du fournisseur.
Démarrez le processus de développement.

Exemple de fournisseur MI

Cet exemple fournit plus de détails sur chaque étape pour montrer comment implémenter un exemple de ressource native nommée MSFT_FileDirectoryConfiguration.

Étape 1 : Créer le fichier MOF du schéma de ressources

Créez un exemple de fichier MOF de schéma utilisé pour générer le code source initial pour la MSFT_FileDirectoryConfiguration ressource native. Placez-le dans le répertoire du projet nommé 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
    );
};

Remarque

Le nom de la classe et le nom du fichier DLL doivent être identiques, comme défini dans le Provider.DEF fichier.
Le qualificateur [Key] de type sur une propriété indique qu’il identifie de manière unique la ressource instance. Au moins une [Key] propriété est requise.
Le [Required] qualificateur indique que la propriété est obligatoire. En d’autres termes, une valeur doit être spécifiée dans tout script de configuration qui utilise cette ressource.
Le [write] qualificateur indique que la propriété est facultative lors de l’utilisation de la ressource personnalisée dans un script de configuration. Le [read] qualificateur indique qu’une propriété ne peut pas être définie par une configuration et qu’elle sert uniquement à des fins de création de rapports.
Le [Values] qualificateur limite les valeurs qui peuvent être affectées à la propriété . Définissez la liste des valeurs autorisées dans [ValueMap]. Pour plus d’informations, consultez ValueMap et qualificateurs de valeur.

Tout nouveau fichier MOF doit inclure les lignes suivantes en haut du fichier :

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

Les noms de méthode et leurs paramètres doivent être identiques pour chaque ressource. Passez MSFT_FileDirectoryConfiguration de la valeur EmbeddedInstance au nom de classe du fournisseur souhaité. Il ne doit y avoir qu’un seul fournisseur par fichier MOF.

Étape 2 : Copier les fichiers MOF de schéma

Copiez ces fichiers et dossiers requis dans le répertoire du projet que vous avez créé à l’étape 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

Pour plus d’informations sur l’obtention des fichiers requis, consultez Comment implémenter un fournisseur mi.

Étape 3 : Modifier les fichiers requis

Modifiez les fichiers suivants dans le répertoire du projet :

MSFT_FileDirectoryConfiguration.mof: vous avez créé ce fichier à l’étape 1.
Provider.DEF: ce fichier contient le nom de la DLL, par exemple . MSFT_FileDirectoryConfiguration.dll

codegen.cmd: ce fichier contient la commande pour appeler 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

Étape 4 : Exécuter l’outil générateur de fournisseurs

Exécutez codegen.cmd, qui exécute la convert-moftoprovider.exe commande . Vous pouvez également exécuter la commande directement.

Étape 5 : Copier les fichiers sources générés

La commande de l’étape 3 spécifie le -OutPath paramètre , qui dans cet exemple est un dossier nommé temp. Lorsque vous exécutez l’outil à l’étape 4, il crée des fichiers dans ce dossier. Copiez les fichiers générés de ce temp dossier dans le répertoire du projet. Vous avez créé le répertoire du projet à l’étape 1, qui est MSFT_FileDirectoryConfigurationdans cet exemple .

Remarque

Chaque fois que vous mettez à jour le fichier MOF de schéma, exécutez le codegen.cmd script pour régénérer les fichiers sources. Le réexécution de l’outil générateur remplace tous les fichiers sources existants. Pour éviter ce comportement, cet exemple utilise un dossier temporaire. Réduisez les mises à jour du fichier MOF de schéma, car l’implémentation principale doit être fusionnée avec les fichiers sources générés automatiquement les plus récents.

À propos de la `MSFT_FileDirectoryConfiguration` ressource

Après avoir exécuté l’outil générateur de fournisseurs, il crée plusieurs fichiers source et d’en-tête :

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

À partir de cette liste, il vous suffit de modifier MSFT_FileDirectoryConfiguration.c et MSFT_FileDirectoryConfiguration.h. Vous pouvez également remplacer l’extension des fichiers sources par .c.cpp, ce qui est le cas pour cette ressource. La logique métier de cette ressource est implémentée dans MSFT_FileDirectoryConfigurationImp.cpp et MSFT_FileDirectoryConfigurationImp.h. Ces nouveaux fichiers sont ajoutés au répertoire du MSFT_FileDirectoryConfiguration projet après avoir exécuté l’outil générateur de fournisseurs.

Pour une ressource de configuration d’état souhaitée native, vous devez implémenter trois fonctions générées automatiquement dans MSFT_FileDirectoryConfiguration.cpp:

MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource
MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource
MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource

À partir de ces trois fonctions, seule MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource est requise pour un scénario Get. MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource et MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource sont utilisés quand une correction est nécessaire.

Il existe plusieurs autres fonctions générées automatiquement dans MSFT_FileDirectoryConfiguration.cpp qui n’ont pas besoin d’implémentation pour une ressource de configuration d’état souhaitée native. Vous n’avez pas besoin de modifier les fonctions suivantes :

MSFT_FileDirectoryConfiguration_Load
MSFT_FileDirectoryConfiguration_Unload
MSFT_FileDirectoryConfiguration_EnumerateInstances
MSFT_FileDirectoryConfiguration_GetInstance
MSFT_FileDirectoryConfiguration_CreateInstance
MSFT_FileDirectoryConfiguration_ModifyInstance
MSFT_FileDirectoryConfiguration_DeleteInstance

Environ `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`

La MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource fonction effectue les étapes suivantes pour effectuer sa tâche :

Validez la ressource d’entrée.
Vérifiez que les clés et les paramètres requis sont présents.
Créez une ressource instance utilisée comme sortie de la méthode Get. Cette instance est de type MSFT_FileDirectoryConfiguration, qui est dérivé de MI_Instance.
Créez la ressource de sortie instance à partir de la ressource modifiée instance et retournez-la au client MI en appelant ces fonctions :
- MSFT_FileDirectoryConfiguration_GetTargetResource_Construct
- MSFT_FileDirectoryConfiguration_GetTargetResource_SetPtr_OutputResource
- MSFT_FileDirectoryConfiguration_GetTargetResource_Set_MIReturn
- MSFT_FileDirectoryConfiguration_GetTargetResource_Post
- MSFT_FileDirectoryConfiguration_GetTargetResource_Destruct
Nettoyer les ressources, par exemple, libérer la mémoire allouée.

Document WinDC

Important

La cible des paramètres de scénario peut uniquement être à l’échelle de l’appareil pour l’extensibilité. L’étendue CSP définie dans et le <LocURI>contexte WinDC doit être Device.

La valeur du Document nœud feuille dans le csp DeclaredConfiguration est un document XML qui décrit la requête. Voici un exemple de document WinDC avec les données de configuration spécifiées pour l’extensibilité.

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

Seules les valeurs prises en charge pour osdefinedscenario peuvent être utilisées. Les valeurs non prises en charge entraînent un message d’erreur similaire à Invalid scenario name.

osdefinedscenario	Description
MSFTExtensibilityMIProviderConfig	Permet de configurer les paramètres du fournisseur mi.
MSFTExtensibilityMIProviderInventory	Utilisé pour récupérer les valeurs de paramètre du fournisseur mi.

Les scénarios MSFTExtensibilityMIProviderConfig et MSFTExtensibilityMIProviderInventory qui nécessitent les mêmes balises et attributs.

La <DSC> balise XML décrit le fournisseur WMI ciblé exprimé par un espace de noms et un nom de classe, ainsi que les valeurs à appliquer à l’appareil ou interrogées par le fournisseur mi.

Cette balise a les attributs suivants :

Attribut Description

namespace Spécifie l’espace de noms du fournisseur mi ciblé.

classname Fournisseur MI ciblé.
La <Key> balise XML décrit le nom et la valeur du paramètre requis. Il n’a besoin que d’une valeur pour la configuration. Le nom est un attribut et la valeur est <Key> content.

Cette balise a les attributs suivants :

Attribut Description

name Spécifie le nom d’un paramètre de fournisseur mi.
La <Value> balise XML décrit le nom et la valeur du paramètre facultatif. Il n’a besoin que d’une valeur pour la configuration. Le nom est un attribut et la valeur est <Value> content.

Cette balise a les attributs suivants :

Attribut Description

name Spécifie le nom d’un paramètre de fournisseur mi.

Attribut	Description
`namespace`	Spécifie l’espace de noms du fournisseur mi ciblé.
`classname`	Fournisseur MI ciblé.

Attribut	Description
`name`	Spécifie le nom d’un paramètre de fournisseur mi.

Attribut	Description
`name`	Spécifie le nom d’un paramètre de fournisseur mi.

Exemples SyncML

La syntaxe SyncML OMA-DM standard est utilisée pour spécifier les opérations CSP DeclaredConfiguration telles que Remplacer, Ajouter et Supprimer. La charge utile de l’élément syncML <Data> doit être encodée au format XML. Pour cet encodage XML, vous pouvez utiliser différents encodeurs en ligne. Pour éviter d’encoder la charge utile, vous pouvez utiliser la section CDATA , comme indiqué dans les exemples SyncML suivants.

Demande de configuration

Cet exemple montre comment envoyer une demande de configuration à l’aide du MSFT_FileDirectoryConfiguration fournisseur mi avec le MSFTExtensibilityMIProviderConfig scénario .

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

Demande d’inventaire

Cet exemple montre comment envoyer une demande d’inventaire à l’aide du fournisseur mi MSFT_FileDirectoryConfiguration avec le scénario 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>

Récupérer les résultats

Cet exemple récupère les résultats d’une demande de configuration ou d’inventaire :

Demande :

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

Réponse :

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

Références d’implémentation mi

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-08-04

Partager via

Extensibilité de configuration déclarée

Créer des ressources de configuration d’état souhaité

Exemple de fournisseur MI

Étape 1 : Créer le fichier MOF du schéma de ressources

Étape 2 : Copier les fichiers MOF de schéma

Étape 3 : Modifier les fichiers requis

Étape 4 : Exécuter l’outil générateur de fournisseurs

Étape 5 : Copier les fichiers sources générés

À propos de la MSFT_FileDirectoryConfiguration ressource

Environ MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource

Document WinDC

Exemples SyncML

Demande de configuration

Demande d’inventaire

Récupérer les résultats

Références d’implémentation mi

Commentaires

Ressources supplémentaires

À propos de la `MSFT_FileDirectoryConfiguration` ressource

Environ `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`