Dela via

Schemareferens för DSC-resursmanifestets testegenskaper

  • Artikel

Synopsis

Definierar hur du testar om en DSC-resursinstans är i önskat tillstånd.

Metadata

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

Description

Om en DSC-resurs implementerar sin egen logik för att avgöra om en instans är i önskat tillstånd måste den test definiera egenskapen i sitt manifest. Den här egenskapen definierar hur DSC kan anropa resursen för att testa om en instans är i önskat tillstånd.

När den här egenskapen inte har definierats använder DSC en syntetisk testmetod för resursen. Den syntetiska testmetoden:

  1. Hämtar det faktiska tillståndet för instansen med hjälp av resursmetoden get .
  2. Jämför varje definierad egenskap för instansens önskade tillstånd med det faktiska tillståndet.
  3. Om det önskade tillståndet för en egenskap inte är lika med det faktiska tillståndet för den egenskapen rapporterar DSC att instansen inte är i önskat tillstånd.

Eftersom det syntetiska testet bara söker efter likvärdighet kan det inte korrekt testa resurser med egenskaper som inte kan utvärderas enbart med likvärdighet. Om en resurs till exempel hanterar paketversioner och tillåter att versionen anges till latestrapporterar DSC en instans med en version av 3.1.0 som inte har önskat tillstånd, även om 3.1.0 det är den senaste versionen av paketet.

För resurser med egenskaper som inte kan utvärderas enbart med likvärdighet definierar test du alltid egenskapen i manifestet.

DSC skickar data till kommandot på tre sätt:

  1. När input är stdinskickar DSC data som en sträng som representerar data som ett komprimerat JSON-objekt utan blanksteg eller nya linjer mellan objektegenskaperna.
  2. När input är envskickar DSC data som miljövariabler. Den skapar en miljövariabel för varje egenskap i indataobjektet med hjälp av egenskapens namn och värde.
  3. När matrisen args innehåller en JSON-indataargumentdefinition skickar DSC data som en sträng som representerar data som ett komprimerat JSON-objekt till det angivna argumentet.

Om du inte definierar input egenskapen och inte definierar ett JSON-indataargument kan DSC inte skicka indata-JSON till resursen. Du kan bara definiera ett JSON-indataargument för ett kommando.

Du måste definiera input egenskapen, ett JSON-indataargument i egenskapsmatrisen args eller båda.

Exempel

Exempel 1 – Fullständig definition

Det här exemplet kommer från DSC-resursen Microsoft.Windows/Registry .

"test": {
  "executable": "registry",
  "args": [
    "config",
    "test"
  ],
  "input": "stdin",
  "return": "state"
}

Den definierar executable som registryi stället för registry.exe. Tillägget krävs inte när operativsystemet identifierar kommandot som en körbar fil.

Manifestet definierar två argument och configtest. Värdet för input egenskapen anger att test kommandot förväntar sig indata som en JSON-blob från stdin.

I kombination med värdet för executableanropar DSC metoden för den här resursen test genom att köra:

{ ... } | registry config test

Manifestet definierar return som state, som anger att det bara returnerar resursens faktiska tillstånd när test metoden körs.

Nödvändiga egenskaper

Definitionen test måste innehålla följande egenskaper:

Egenskaper

Körbara

Egenskapen executable definierar namnet på kommandot som ska köras. Värdet måste vara namnet på ett kommando som kan identifieras i systemets PATH miljövariabel eller den fullständiga sökvägen till kommandot. Ett filnamnstillägg krävs endast när kommandot inte kan identifieras av operativsystemet som en körbar fil.

Type:     string
Required: true

args

Egenskapen args definierar listan med argument som ska skickas till kommandot. Argumenten kan vara valfritt antal strängar. Om du vill skicka JSON-objektet som representerar egenskapsuppsättningen för resursen till ett argument kan du definiera ett enskilt objekt i matrisen som ett [JSON-objekt], som anger namnet på argumentet med strängegenskapen jsonInputArg och om argumentet är obligatoriskt för kommandot med den mandatory booleska egenskapen.

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

Strängargument

Alla objekt i argumentmatrisen kan vara en sträng som representerar ett statiskt argument som ska skickas till kommandot, till exempel config eller --format.

Type: string

JSON-indataargument

Definierar ett argument för kommandot som accepterar JSON-indataobjektet som en sträng. DSC skickar JSON-indata till det namngivna argumentet när det är tillgängligt. Ett JSON-indataargument definieras som ett JSON-objekt med följande egenskaper:

  • jsonInputArg (obligatoriskt) – argumentet som JSON-data ska skickas till för kommandot, till exempel --input.
  • mandatory (valfritt) – Ange om DSC alltid ska skicka argumentet till kommandot, även om det inte finns några JSON-indata för kommandot. I så fall skickar DSC en tom sträng till JSON-indataargumentet.

Du kan bara definiera ett JSON-indataargument per argumentmatris.

Om du definierar ett JSON-indataargument och en input typ för ett kommando skickar DSC JSON-data åt båda hållen:

  • Om du definierar input som env och ett JSON-indataargument anger DSC en miljövariabel för varje egenskap i JSON-indata och skickar JSON-indataobjektet som en sträng till det definierade argumentet.
  • Om du definierar input som stdin och ett JSON-indataargument skickar DSC JSON-indata över stdin och som en sträng till det definierade argumentet.
  • Om du definierar ett JSON-indataargument utan att input definiera egenskapen skickar DSC bara JSON-indata som en sträng till det definierade argumentet.

Om du inte definierar input egenskapen och inte definierar ett JSON-indataargument kan DSC inte skicka indata-JSON till resursen. Detta gör manifestet ogiltigt. Du måste definiera input egenskapen, ett JSON-indataargument i egenskapsmatrisen args eller båda.

Type:                object
RequiredProperties: [jsonInputArg]

indata

Egenskapen input definierar hur du skickar indata till resursen. Om den här egenskapen inte har definierats skickar DSC inga indata till resursen när åtgärden test anropas.

Värdet för den här egenskapen måste vara en av följande strängar:

  • env – Anger att resursen förväntar sig att egenskaperna för en instans ska anges som miljövariabler med samma namn och hölje.

    Det här alternativet stöder endast följande datatyper för instansegenskaper:

    • boolean
    • integer
    • number
    • string
    • array av integer värden
    • array av number värden
    • array av string värden

    För icke-matrisvärden anger DSC miljövariabeln till det angivna värdet som det är. När datatypen är en matris med värden anger DSC miljövariabeln som en kommaavgränsad sträng. Egenskapen foo med värdet [1, 2, 3] för sparas till exempel i foo miljövariabeln som "1,2,3".

    Om resursen behöver stöd för komplexa egenskaper med ett object värde eller matriser av flera typer anger du detta till stdin i stället.

  • stdin – Anger att resursen förväntar sig en JSON-blob som representerar en instans från stdin. JSON måste följa instansschemat för resursen.

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

återgå

Egenskapen return definierar hur DSC ska bearbeta utdata för den här metoden. Värdet för den här egenskapen måste vara en av följande strängar:

  • state – Anger att resursen endast returnerar instansens faktiska tillstånd.
  • stateAndDiff – Anger att resursen returnerar instansens faktiska tillstånd och en matris med egenskapsnamn som inte har önskat tillstånd.

Standardvärdet är state.

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