Referenz zum DSC-Konfigurationsdokumentschema

Artikel
05/11/2024

Zusammenfassung

Die YAML- oder JSON-Datei, die eine DSC-Konfiguration definiert.

Metadaten

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

Beschreibung

DSC-Konfigurationen ermöglichen Es Benutzern, den Zustand zu definieren, indem verschiedene DSC-Ressourcen kombiniert werden. Ein Konfigurationsdokument verwendet Parameter und Variablen, um an eine Gruppe von Ressourcen zu übergeben, die einen gewünschten Zustand definieren.

Ein Konfigurationsdokument kann entweder als YAML oder JSON definiert werden. Zur Vereinfachung der Erstellung empfiehlt Microsoft das Erstellen von Konfigurationsdokumenten in YAML.

Damit die Erstellungstools von DSC eine Datei als DSC-Konfigurationsdokument erkennen können, muss der Dateiname auf , .dsc.config.ymloder .dsc.config.yamlenden.dsc.config.json.

Sie können Konfigurationsdokumentfunktionen verwenden, um Werte im Dokument zur Laufzeit dynamisch zu bestimmen. Weitere Informationen finden Sie unter Referenz zu DSC-Konfigurationsdokumentfunktionen.

Im weiteren Verlauf dieses Dokuments wird das Schema beschrieben, das DSC zum Überprüfen von Konfigurationsdokumenten verwendet.

Beispiele

Erforderliche Eigenschaften

Jedes Konfigurationsdokument muss die folgenden Eigenschaften enthalten:

[$schema]
[Ressourcen]

Eigenschaften

$schema

Die $schema -Eigenschaft gibt die kanonische URL der Version dieses Schemas an, der das Dokument entspricht. DSC verwendet diese Eigenschaft beim Überprüfen des Konfigurationsdokuments vor konfigurationsvorgängen.

Es gibt derzeit 3 veröffentlichte Versionen des Schemas, die mit verschiedenen Versionen von DSC kompatibel sind:

2024/04 ist die neueste Version des Schemas, die mit DSC-Version 3.0.0-preview.7 und höher kompatibel ist.
2023/10 ist die vorherige Version des Schemas, kompatibel mit DSC-Versionen 3.0.0-alpha.4 und 3.0.0-alpha.5.
2023/08 ist die erste Version des Schemas, die mit DSC-Versionen 3.0.0-alpha.1 über 3.0.0-alpha.3kompatibel ist.

Diese Dokumentation unterliegt der neuesten Version des Schemas. Sie sollten Ihre Konfigurationsdokumente und Ressourcenmanifeste auf die neueste Version des Schemas aktualisieren. Frühere Versionen funktionieren nicht mit neuen Versionen von DSC. Die Schemas bleiben veröffentlicht, erhalten aber keine Updates.

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

.../config/document.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/config/document.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/config/document.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/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json
             ]

metadata

Die metadata -Eigenschaft definiert einen Satz von Schlüssel-Wert-Paaren als Anmerkungen für die Konfiguration. DSC überprüft die Metadaten nicht. Eine Konfiguration kann beliebige Informationen in dieser Eigenschaft enthalten.

Type:     object
Required: false

parameters

Die parameters -Eigenschaft definiert eine Reihe von Laufzeitoptionen für die Konfiguration. Jeder Parameter ist als Schlüssel-Wert-Paar definiert. Der Schlüssel für jedes Paar definiert den Namen des Parameters. Der Wert für jedes Paar muss ein Objekt sein, das die type Schlüsselwort (keyword) definiert, um anzugeben, wie DSC den Parameter verarbeiten soll.

Parameter können zur Laufzeit überschrieben werden, wodurch die Wiederverwendung desselben Konfigurationsdokuments für verschiedene Kontexte ermöglicht wird.

Weitere Informationen zum Definieren von Parametern in einer Konfiguration finden Sie unter DSC-Konfigurationsdokumentparameterschema.

Type:                object
Required:            false
ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.parameter.json

variables

Die variables -Eigenschaft definiert einen Satz wiederverwendbarer Werte für die Ressourcen im Dokument als Schlüssel-Wert-Paare. Der Schlüssel für jedes Paar definiert den Namen der Variablen. Ressourcen, die anhand des Namens auf die Variable verweisen, können auf den Wert der Variablen zugreifen.

Dies kann dazu beitragen, die Menge der kopierten Werte und Optionen für Ressourcen in der Konfiguration zu reduzieren, wodurch das Dokument einfacher zu lesen und zu verwalten ist. Im Gegensatz zu Parametern können Variablen nur in der Konfiguration definiert und zur Laufzeit nicht überschrieben werden.

Type:     object
Required: false

ressourcen

Die resources -Eigenschaft definiert eine Liste der DSC-Ressourceninstanzen, die von der Konfiguration verwaltet werden. Jede instance in der Liste muss eindeutig sein, aber Instanzen können denselben DSC-Ressourcentyp verwenden.

Weitere Informationen zum Definieren einer gültigen Ressourcen-instance in einer Konfiguration finden Sie unter Ressourcenschema des DSC-Konfigurationsdokuments.

Type:             array
Required:         true
MinimumItemCount: 1
ValidItemSchema:  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.resource.json

Freigeben über