Befehlsbasierte DSC-Ressourcenmanifestschemareferenz

Artikel
05/11/2024

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:

In der Umgebungsvariablen PATH erkennbar sein.
Entweder als JSON oder YAML formatiert werden.
Befolgen Sie die Namenskonvention <name>.dsc.resource.<extension>. Gültige Erweiterungen sind json, ymlund yaml.
Gelten Sie für das in diesem Dokument beschriebene Schema.

Im weiteren Verlauf dieses Dokuments wird das Schema des Manifests beschrieben.

Erforderliche Eigenschaften

Das Manifest muss die folgenden Eigenschaften enthalten:

$schema
type
version
get

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 es für die Validierung verwendet wird, muss der überprüfende Client dieses Schema und jedes Schema abrufen, auf das er verweist.
.../bundled/resource/manifest.json

Die URL zum gebündelten Schema. Wenn es für die Validierung verwendet wird, muss der überprüfende Client nur dieses Schema abrufen.

Dieses Schema verwendet das für das JSON-Schema 2020-12 eingeführte Bündelungsmodell. Obwohl DSC das Dokument weiterhin überprüfen kann, wenn dieses Schema verwendet wird, können andere Tools fehler- oder verhalten sich auf unerwartete Weise.
.../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. Obwohl DSC das Dokument weiterhin überprüfen kann, wenn dieses Schema verwendet wird, können andere Tools fehler- oder verhalten sich auf unerwartete Weise.

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
             ]

Typ

Die type -Eigenschaft stellt den vollqualifizierten Typnamen der Ressource dar. Sie wird verwendet, um die Ressource in Konfigurationsdokumenten und als Wert des --resource Flags anzugeben, wenn Sie die dsc resource * Befehle verwenden. Weitere Informationen zu Ressourcentypnamen finden Sie unter Referenz zu vollqualifizierten DSC-Ressourcennamensschemas.

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

version

Die version -Eigenschaft muss die aktuelle Version der Ressource als gültige semver-Zeichenfolge (semantische Version) 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-]+)*))?$

description

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

Type:     string
Required: false

kind

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

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

Wenn Sie eine Gruppenressource definieren, definieren Sie die kind Eigenschaft im Manifest immer explizit als Group.

Weitere Informationen finden Sie unter Referenz zum DSC-Ressourcentypschema.

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

Export

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

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

Der Wert dieser Eigenschaft muss ein -Objekt sein. Die -Eigenschaft des executable Objekts, die den Namen des aufzurufenden Befehls definiert, ist obligatorisch. Die args-Eigenschaft ist optional. Weitere Informationen finden Sie unter Referenz zum DSC-Ressourcenmanifest zum Exportieren von Eigenschaftenschemas.

Type:     object
Required: true

get

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

Der Wert dieser Eigenschaft muss ein -Objekt sein. Die -Eigenschaft des executable Objekts, die den Namen des aufzurufenden Befehls definiert, ist obligatorisch. Die args Eigenschaften und input sind optional. Weitere Informationen finden Sie unter Referenz zum Abrufen von Eigenschaftenschemas für das DSC-Ressourcenmanifest.

Type:     object
Required: true

set

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

Der Wert dieser Eigenschaft muss ein -Objekt sein. Die executable -Eigenschaft, die den Namen des aufzurufenden Befehls definiert, ist obligatorisch. Die argsinputEigenschaften , implementsPretestund returns sind optional. Weitere Informationen finden Sie unter DSC Resource Manifest Set Property Schema Reference.

Type:     object
Required: false

test

Die test -Eigenschaft definiert, wie die Ressource aufgerufen wird, um zu testen, ob sich ein instance im gewünschten Zustand befindet. Außerdem wird definiert, wie die Ausgabe 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 durch.

Der Wert dieser Eigenschaft muss ein -Objekt sein. Die -Eigenschaft des executable Objekts, die den Namen des aufzurufenden Befehls definiert, ist obligatorisch. Die argsinputEigenschaften , und returns sind optional. Weitere Informationen finden Sie unter Referenz zum DSC-Ressourcenmanifest– Testeigenschaftenschema.

Type:     object
Required: false

validate

Die validate -Eigenschaft definiert, wie eine DSC-Gruppenressource aufgerufen wird, um deren 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 -Eigenschaft des executable Objekts, die den Namen des aufzurufenden Befehls definiert, ist obligatorisch. Die args-Eigenschaft ist optional. Weitere Informationen finden Sie unter Referenz zu DSC-Ressourcenmanifest zur Überprüfung des Eigenschaftenschemas.

Type:     object
Required: false

Provider

Bei Angabe definiert die provider -Eigenschaft die Ressource als DSC-Ressourcenanbieter.

Der Wert dieser Eigenschaft muss ein -Objekt sein. Die Eigenschaften des list Objekts und config sind obligatorisch. Die list -Eigenschaft definiert, wie der Anbieter aufgerufen wird, um die Ressourcen zurückzugeben, die der Anbieter verwalten kann. Die config -Eigenschaft definiert, wie der Anbieter eine Eingabe erwartet. Weitere Informationen finden Sie in der Referenz zu DSC-Ressourcenmanifestanbietereigenschaften.

Beendigungswerte

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

Der Schlüssel ist eine Zeichenfolge mit einer ganzzahligen Vorzeichen, die einem bekannten Exitcode für die Ressource zugeordnet ist. Der Exitcode muss eine ganze Literal-Ganzzahl mit Vorzeichen sein. Sie können keine alternativen Formate für den Exitcode verwenden. Geben Sie beispielsweise anstelle des Hexadezimalwerts 0x80070005 für "Zugriff verweigert" den Exitcode als -2147024891an.
Der Wert ist eine Zeichenfolge, die die semantische Bedeutung dieses Exitcodes für einen menschlichen Leser beschreibt.

DSC interpretiert Exitcode 0 als erfolgreichen Vorgang und jeden anderen Exitcode als Fehler.

Tipp

Wenn Sie Ihr Ressourcenmanifest in yaml erstellen, stellen Sie sicher, dass Sie den Exitcode in einzelne Anführungszeichen umschließen, um sicherzustellen, dass die YAML-Datei ordnungsgemäß analysiert werden kann. 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 instance 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 Referenz zu DSC-Ressourcenmanifestschemaeigenschaften.

Type:     object
Required: true

Share via