Deklarierte Konfigurationserweiterbarkeit

• Gilt für::

  ✅ Windows 11, ✅ Windows 10

Die Windows-Registrierung für deklarierte Konfiguration (Windows Declared Configuration, WinDC) bietet Erweiterbarkeit über native WMI-Anbieter. Dieses Feature instanziiert und stellt Schnittstellen mit einem WMI-Anbieter (Windows Management Instrumentation) her, der eine Verwaltungsinfrastrukturschnittstelle (MI) implementiert. Die Schnittstelle muss die Methoden GetTargetResource, TestTargetResource und SetTargetResource implementieren und kann eine beliebige Anzahl von Zeichenfolgeneigenschaften implementieren.

Hinweis

Derzeit werden nur Zeichenfolgeneigenschaften von Erweiterbarkeitsanbietern unterstützt.

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

Erstellen von Ressourcen für die Konfiguration des gewünschten Zustands

Führen Sie zum Erstellen eines nativen WMI-Anbieters die unter Implementieren eines MI-Anbieters beschriebenen Schritte aus. In diesen Schritten wird beschrieben, wie Sie den Quellcode für eine MI-Schnittstelle mithilfe des Convert-MofToProvider.exe Tools generieren, um die DLL zu generieren und für die Platzierung vorzubereiten.

1. Erstellen Sie eine MOF-Datei (Managed Object Format), die das Schema für die gewünschte Zustandskonfigurationsressource einschließlich Parametern und Methoden definiert. Diese Datei enthält die erforderlichen Parameter für die Ressource.
2. Kopieren Sie die SCHEMA-MOF-Datei zusammen mit allen erforderlichen Dateien in das Verzeichnis der Anbietertools, z. B. ProviderGenerationTool.
3. Bearbeiten Sie die erforderlichen Dateien, und fügen Sie die richtigen Dateinamen und Klassennamen ein.
4. Rufen Sie das Anbietergeneratortool auf, um die Projektdateien des Anbieters zu generieren.
5. Kopieren Sie die generierten Dateien in den Projektordner des Anbieters.
6. Starten Sie den Entwicklungsprozess.

Beispiel für einen MI-Anbieter

Dieses Beispiel enthält weitere Details zu den einzelnen Schritten, um zu veranschaulichen, wie eine native Beispielressource namens implementiert wird MSFT_FileDirectoryConfiguration.

Schritt 1: Erstellen der MOF-Datei des Ressourcenschemas

Erstellen Sie eine MOF-Beispielschemadatei, die zum Generieren des anfänglichen Quellcodes für die MSFT_FileDirectoryConfiguration native Ressource verwendet wird. Platzieren Sie es im Projektverzeichnis mit dem Namen 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
    );
};

Hinweis

• Der Klassenname und der DLL-Dateiname sollten identisch sein, wie in der Provider.DEF Datei definiert.

• Der Typqualifizierer [Key] für eine Eigenschaft gibt an, dass er die Ressource eindeutig identifiziert instance. Mindestens eine [Key] Eigenschaft ist erforderlich.

• Der [Required] Qualifizierer gibt an, dass die -Eigenschaft erforderlich ist. Anders ausgedrückt: In jedem Konfigurationsskript, das diese Ressource verwendet, muss ein Wert angegeben werden.

• Der [write] Qualifizierer gibt an, dass die Eigenschaft optional ist, wenn die benutzerdefinierte Ressource in einem Konfigurationsskript verwendet wird. Der [read] Qualifizierer gibt an, dass eine Eigenschaft nicht durch eine Konfiguration festgelegt werden kann, und dient nur zu Berichtszwecken.

• Der [Values] Qualifizierer schränkt die Werte ein, die der Eigenschaft zugewiesen werden können. Definieren Sie die Liste der zulässigen Werte in [ValueMap]. Weitere Informationen finden Sie unter ValueMap- und Wertqualifizierer.

• Jede neue MOF-Datei sollte die folgenden Zeilen am Anfang der Datei enthalten:

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

• Methodennamen und die zugehörigen Parameter sollten für jede Ressource identisch sein. Ändern Sie MSFT_FileDirectoryConfiguration vom EmbeddedInstance-Wert in den Klassennamen des gewünschten Anbieters. Pro MOF-Datei sollte nur ein Anbieter vorhanden sein.

Schritt 2: Kopieren der MOF-Schemadateien

Kopieren Sie diese erforderlichen Dateien und Ordner in das Projektverzeichnis, das Sie in Schritt 1 erstellt haben:

• 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

Weitere Informationen zum Abrufen der erforderlichen Dateien finden Sie unter Implementieren eines MI-Anbieters.

Schritt 3: Bearbeiten der erforderlichen Dateien

Ändern Sie die folgenden Dateien im Projektverzeichnis:

• MSFT_FileDirectoryConfiguration.mof: Sie haben diese Datei in Schritt 1 erstellt.

• Provider.DEF: Diese Datei enthält den DLL-Namen, z. B MSFT_FileDirectoryConfiguration.dll. .

• codegen.cmd: Diese Datei enthält den Befehl zum Aufrufen convert-moftoprovider.exevon .

  "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
  

Schritt 4: Ausführen des Anbietergeneratortools

Führen Sie codegen.cmdaus, wodurch der convert-moftoprovider.exe Befehl ausgeführt wird. Alternativ können Sie den Befehl direkt ausführen.

Schritt 5: Kopieren der generierten Quelldateien

Der Befehl in Schritt 3 gibt den -OutPath Parameter an, der in diesem Beispiel ein Ordner namens tempist. Wenn Sie das Tool in Schritt 4 ausführen, werden neue Dateien in diesem Ordner erstellt. Kopieren Sie die generierten Dateien aus diesem temp Ordner in das Projektverzeichnis. Sie haben das Projektverzeichnis in Schritt 1 erstellt, das in diesem Beispiel ist MSFT_FileDirectoryConfiguration.

Hinweis

Führen Sie jedes Mal, wenn Sie die MOF-Schemadatei aktualisieren, das codegen.cmd Skript aus, um die Quelldateien erneut zu generieren. Beim erneuten Ausführen des Generatortools werden alle vorhandenen Quelldateien überschrieben. Um dieses Verhalten zu verhindern, wird in diesem Beispiel ein temporärer Ordner verwendet. Minimieren Sie Aktualisierungen der SCHEMA-MOF-Datei, da die Standard Implementierung mit den neuesten automatisch generierten Quelldateien zusammengeführt werden sollte.

Informationen zur MSFT_FileDirectoryConfiguration Ressource

Nachdem Sie das Anbietergeneratortool ausgeführt haben, werden mehrere Quell- und Headerdateien erstellt:

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

In dieser Liste müssen Sie nur und MSFT_FileDirectoryConfiguration.händernMSFT_FileDirectoryConfiguration.c. Sie können auch die Erweiterung für die Quelldateien von .c in .cppändern, was für diese Ressource der Fall ist. Die Geschäftslogik für diese Ressource wird in MSFT_FileDirectoryConfigurationImp.cpp und MSFT_FileDirectoryConfigurationImp.himplementiert. Diese neuen Dateien werden dem MSFT_FileDirectoryConfiguration Projektverzeichnis hinzugefügt, nachdem Sie das Anbietergeneratortool ausgeführt haben.

Für eine native Ressource für die Konfiguration des gewünschten Zustands müssen Sie drei automatisch generierte Funktionen in MSFT_FileDirectoryConfiguration.cppimplementieren:

• MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource
• MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource
• MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource

Von diesen drei Funktionen ist nur MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource für ein Get-Szenario erforderlich. MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource und MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource werden verwendet, wenn eine Korrektur erforderlich ist.

Es gibt mehrere andere automatisch generierte Funktionen in MSFT_FileDirectoryConfiguration.cpp , die keine Implementierung für eine native Ressource für die Konfiguration des gewünschten Zustands benötigen. Sie müssen die folgenden Funktionen nicht ändern:

• MSFT_FileDirectoryConfiguration_Load
• MSFT_FileDirectoryConfiguration_Unload
• MSFT_FileDirectoryConfiguration_EnumerateInstances
• MSFT_FileDirectoryConfiguration_GetInstance
• MSFT_FileDirectoryConfiguration_CreateInstance
• MSFT_FileDirectoryConfiguration_ModifyInstance
• MSFT_FileDirectoryConfiguration_DeleteInstance

Über MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource

Die MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource Funktion führt die folgenden Schritte aus, um ihre Aufgabe abzuschließen:

1. Überprüfen Sie die Eingaberessource.

2. Stellen Sie sicher, dass die Schlüssel und die erforderlichen Parameter vorhanden sind.

3. Erstellen Sie eine Ressource instance, die als Ausgabe der Get-Methode verwendet wird. Dieser instance ist vom Typ MSFT_FileDirectoryConfiguration, der von MI_Instanceabgeleitet wird.

4. Erstellen Sie die Ausgaberessource instance aus dem geänderten Ressourcen-instance, und geben Sie sie an den MI-Client zurück, indem Sie diese Funktionen aufrufen:

   • MSFT_FileDirectoryConfiguration_GetTargetResource_Construct
   • MSFT_FileDirectoryConfiguration_GetTargetResource_SetPtr_OutputResource
   • MSFT_FileDirectoryConfiguration_GetTargetResource_Set_MIReturn
   • MSFT_FileDirectoryConfiguration_GetTargetResource_Post
   • MSFT_FileDirectoryConfiguration_GetTargetResource_Destruct

5. Bereinigen von Ressourcen, z. B. Freigeben von zugeordnetem Arbeitsspeicher.

WinDC-Dokument

Wichtig

Das Ziel der Szenarioeinstellungen kann aus Gründen der Erweiterbarkeit nur geräteweit sein. Der in <LocURI> und WinDC-Kontext definierte CSP-Bereich muss sein.Device

Der Wert des Document Blattknotens im CSP DeclaredConfiguration ist ein XML-Dokument, das die Anforderung beschreibt. Hier sehen Sie ein WinDC-Beispieldokument mit den Konfigurationsdaten, die zur Erweiterbarkeit angegeben sind.

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

Es können nur unterstützte Werte für osdefinedscenario verwendet werden. Nicht unterstützte Werte führen zu einer Fehlermeldung ähnlich Invalid scenario nameder .

osdefinedscenario	Beschreibung
MSFTExtensibilityMIProviderConfig	Wird zum Konfigurieren von MI-Anbietereinstellungen verwendet.
MSFTExtensibilityMIProviderInventory	Wird zum Abrufen von Mi-Anbietereinstellungswerten verwendet.

Sowohl als MSFTExtensibilityMIProviderInventory auch MSFTExtensibilityMIProviderConfig Szenarien, die die gleichen Tags und Attribute erfordern.

• Das <DSC> XML-Tag beschreibt den WMI-Zielanbieter, der durch einen Namespace und klassennamen ausgedrückt wird, zusammen mit den Werten, die entweder auf das Gerät angewendet oder vom MI-Anbieter abgefragt werden sollen.

  Dieses Tag weist die folgenden Attribute auf:

  Attribut	Beschreibung
  namespace	Gibt den Zielnamespace des MI-Anbieters an.
  classname	Der zielorientierte MI-Anbieter.

• Das <Key> XML-Tag beschreibt den erforderlichen Parameternamen und -wert. Es benötigt nur einen Wert für die Konfiguration. Der Name ist ein Attribut, und der Wert ist <Key> content.

  Dieses Tag weist die folgenden Attribute auf:

  Attribut	Beschreibung
  name	Gibt den Namen eines MI-Anbieterparameters an.

• Das <Value> XML-Tag beschreibt den optionalen Parameternamen und -wert. Es benötigt nur einen Wert für die Konfiguration. Der Name ist ein Attribut, und der Wert ist <Value> content.

  Dieses Tag weist die folgenden Attribute auf:

  Attribut	Beschreibung
  name	Gibt den Namen eines MI-Anbieterparameters an.

SyncML-Beispiele

Die Standardmäßige OMA-DM SyncML-Syntax wird verwendet, um die DeclaredConfiguration-CSP-Vorgänge wie Ersetzen, Hinzufügen und Löschen anzugeben. Die Nutzlast des SyncML-Elements <Data> muss XML-codiert sein. Für diese XML-Codierung gibt es verschiedene Onlineencoder, die Sie verwenden können. Um die Codierung der Nutzlast zu vermeiden, können Sie den CDATA-Abschnitt verwenden, wie in den folgenden SyncML-Beispielen gezeigt.

Konfigurationsanforderung

In diesem Beispiel wird veranschaulicht, wie Sie eine Konfigurationsanforderung mithilfe des MSFT_FileDirectoryConfiguration MI-Anbieters mit dem MSFTExtensibilityMIProviderConfig Szenario senden.

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

Bestandsanforderung

In diesem Beispiel wird veranschaulicht, wie eine Bestandsanforderung mithilfe des MSFT_FileDirectoryConfiguration MI-Anbieters mit dem Szenario MSFTExtensibilityMIProviderInventory gesendet wird.

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

Abrufen von Ergebnissen

In diesem Beispiel werden die Ergebnisse einer Konfigurations- oder Bestandsanforderung abgerufen:

Anforderung:

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

Antwort:

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

MI-Implementierungsreferenzen

• Verwaltungsinfrastruktur-API (MI)
• MI-Anbieter (1) – Übersicht
• MI-Anbieter (2): Schema definieren
• MI-Anbieter (3): Generieren von Code
• MI-Anbieter (4) – Generieren von Code (Weiter)
• MI-Anbieter (5): Implementieren
• MI-Anbieter (6): Erstellen, Registrieren und Debuggen
• MI-Schnittstellen
• MI-Datentypen
• MI-Strukturen und -Gewerkschaften
• MI_Result-Enumeration (mi.h)
• MI_Type-Enumeration (mi.h)