Dela via

DSC-resursmanifest whatIf egenskapsschemareferens

  • Artikel

Sammanfattning

Definierar hur du anger om och hur set-kommandot ska ändra en instans.

Metadata

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

Beskrivning

När du framtvingar ett konfigurationsdokument med kommandot dsc config set kan användarna ange alternativet --what-if för att se om och hur resurser kommer att ändra systemtillståndet utan att faktiskt göra det. Den här egenskapen definierar hur DSC kan anropa resursen för att returnera den informationen direkt.

När den här egenskapen inte har definierats syntetiserar DSC det här beteendet genom att konvertera resultatet av en teståtgärd mot resursen till ett uppsättningsresultat. Det syntetiska resultatet kan bara indikera hur åtgärden ändrar resursegenskaperna. Det går inte att ange om den set åtgärden misslyckas på grund av ogiltiga parametrar eller vilka skrivskyddade egenskaper som resursen kommer att returnera från åtgärden. I följande lista beskrivs några fall där ett syntetiskt konsekvensresultat inte returnerar tillräcklig information till användaren:

  • En resurs som kräver en parameter för autentiseringsuppgifter kan testa instansen men inte ha behörighet att ändra den. I det här fallet kan användaren köra dsc config set --what-if och se en till synes lyckad förutsägelse för resursen. När de sedan kör kommandot utan alternativet --what-if genererar resursen ett fel som användaren måste undersöka. Om andra resurser har tillämpats före den instans som misslyckades kan systemet lämnas i ett delvis konfigurerat tillstånd.
  • En resurs med en beroendetjänst kan inte rapportera om tjänsten behöver startas om från ett syntetiskt resultat. När du har granskat effekten av konfigurationen baserat på konsekvensresultatet kan en användare oavsiktligt starta om en tjänst eller lämna konfigurationen i ett delvis konfigurerat tillstånd tills tjänsten startas om.

Om resursen använder parametrar eller returnerar skrivskyddade egenskaper från en set-åtgärd definierar du den här metoden för att säkerställa att användarna får bästa möjliga information om huruvida och hur resursen ändrar systemtillståndet i konsekvensläge.

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 radlinjer 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 den args matrisen 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 egenskapen input 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 egenskapen input, ett JSON-indataargument i args-egenskapsmatrisen eller båda.

Exempel

Exempel 1 – Fullständig definition

"set": {
  "executable": "my_app",
  "args": [
    "config",
    "set",
    "--what-if"
  ],
  "input":            "stdin",
  "return":           "state"
}

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

Manifestet definierar tre argument, config, setoch --what-if. Värdet för egenskapen input anger att kommandot whatIf förväntar sig dess indata som en JSON-blob från stdin.

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

{ ... } | my_app config set --what-if

Manifestet definierar return som state, vilket anger att det endast returnerar det förväntade slutliga tillståndet för resursen efter att set-metoden har körts. DSC jämför önskat tillstånd med returdata för den här resursen för att identifiera vilka av resursens egenskaper som metoden set tillämpar, om någon.

Nödvändiga egenskaper

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

Egenskaper

genomförbar

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 bara 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 egenskapspåsen för resursen till ett argument kan du definiera ett enskilt objekt i matrisen som ett JSON-objekt, vilket anger namnet på argumentet med egenskapen jsonInputArg string och om argumentet är obligatoriskt för kommandot med egenskapen mandatory booleskt värde.

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 (krävs) – argumentet för att skicka JSON-data till för kommandot, till exempel --input.
  • mandatory (valfritt) – Anger 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 definiera egenskapen input skickar DSC endast JSON-indata som en sträng till det definierade argumentet.

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

Type:                object
RequiredProperties: [jsonInputArg]

inmatning

Egenskapen input definierar hur du skickar indata till resursen. Om den här egenskapen inte har definierats och definitionen inte definierar ett JSON-indataargumentskickar DSC inga indata till resursen när whatIf-åtgärden 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 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 värden som inte är matrisvärden anger DSC miljövariabeln till det angivna värdet as-is. 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] sparas till exempel i miljövariabeln foo 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]

implementsPretest

Egenskapen implementsPretest definierar om resursen testar om instansen är i önskat tillstånd internt innan det önskade tillståndet verkställs. Ange den här egenskapen till true när resursen testar instansen som en del av den set åtgärden. Ställ in den här egenskapen på false när den inte gör det. I de flesta fall bör det här värdet anges på samma sätt som egenskapen implementsPretest i definitionen för den angivna metoden i resursmanifestet.

När det här värdet är falseanger det att användarna alltid ska anropa dsc resource test mot instansen innan de anropar kommandot dsc resource set mot resursen.

Standardvärdet är false.

Type:     boolean
Required: false
Default:  false

handlesExist

Egenskapen handlesExist definierar om resursen har inbyggd hantering för egenskapen _exist i den set åtgärden. Standardvärdet är false. I de flesta fall bör det här värdet anges på samma sätt som egenskapen implementsPretest i definitionen för den angivna metoden i resursmanifestet.

Ställ in den här egenskapen på true när resursen uppfyller följande implementeringskrav:

  • Resursens instansschema definierar egenskapen _exist som en giltig instansegenskap.
  • Resursens set-kommando hanterar skapande, uppdatering och borttagning av en instans baserat på instansens aktuella tillstånd och värdet för egenskapen _exist i önskat tillstånd.

När den här egenskapen är inställd på trueanger resursen att den har funktionen SetHandlesExist. När du bearbetar resurser med funktionen SetHandlesExist i en konfiguration anropar DSC den set åtgärden för resursen när en instans definierar _exist som false. Utan den här funktionen måste en resurs definiera åtgärden ta bort för att kunna ta bort instanser av resursen.

Om ett resursmanifest inte definierar den här egenskapen som true och inte definierar den delete åtgärden, genererar DSC ett fel när den påträffar en instans av resursen med _exist inställd på false.

återvända

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 förväntade slutliga tillstånd efter den angivna åtgärden som en JSON-blob.
  • stateAndDiff – Anger att resursen returnerar instansens förväntade slutliga tillstånd och en matris med egenskapsnamn som resursen ändrade.

Standardvärdet är state.

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