Befehlsbasierte DSC-Ressourcenmanifestschemareferenz

  • Artikel

Zusammenfassung

Die Datendatei, die eine befehlsbasierte DSC-Ressource definiert.

Metadaten

SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json
Type:          object

Beschreibung

Jede befehlsbasierte DSC-Ressource muss über ein Manifest verfügen. Die Manifestdatei muss:

  1. In der PATH Umgebungsvariablen auffindbar sein.
  2. Als JSON oder YAML formatiert werden.
  3. Folgen Sie der Benennungskonvention <name>.dsc.resource.<extension>. Gültige Erweiterungen umfassen json, ymlund yaml.
  4. Gültig für das in diesem Dokument beschriebene Schema.

Im restlichen Dokument wird das Schema des Manifests beschrieben.

Erforderliche Eigenschaften

Das Manifest muss die folgenden Eigenschaften enthalten:

Eigenschaften

$schema

Die $schema-Eigenschaft gibt den kanonischen URI dieses Schemas an, für den das Manifest überprüft wird. Diese Eigenschaft ist obligatorisch. DSC verwendet diesen Wert, um das Manifest anhand des richtigen JSON-Schemas zu überprüfen.

Für jede Version des Schemas gibt es drei gültige URLs:

  • .../resource/manifest.json

    Die URL zum kanonischen nicht gebündelten Schema. Wenn er für die Überprüfung verwendet wird, muss der validierende Client dieses Schema und jedes Schema abrufen, auf das es verweist.

  • .../bundled/resource/manifest.json

    Die URL zum gebündelten Schema. Wenn er für die Überprüfung verwendet wird, muss der validierende Client dieses Schema nur abrufen.

    Dieses Schema verwendet das für JSON-Schema 2020-12 eingeführte Bündelungsmodell. Während DSC das Dokument weiterhin überprüfen kann, wenn es dieses Schema verwendet, können andere Tools auf unerwartete Weise fehlern oder verhalten.

  • .../bundled/resource/manifest.vscode.json

    Die URL zum erweiterten Erstellungsschema. Dieses Schema ist viel größer als die anderen Schemas, da es zusätzliche Definitionen enthält, die kontextbezogene Hilfe und Codeausschnitte bereitstellen, die die anderen nicht enthalten.

    Dieses Schema verwendet Schlüsselwörter, die nur von VS Code erkannt werden. Während DSC das Dokument weiterhin überprüfen kann, wenn es dieses Schema verwendet, können andere Tools auf unerwartete Weise fehlern oder verhalten.

Type:        string
Required:    true
Format:      URI
ValidValues: [
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json
             ]

Art

Die type-Eigenschaft stellt den vollqualifizierten Typnamen der Ressource dar. Es wird verwendet, um die Ressource in Konfigurationsdokumenten und als Wert des --resource Flags bei Verwendung der dsc resource *-Befehle anzugeben. Weitere Informationen zu Ressourcentypnamen finden Sie unter DSC Resource fully qualified type name schema reference.

Type:     string
Required: true
Pattern:  ^\w+(\.\w+){0,2}\/\w+$

Version

Die eigenschaft version muss die aktuelle Version der Ressource als gültige semantische Version (Semver)-Zeichenfolge sein. Die Version gilt für die Ressource, nicht für die von ihr verwaltete Software.

Type:     string
Required: true
Pattern:  ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

Beschreibung

Die eigenschaft description definiert eine Synopsis für den Zweck der Ressource. Der Wert für diese Eigenschaft muss eine kurze Zeichenfolge sein.

Type:     string
Required: false

Art

Die eigenschaft kind definiert, wie DSC die Ressource behandeln soll. DSC unterstützt drei Arten von befehlsbasierten DSC-Ressourcen: Resource, Groupund Adapter.

Wenn kind im Ressourcenmanifest nicht definiert ist, leitet DSC den Wert für die Eigenschaft ab. Wenn die eigenschaft adapter im Ressourcenmanifest definiert ist, leitet DSC den Wert von kind als Adapterab. Wenn die adapter-Eigenschaft nicht definiert ist, leitet DSC den Wert von kind als Resourceab. DSC kann nicht ableiten, ob ein Manifest für eine Gruppenressource ist.

Definieren Sie beim Definieren einer Gruppenressource immer explizit die eigenschaft kind im Manifest als Group.

Weitere Informationen finden Sie unter DSC Resource kind schema reference.

Type:        string
Required:    false
ValidValues: [Resource, Adapter, Group]

Schilder

Die tags-Eigenschaft definiert eine Liste der durchsuchbaren Ausdrücke für die Ressource. Der Wert dieser Eigenschaft muss ein Array von Zeichenfolgen sein. Jedes Tag darf nur alphanumerische Zeichen und Unterstriche enthalten. Es sind keine anderen Zeichen zulässig. Jedes Tag muss eindeutig sein.

Type:              array
Required:          false
ItemsMustBeUnique: true
ItemsType:         string
ItemsPattern:      ^\w+$

exportieren

Die export-Eigenschaft definiert, wie die Ressource aufgerufen wird, um den aktuellen Zustand jeder Instanz abzurufen. Wenn diese Eigenschaft definiert ist, können Benutzer:

  • Geben Sie eine Instanz der Ressource in der Eingabekonfiguration für den dsc config export Befehl an, um ein verwendbares Konfigurationsdokument zu generieren.
  • Geben Sie die Ressource mit dem Befehl dsc-Ressourcenexport an, um ein Konfigurationsdokument zu generieren, das jede Instanz der Ressource definiert.
  • Geben Sie die Ressource mit der dsc-Ressource abrufen Befehl und die Option --all- an, um den aktuellen Zustand für jede Instanz der Ressource zurückzugeben.

Der Wert dieser Eigenschaft muss ein Objekt sein. Die executable-Eigenschaft des Objekts, die den Namen des aufrufenden Befehls definiert, ist obligatorisch. Die args-Eigenschaft ist optional. Weitere Informationen finden Sie unter DSC Resource manifest property schema reference.

Type:     object
Required: true

Erhalten

Die get-Eigenschaft definiert, wie die Ressource aufgerufen wird, um den aktuellen Zustand einer Instanz abzurufen. Diese Eigenschaft ist für alle Ressourcen obligatorisch.

Der Wert dieser Eigenschaft muss ein Objekt sein. Die executable-Eigenschaft des Objekts, die den Namen des aufrufenden Befehls definiert, ist obligatorisch. Die eigenschaften args und input sind optional. Weitere Informationen finden Sie unter DSC Resource manifest get property schema reference.

Type:     object
Required: true

Garnitur

Die set-Eigenschaft definiert, wie die Ressource aufgerufen wird, um den gewünschten Zustand einer Instanz festzulegen. Außerdem wird definiert, wie die Ausgabe aus der Ressource für diese Methode verarbeitet wird. Wenn diese Eigenschaft nicht definiert ist, kann der DSC keine Instanzen der Ressource verwalten. Er kann nur den aktuellen Zustand abrufen und testen, ob sich die Instanz im gewünschten Zustand befindet.

Der Wert dieser Eigenschaft muss ein Objekt sein. Die executable-Eigenschaft, die den Namen des aufrufenden Befehls definiert, ist obligatorisch. Die Eigenschaften argsinput, implementsPretestund returns sind optional. Weitere Informationen finden Sie unter DSC Resource manifest set property schema reference.

Type:     object
Required: false

whatIf

Definiert, wie DSC die DSC-Ressource aufrufen muss, um anzugeben, ob und wie der Set-Befehl eine Instanz ändert und wie die Ausgabe aus der DSC-Ressource verarbeitet wird. Wenn eine Ressource diese Methode im Manifest nicht definiert, synthetisiert DSC dieses Verhalten, indem das Ergebnis des Testvorgangs für die Ressource in das Setergebnis konvertiert wird.

Der Wert dieser Eigenschaft muss ein Objekt sein. Die executable-Eigenschaft, die den Namen des aufrufenden Befehls definiert, ist obligatorisch. Die Eigenschaften argsinput, implementsPretestund returns sind optional. Weitere Informationen finden Sie unter DSC Resource manifest whatIf property schema reference.

Test

Die eigenschaft test definiert, wie die Ressource aufgerufen wird, um zu testen, ob sich eine Instanz im gewünschten Zustand befindet. Außerdem wird definiert, wie die Ausgabe aus der Ressource für diese Methode verarbeitet wird. Wenn diese Eigenschaft nicht definiert ist, führt DSC einen grundlegenden synthetischen Test für Instanzen der DSC-Ressource aus.

Der Wert dieser Eigenschaft muss ein Objekt sein. Die executable-Eigenschaft des Objekts, die den Namen des aufrufenden Befehls definiert, ist obligatorisch. Die eigenschaften argsinputund returns sind optional. Weitere Informationen finden Sie unter DSC Resource manifest test property schema reference.

Type:     object
Required: false

validieren

Die validate-Eigenschaft definiert, wie eine DSC-Gruppenressource aufgerufen wird, um ihre Instanzen zu überprüfen. Diese Eigenschaft ist für DSC-Gruppenressourcen obligatorisch. DSC ignoriert diese Eigenschaft für alle anderen Ressourcen.

Der Wert dieser Eigenschaft muss ein Objekt sein. Die executable-Eigenschaft des Objekts, die den Namen des aufrufenden Befehls definiert, ist obligatorisch. Die args-Eigenschaft ist optional. Weitere Informationen finden Sie unter DSC Resource manifest validate property schema reference.

Type:     object
Required: false

Anbieter

Wenn angegeben, definiert die provider-Eigenschaft die Ressource als DSC-Ressourcenanbieter.

Der Wert dieser Eigenschaft muss ein Objekt sein. Die list und config Eigenschaften des Objekts sind obligatorisch. Die list-Eigenschaft definiert, wie der Anbieter aufgerufen wird, um die vom Anbieter verwalteten Ressourcen zurückzugeben. Die config-Eigenschaft definiert, wie der Anbieter Eingaben erwartet. Weitere Informationen finden Sie in der DSC-Ressourcenmanifestanbieter-Eigenschaftsschemareferenz.

exitCodes

Die exitCodes-Eigenschaft definiert einen Satz gültiger Ausgangscodes für die Ressource und deren Bedeutung. Definieren Sie diese Eigenschaft als Satz von Schlüssel-Wert-Paaren, wobei:

  • Der Schlüssel ist eine Zeichenfolge mit einer signierten ganzzahligen Zahl, die einem bekannten Ausgangscode für die Ressource zugeordnet ist. Der Ausgangscode muss eine literale ganze Zahl sein. Sie können keine alternativen Formate für den Ausgangscode verwenden. Geben Sie z. B. anstelle des Hexadezimalwerts 0x80070005 für "Zugriff verweigert" den Ausgangscode als -2147024891an.
  • Der Wert ist eine Zeichenfolge, die die semantische Bedeutung dieses Ausgangscodes für einen menschlichen Leser beschreibt.

DSC interpretiert Exit-Code 0 als erfolgreichen Vorgang und alle anderen Exit-Code als Fehler.

Trinkgeld

Wenn Sie Ihr Ressourcenmanifest in yaml erstellen, müssen Sie den Ausgangscode in einfache Anführungszeichen umschließen, um sicherzustellen, dass die YAML-Datei korrekt analysiert werden kann. Zum Beispiel:

exitCodes:
  '0': Success
  '1': Invalid parameter
  '2': Invalid input
  '3': Registry error
  '4': JSON serialization failed

Type:                object
Required:            false
PropertyNamePattern: ^-?[0-9]+#
PropertyValueType:   string

Schema

Die schema-Eigenschaft definiert, wie das JSON-Schema abgerufen wird, das eine Instanz der Ressource überprüft. Diese Eigenschaft muss immer ein Objekt sein, das eine der folgenden Eigenschaften definiert:

  • command – Wenn Sie die command-Eigenschaft angeben, ruft DSC den definierten Befehl auf, um das JSON-Schema abzurufen.
  • embedded – Wenn Sie die embedded-Eigenschaft angeben, verwendet DSC den definierten Wert als JSON-Schema.

Weitere Informationen finden Sie unter DSC Resource manifest schema property reference.

Type:     object
Required: true