Referenz zum DSC-Ressourcenmanifest: Testeigenschaftsschema
Zusammenfassung
Definiert, wie getestet wird, ob sich eine DSC-Ressource instance im gewünschten Zustand befindet.
Metadaten
SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json
Type: object
Beschreibung
Wenn eine DSC-Ressource eine eigene Logik implementiert, um zu bestimmen, ob sich ein instance im gewünschten Zustand befindet, muss sie die test
Eigenschaft in ihrem Manifest definieren. Diese Eigenschaft definiert, wie DSC die Ressource aufrufen kann, um zu testen, ob sich ein instance im gewünschten Zustand befindet.
Wenn diese Eigenschaft nicht definiert ist, verwendet DSC eine synthetische Testmethode für die Ressource. Die synthetische Testmethode:
- Ruft den tatsächlichen Zustand des instance mithilfe der Methode der Ressource
get
ab. - Vergleicht jede definierte Eigenschaft des gewünschten Zustands des instance mit dem tatsächlichen Zustand.
- Wenn der gewünschte Zustand einer Eigenschaft nicht dem tatsächlichen Zustand dieser Eigenschaft entspricht, meldet DSC, dass sich die instance nicht im gewünschten Zustand befindet.
Da der synthetische Test nur auf Äquivalenz überprüft, können Ressourcen nicht genau mit Eigenschaften getestet werden, die nicht allein mit Äquivalenz ausgewertet werden können. Wenn eine Ressource beispielsweise Paketversionen verwaltet und das Festlegen der Version auf latest
zulässt, meldet DSC einen instance mit einer Version von 3.1.0
als außerhalb des gewünschten Zustands, auch wenn 3.1.0
die neueste Version des Pakets ist.
Definieren Sie für Ressourcen mit Eigenschaften, die nicht allein anhand der Äquivalenz ausgewertet werden können, immer die test
Eigenschaft im Manifest.
DSC sendet Daten auf drei Arten an den Befehl:
- Wenn
input
iststdin
, sendet DSC die Daten als Zeichenfolge, die die Daten als komprimiertes JSON-Objekt ohne Leerzeichen oder Neueinbrüche zwischen den Objekteigenschaften darstellt. - Wenn
input
dies der Wert istenv
, 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. - 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.
"test": {
"executable": "registry",
"args": [
"config",
"test"
],
"input": "stdin",
"return": "state"
}
Sie definiert executable
als registry
, und registry.exe
nicht . Die Erweiterung ist nicht erforderlich, wenn das Betriebssystem den Befehl als ausführbare Datei erkennt.
Das Manifest definiert zwei Argumente und config
test
. Der Wert der input
-Eigenschaft gibt an, dass der test
Befehl seine Eingabe als JSON-Blob von stdin
erwartet.
In Kombination mit dem Wert für executable
ruft DSC die test
-Methode für diese Ressource auf, indem folgendes ausgeführt wird:
{ ... } | registry config test
Das Manifest definiert return
als state
, was angibt, dass es nur den tatsächlichen Zustand der Ressource zurückgibt, wenn die test
Methode ausgeführt wird.
Erforderliche Eigenschaften
Die test
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, sendet DSC beim Aufrufen des Vorgangs keine Eingabe an die test
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
voninteger
Wertenarray
vonnumber
Wertenarray
vonstring
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 Umgebungsvariablenfoo
als"1,2,3"
gespeichert.Wenn die Ressource komplexe Eigenschaften mit einem
object
Wert oder Mehrtyparrays unterstützen muss, legen Sie stattdessen dies aufstdin
fest.stdin
– Gibt an, dass die Ressource ein JSON-Blob erwartet, das eine instance vonstdin
darstellt. Der JSON-Code muss dem instance Schema für die Ressource entsprechen.
Type: string
Required: false
ValidValues: [env, stdin]
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 tatsächlichen Zustand des instance zurückgibt.stateAndDiff
– Gibt an, dass die Ressource den tatsächlichen Zustand der instance und ein Array von Eigenschaftennamen zurückgibt, die außerhalb des gewünschten Zustands liegen.
Der Standardwert ist state
.
Type: string
Required: false
Default: state
ValidValues: [state, stateAndDiff]