Dela via

Referens för egenskapsschema för DSC-resursmanifestuppsättning

  • Artikel

Synopsis

Definierar hur du framtvingar tillstånd för en DSC-resursinstans.

Metadata

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

Description

Om du vill hantera en instans med DSC måste en DSC-resurs definiera set egenskapen i manifestet. Den här egenskapen definierar hur DSC kan framtvinga det aktuella tillståndet för en instans.

När den här egenskapen inte har definierats kan DSC bara hämta det aktuella tillståndet för instanser och testa om de är i önskat tillstånd. DSC kan inte framtvinga önskat tillstånd för resursen.

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 .

"set": {
  "executable": "registry",
  "args": [
    "config",
    "set"
  ],
  "input":            "stdin",
  "implementsPretest": true,
  "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 configset. Värdet för input egenskapen anger att set kommandot förväntar sig indata som en JSON-blob från stdin.

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

{ ... } | registry config set

Eftersom manifestet definierar som anropar implementsPretest DSC inte test metoden för resursen innan den anropar set.true Den här inställningen anger att själva resursen testar instanser innan de framtvingar önskat tillstånd.

Manifestet definierar return som state, som anger att det bara returnerar det slutliga tillståndet för resursen efter att metoden har körts set . DSC jämför önskat tillstånd med returdata för den här resursen för att identifiera vilka av resursens egenskaper set som metoden framtvingade, om sådana finns.

Nödvändiga egenskaper

Definitionen set 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 och definitionen inte definierar ett JSON-indataargument skickar DSC inga indata till resursen när åtgärden set 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]

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 åtgärden set . Ange den här egenskapen till false när den inte gör det.

När det här värdet är falseanger det att användarna alltid ska anropa dsc resource test instansen innan de dsc resource set anropar kommandot 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 set åtgärden. Standardvärdet är false.

Ange den här egenskapen till true när resursen uppfyller följande implementeringskrav:

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

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

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

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

Standardvärdet är state.

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