Freigeben über

Referenz zu DSC-Ressourcenmanifestsatzeigenschaften

  • Artikel

Zusammenfassung

Definiert, wie der Zustand für eine DSC-Ressourcen-instance erzwungen wird.

Metadaten

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

Beschreibung

Um eine instance mit DSC zu verwalten, muss eine DSC-Ressource die Eigenschaft in ihrem set Manifest definieren. Diese Eigenschaft definiert, wie DSC den aktuellen Zustand einer instance erzwingen kann.

Wenn diese Eigenschaft nicht definiert ist, kann DSC nur den aktuellen Zustand von Instanzen abrufen und testen, ob sie sich im gewünschten Zustand befinden. DSC kann den gewünschten Zustand für die Ressource nicht erzwingen.

DSC sendet Daten auf drei Arten an den Befehl:

  1. Wenn input ist stdin, sendet DSC die Daten als Zeichenfolge, die die Daten als komprimiertes JSON-Objekt ohne Leerzeichen oder Neueinbrüche zwischen den Objekteigenschaften darstellt.
  2. Wenn input dies der Wert ist env, sendet DSC die Daten als Umgebungsvariablen. Es erstellt eine Umgebungsvariable für jede Eigenschaft im Eingabedatenobjekt, wobei der Name und der Wert der Eigenschaft verwendet werden.
  3. Wenn das args Array eine JSON-Eingabeargumentdefinition enthält, sendet DSC die Daten als Zeichenfolge, die die Daten als komprimiertes JSON-Objekt an das angegebene Argument darstellt.

Wenn Sie die input Eigenschaft nicht definieren und kein JSON-Eingabeargument definieren, kann DSC den Eingabe-JSON-Code nicht an die Ressource übergeben. Sie können nur ein JSON-Eingabeargument für einen Befehl definieren.

Sie müssen die input Eigenschaft, ein JSON-Eingabeargument im args Eigenschaftenarray oder beides definieren.

Beispiele

Beispiel 1: Vollständige Definition

Dieses Beispiel stammt aus der Microsoft.Windows/Registry DSC-Ressource.

"set": {
  "executable": "registry",
  "args": [
    "config",
    "set"
  ],
  "input":            "stdin",
  "implementsPretest": true,
  "return":           "state"
}

Sie definiert executable als registry, und registry.exenicht . Die Erweiterung ist nicht erforderlich, wenn das Betriebssystem den Befehl als ausführbare Datei erkennt.

Das Manifest definiert zwei Argumente und configset. Der Wert der input -Eigenschaft gibt an, dass der set Befehl seine Eingabe als JSON-Blob von stdinerwartet.

In Kombination mit dem Wert für executableruft DSC die set-Methode für diese Ressource auf, indem folgendes ausgeführt wird:

{ ... } | registry config set

Da das Manifest als definiert wirdimplementsPretest, ruft DSC die -Methode für die test Ressource nicht auf, bevor aufgerufen wirdset.true Diese Einstellung gibt an, dass die Ressource selbst Instanzen testet, bevor sie ihren gewünschten Zustand erzwingt.

Das Manifest definiert return als state, was angibt, dass es erst nach der Ausführung der Methode den endgültigen Zustand der set Ressource zurückgibt. DSC vergleicht den gewünschten Zustand mit den Rückgabedaten dieser Ressource, um zu ermitteln, welche der Eigenschaften der Ressource von der set Methode erzwungen wurde, falls vorhanden.

Erforderliche Eigenschaften

Die set Definition muss die folgenden Eigenschaften enthalten:

Eigenschaften

executable

Die executable -Eigenschaft definiert den Namen des auszuführenden Befehls. Der Wert muss der Name eines Befehls sein, der in der Umgebungsvariablen des PATH Systems ermittelt werden kann, oder der vollständige Pfad zum Befehl. Eine Dateierweiterung ist nur erforderlich, wenn der Befehl vom Betriebssystem nicht als ausführbare Datei erkennbar ist.

Type:     string
Required: true

args

Die args -Eigenschaft definiert die Liste der Argumente, die an den Befehl übergeben werden sollen. Die Argumente können eine beliebige Anzahl von Zeichenfolgen sein. Wenn Sie das JSON-Objekt, das den Eigenschaftenbehälter für die Ressource darstellt, an ein Argument übergeben möchten, können Sie ein einzelnes Element im Array als [JSON-Objekt] definieren, indem Sie den Namen des Arguments mit der jsonInputArg Zeichenfolgeneigenschaft angeben und angeben, ob das Argument für den Befehl mit der mandatory booleschen Eigenschaft obligatorisch ist.

Type:     array
Required: false
Default:  []
Type:     [string, object(JSON Input Argument)]

Zeichenfolgenargumente

Jedes Element im Argumentarray kann eine Zeichenfolge sein, die ein statisches Argument darstellt, das an den Befehl übergeben werden soll, z. B config . oder --format.

Type: string

JSON-Eingabeargument

Definiert ein Argument für den Befehl, der das JSON-Eingabeobjekt als Zeichenfolge akzeptiert. DSC übergibt die JSON-Eingabe an das benannte Argument, sofern verfügbar. Ein JSON-Eingabeargument wird als JSON-Objekt mit den folgenden Eigenschaften definiert:

  • jsonInputArg (erforderlich) – das Argument, an das die JSON-Daten für den Befehl übergeben werden sollen, z. B --input. .
  • mandatory (optional) – Geben Sie an, ob DSC das Argument immer an den Befehl übergeben soll, auch wenn keine JSON-Eingabe für den Befehl vorhanden ist. In diesem Fall übergibt DSC eine leere Zeichenfolge an das JSON-Eingabeargument.

Sie können nur ein JSON-Eingabeargument pro Argumentarray definieren.

Wenn Sie ein JSON-Eingabeargument und eine input Art für einen Befehl definieren, sendet DSC die JSON-Daten auf beide Arten:

  • Wenn Sie als env und ein JSON-Eingabeargument definiereninput, legt DSC eine Umgebungsvariable für jede Eigenschaft in der JSON-Eingabe fest und übergibt das JSON-Eingabeobjekt als Zeichenfolge an das definierte Argument.
  • Wenn Sie als stdin und ein JSON-Eingabeargument definiereninput, übergibt DSC die JSON-Eingabe über stdin und als Zeichenfolge an das definierte Argument.
  • Wenn Sie ein JSON-Eingabeargument definieren, ohne die input -Eigenschaft zu definieren, übergibt DSC die JSON-Eingabe nur als Zeichenfolge an das definierte Argument.

Wenn Sie die input Eigenschaft nicht definieren und kein JSON-Eingabeargument definieren, kann DSC den Eingabe-JSON-Code nicht an die Ressource übergeben. Dadurch ist das Manifest ungültig. Sie müssen die input Eigenschaft, ein JSON-Eingabeargument im args Eigenschaftenarray oder beides definieren.

Type:                object
RequiredProperties: [jsonInputArg]

input

Die input -Eigenschaft definiert, wie Eingaben an die Ressource übergeben werden. Wenn diese Eigenschaft nicht definiert ist und die Definition kein JSON-Eingabeargument definiert, sendet DSC beim Aufrufen des Vorgangs keine Eingabe an die set Ressource.

Der Wert dieser Eigenschaft muss eine der folgenden Zeichenfolgen sein:

  • env– Gibt an, dass die Ressource erwartet, dass die Eigenschaften eines instance als Umgebungsvariablen mit denselben Namen und denselben Groß- und Kleinschreibungen angegeben werden.

    Diese Option unterstützt nur die folgenden Datentypen für instance Eigenschaften:

    • boolean
    • integer
    • number
    • string
    • array von integer Werten
    • array von number Werten
    • array von string Werten

    Bei Nicht-Array-Werten legt DSC die Umgebungsvariable auf den angegebenen Wert fest. Wenn der Datentyp ein Array von Werten ist, legt DSC die Umgebungsvariable als durch Trennzeichen getrennte Zeichenfolge fest. Beispielsweise wird die Eigenschaft foo mit dem Wert von [1, 2, 3] in der Umgebungsvariablen foo als "1,2,3"gespeichert.

    Wenn die Ressource komplexe Eigenschaften mit einem object Wert oder Mehrtyparrays unterstützen muss, legen Sie stattdessen dies auf stdin fest.

  • stdin– Gibt an, dass die Ressource ein JSON-Blob erwartet, das eine instance von stdindarstellt. Der JSON-Code muss dem instance Schema für die Ressource entsprechen.

Type:        string
Required:    false
ValidValues: [env, stdin]

implementiertPretest

Die implementsPretest -Eigenschaft definiert, ob die Ressource testet, ob sich die instance intern im gewünschten Zustand befindet, bevor sie den gewünschten Zustand erzwingt. Legen Sie diese Eigenschaft auf festtrue, wenn die Ressource die instance als Teil des Vorgangs set testet. Legen Sie diese Eigenschaft auf false fest, wenn dies nicht der Fall ist.

Wenn dieser Wert istfalse, gibt dies an, dass Benutzer immer für den instance aufrufen dsc resource test sollten, bevor sie den dsc resource set Befehl für die Ressource aufrufen.

Standardwert: false.

Type:     boolean
Required: false
Default:  false

handlesExist

Die handlesExist -Eigenschaft definiert, ob die Ressource über eine integrierte Behandlung für die _exist-Eigenschaft im set Vorgang verfügt. Standardwert: false.

Legen Sie diese Eigenschaft auf fest true , wenn die Ressource die folgenden Implementierungsanforderungen erfüllt:

  • Das instance Schema der Ressource definiert die _exist Eigenschaft als gültige instance-Eigenschaft.
  • Der Befehl der set Ressource verarbeitet das Erstellen, Aktualisieren und Löschen einer instance basierend auf dem aktuellen Zustand der instance und dem Wert der _exist Eigenschaft im gewünschten Zustand.

Wenn diese Eigenschaft auf truefestgelegt ist, gibt die Ressource an, dass sie über die SetHandlesExist-Funktion verfügt. Beim Verarbeiten von Ressourcen mit der SetHandlesExist -Funktion in einer Konfiguration ruft DSC den set Vorgang für die Ressource auf, wenn ein instance als falsedefiniert_exist. Ohne diese Funktion muss eine Ressource den Löschvorgang definieren, um das Entfernen von Instanzen der Ressource zu unterstützen.

Wenn ein Ressourcenmanifest diese Eigenschaft nicht als true definiert und den delete Vorgang nicht definiert, löst DSC einen Fehler aus, wenn eine instance der Ressource mit _exist festgelegt auf falseauftritt.

return

Die return -Eigenschaft definiert, wie DSC die Ausgabe für diese Methode verarbeiten soll. Der Wert dieser Eigenschaft muss eine der folgenden Zeichenfolgen sein:

  • state– Gibt an, dass die Ressource nur den endgültigen Zustand des instance nach dem Setvorgang als JSON-Blob zurückgibt.
  • stateAndDiff– Gibt an, dass die Ressource den endgültigen Zustand des instance und ein Array von Eigenschaftennamen zurückgibt, die die Ressource geändert hat.

Der Standardwert ist state.

Type:        string
Required:    false
Default:     state
ValidValues: [state, stateAndDiff]