Freigeben über

Anatomie einer befehlsbasierten DSC-Ressource

DSC-Ressourcen stellen eine standardisierte Schnittstelle für die Verwaltung der Einstellungen eines Systems bereit. Eine Ressource definiert Eigenschaften, die Sie verwalten können, und implementiert den Code, der zum Abrufen einer Instanz der Ressource erforderlich ist.

DSC-Befehlsressourcen werden mit mindestens zwei Dateien definiert:

  1. Ein DSC-Ressourcenmanifest, das DSC mitteilt, wie mit der Ressource interagiert werden soll.
  2. Eine oder mehrere ausführbare Dateien und deren Abhängigkeiten zum Verwalten von Instanzen der Ressource.

DSC-Ressourcenmanifeste

DSC-Ressourcenmanifeste werden als Datendateien definiert. Damit DSC eine Datendatei als Manifest erkennt, muss die Datei die folgenden Kriterien erfüllen:

  1. Die Daten in der Datei müssen als YAML oder JSON formatiert sein.

  2. Die Datei muss UTF-8-Codierung verwenden.

  3. Die Datei muss in der PATH Umgebungsvariablen auffindbar sein.

  4. Der Dateiname muss mit einer der folgenden Endungen enden:

    • .dsc.resource.json
    • .dsc.resource.yaml
    • .dsc.resource.yml

Wenn DSC das lokale System nach verfügbaren Befehlsressourcen durchsucht, durchsucht es jeden Ordner im PATH nach Dateien, die die Benennungskonvention für DSC-Ressourcenmanifeste verwenden. DSC analysiert dann jede dieser ermittelten Dateien und überprüft sie anhand des JSON-Schemas des DSC-Ressourcenmanifests.

Wenn die JSON-Datei anhand des Schemas überprüft wird, kann DSC die DSC-Ressource verwenden.

Das Manifest muss mindestens Folgendes definieren:

  • Die Version des JSON-Schemas des DSC-Ressourcenmanifests, mit der es kompatibel ist.
  • Der vollqualifizierte Name der Ressource, z. B Microsoft.Windows/Registry. . Die vollqualifizierte Namenssyntax lautet <owner>[.<group>][.<area>]/<name>. Die Gruppen- und Bereichskomponenten des vollqualifizierten Namens ermöglichen das Organisieren von Ressourcen in Namespaces.
  • Wie DSC den Befehl aufrufen kann, um den aktuellen Status einer Ressourceninstanz abzurufen.
  • Eine Möglichkeit, eine Instanz zu validieren. Zu den Optionen für die Validierung einer Instanz gehören:
    • Ein JSON-Schema, das eine Instanz beschreibt
    • Ein Befehl, den DSC aufrufen muss, um das Schema zur Laufzeit abzurufen
    • Ein Befehl zum Überprüfen geschachtelter DSC-Ressourcen. Diese letzte Option gilt nur für DSC-Gruppenressourcen und DSC-Adapterressourcen.

Das Manifest kann Folgendes definieren:

  • Die Art der Ressource, die das Manifest beschreibt: adapter, group, importeroder resource.

    Wenn das Manifest die Ressourcenart nicht definiert, wird standardmäßig eine typische Ressource verwendet resource , die eine Instanz direkt verwaltet, und als solche interpretiert.

  • Wie DSC den Befehl aufrufen kann, um zu testen, ob sich eine Instanz im gewünschten Zustand befindet.

    Wenn das Manifest nicht definiert, wie eine Instanz der Ressource getestet werden soll, führt DSC einen synthetischen Test für Ressourceninstanzen durch. Der synthetische Test von DSC ruft immer den tatsächlichen Zustand einer Instanz ab und führt einen strikten Vergleich der Eigenschaften der Instanz mit dem gewünschten Zustand durch, bei dem die Groß-/Kleinschreibung beachtet wird. Wenn eine der Eigenschaften nicht genau mit dem definierten gewünschten Zustand identisch ist, meldet DSC die Instanz als nicht konform.

  • Wie DSC den Befehl aufrufen kann, um eine Instanz in den gewünschten Zustand zu versetzen.

    Wenn das Manifest nicht definiert, wie eine Instanz der DSC-Ressource festgelegt wird, kann DSC die Ressource nicht verwenden, um den gewünschten Zustand zu erzwingen.

  • Die Bedeutung der Exit-Codes ungleich Null, die vom Befehl zurückgegeben werden.

    Wenn das Manifest die Bedeutung für Beendigungscodes nicht definiert, werden alle Beendigungscodes ungleich Null als generischer Fehler gemeldet.

  • Wie DSC den Befehl aufrufen kann, um eine Liste aller Instanzen dieser Ressource auf dem Computer zu exportieren.

  • Wie DSC den Befehl aufrufen kann, um eine bestimmte Instanz der Ressource zu löschen.

  • Metadaten über die Ressource, wie z. B. der Autor und eine kurze Beschreibung.

Das Manifest muss nicht für jeden Vorgang dieselbe ausführbare Datei angeben. Die Definition für jede Operation ist unabhängig.

Ausführbare Dateien für DSC-Ressourcen

Befehlsressourcen benötigen immer eine ausführbare Datei, damit DSC ausgeführt werden kann. Das Manifest muss nicht mit der ausführbaren Datei gebündelt werden. Bei der ausführbaren Datei kann es sich um eine beliebige ausführbare Datei handeln, z. B. eine Binäranwendung oder ein Shell-Skript. Eine Ressource kann unterschiedliche ausführbare Dateien für unterschiedliche Vorgänge verwenden.

Damit DSC eine ausführbare Datei verwenden kann, muss sie in der PATH Umgebungsvariablen auffindbar sein. DSC ruft die ausführbare Datei einmal pro Vorgang auf, wobei der von der ausführbaren Datei zurückgegebene Beendigungscode verwendet wird, um zu bestimmen, ob der Befehl erfolgreich war. DSC behandelt den Beendigungscode 0 als Erfolg und alle anderen Beendigungscodes als Fehler.

Eingänge

DSC sendet Eingaben auf eine der folgenden Arten an Befehlsressourcen:

  • Ein JSON-Datenblob über stdin.

    Wenn DSC die Eingabe als JSON über stdin sendet, ist das Datenblob die JSON-Darstellung des gewünschten Zustands einer Instanz. Diese Eingabeoption unterstützt komplexe Eigenschaften mit verschachtelten Objekten.

  • Ein JSON-Datenblob als Wert für ein bestimmtes Argument.

    Wenn die Ressource ein JSON-Eingabeargument definiert, ruft DSC den Befehl mit dem definierten Argument auf und übergibt die JSON-Darstellung des gewünschten Zustands einer Instanz an dieses Argument. Diese Eingabeoption unterstützt komplexe Eigenschaften mit verschachtelten Objekten.

  • Eine Reihe von Argumentflags und -werten.

    Wenn DSC die Eingabe als Argumente sendet, wird ein Argumentpaar für jede der angegebenen Eigenschaften generiert. Das erste Argument ist der Name der Eigenschaft mit --dem Präfix , z. B --duration. . . Das zweite Argument ist der Wert der Eigenschaft. Die Reihenfolge der Argumentpaare ist nicht garantiert. Diese Eingabemethode unterstützt keine komplexen Eigenschaften.

  • Umgebungsvariablen

    Wenn DSC die Eingabe als Umgebungsvariablen sendet, wird für jede Eigenschaft der Ressourceninstanz eine Umgebungsvariable definiert und der Wert auf die Zeichenfolgendarstellung dieser Eigenschaft festgelegt. Diese Umgebungsvariablen werden nur für die Ausführung des Befehls für diesen bestimmten Vorgang definiert. Die Umgebungsvariablen wirken sich nicht auf andere Prozesse aus.

Die Eingabebehandlung wird pro Vorgang im Ressourcenmanifest definiert. Eine Ressource kann eine andere Eingabebehandlung für die von ihr unterstützten Vorgänge definieren.

Ausgaben

Die ausführbare Datei für eine Befehlsressource muss JSON-Daten an stdout zurückgeben, wenn sie von DSC aufgerufen wird. Die Ausgabecodierung muss UTF-8 sein. Wenn die Ressource den Status einer Instanz zurückgibt, überprüft DSC die JSON-Daten anhand des Instanzschemas der Ressource.

Für Adapterressourcen erwartet DSC, dass die ausführbare Datei die Instanzzustände für die Ressourcen durchläuft, die sie entweder als einzelnes JSON-Array oder als eine Reihe von JSON-Zeilen verwaltet.

Befehlsressourcen können Protokollierungsinformationen an DSC melden, indem sie JSON-Zeilen an stderr ausgeben. Jeder Protokolleintrag muss ein JSON-Objekt sein, das zwei Schlüssel enthält:

  1. Der message Schlüssel definiert die für Menschen lesbare Zeichenfolge für den Protokolleintrag.
  2. Der level Schlüssel definiert, ob die Nachricht eine error, eine oder warninginformationeine darstellt.

DSC sammelt Meldungen von Ressourcen und zeigt sie in den Ergebnissen für einen Konfigurationsvorgang an. Wenn DSC eine Ressource direkt außerhalb einer Konfiguration aufruft, werden die Nachrichten nicht erfasst. Stattdessen gibt DSC die Nachrichten an stderr aus.

Verwandte Inhalte

  • Last updated on