Aufbau einer befehlsbasierten DSC-Ressource

  • Artikel

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

Befehlsbasierte DSC-Ressourcen werden mit mindestens zwei Dateien definiert:

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

DSC-Ressourcenmanifeste

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

  1. Die Datei muss in der Umgebungsvariablen PATH auffindbar sein.
  2. Der Dateiname muss mit enden .dsc.resource.json.

Wenn DSC das lokale System nach verfügbaren befehlsbasierten DSC-Ressourcen durchsucht, durchsucht es jeden Ordner im nach PATH Dateien, die die Benennungskonvention des DSC-Ressourcenmanifests 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 dem 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 Zustand einer Ressource instance abzurufen.
  • Eine Möglichkeit zum Überprüfen eines instance. Folgende Möglichkeiten stehen zur Auswahl:
    • Ein JSON-Schema, das eine instance beschreibt
    • Ein DSC-Befehl muss aufrufen, 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-Anbieterressourcen.

Das Manifest kann optional Folgendes definieren:

  • Wie DSC den Befehl aufrufen kann, um zu testen, ob sich ein instance im gewünschten Zustand befindet.
  • Wie DSC den Befehl aufrufen kann, um einen instance auf den gewünschten Zustand festzulegen.
  • Die Bedeutung der vom Befehl zurückgegebenen Exitcodes ungleich null.
  • Wie DSC den Befehl aufrufen kann, um andere DSC-Ressourcen zu verwalten, wenn es sich bei der Ressource um eine DSC-Gruppenressource oder eine DSC-Anbieterressource handelt.
  • Metadaten zur Ressource, z. B. deren Autor und eine kurze Beschreibung.

Wenn das Manifest nicht definiert, wie eine instance der Ressource getestet werden soll, führt DSC einen synthetischen Test für Ressourceninstanzen durch. Der synthetische DSC-Test ruft immer den tatsächlichen Zustand eines instance ab und vergleicht die Eigenschaften der instance streng mit dem gewünschten Zustand. Der synthetische Test ignoriert alle Eigenschaften, denen ein Unterstrich (_) oder ein Dollarzeichen ($) vorangestellt ist. Wenn eine der Eigenschaften nicht genau mit dem definierten gewünschten Zustand identisch ist, meldet DSC die instance als nicht konform.

Wenn das Manifest nicht definiert, wie ein instance der DSC-Ressource festgelegt werden soll, kann DSC die Ressource nicht verwenden, um den gewünschten Zustand zu erzwingen.

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

Ausführbare DSC-Ressourcendateien

Befehlsbasierte DSC-Ressourcen erfordern immer eine ausführbare Datei, damit DSC ausgeführt werden kann. Das DSC-Ressourcenmanifest 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 Shellskript. 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 Umgebungsvariablen PATH auffindbar sein. DSC ruft die ausführbare Datei einmal pro Vorgang auf, wobei der von der ausführbaren Datei zurückgegebene Exitcode verwendet wird, um zu bestimmen, ob der Befehl erfolgreich war. DSC behandelt Exitcode 0 als Erfolg und alle anderen Exitcodes als Fehler.

Eingaben

DSC sendet Eingaben an befehlsbasierte DSC-Ressourcen entweder als JSON-Datenblob über stdin oder als Satz von Argumentflags und -werten. Die Eingabebehandlung wird pro Vorgang im DSC-Ressourcenmanifest definiert.

Wenn DSC die Eingabe als JSON über stdin sendet, ist das Datenblob die JSON-Darstellung des gewünschten Zustands eines instance. Dies ist die robusteste Option für eine Ressource, da sie es der Ressource ermöglicht, komplexe Eigenschaften mit geschachtelten Objekten zu unterstützen.

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

Ausgaben

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

Für DSC-Anbieterressourcen erwartet DSC, dass die ausführbare Datei die instance Zustände für die Ressourcen übergibt, die sie entweder als einzelnes JSON-Array oder als eine Reihe von JSON-Zeilen verwaltet.

Befehlsbasierte DSC-Ressourcen 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 lesbare Zeichenfolge für den Protokolleintrag.
  2. Der level Schlüssel definiert, ob die Nachricht ein Error- , oder WarningInformation- darstellt.

DSC sammelt Nachrichten aus 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 werden sie nur an stderr ausgegeben.

Verwandte Inhalte