Dela via

Hämta egenskapsschemareferens för DSC-resursmanifest

  • Artikel

Synopsis

Definierar hur du hämtar 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.get.json
Type:          object

Description

Varje kommandobaserad DSC-resurs måste definiera get egenskapen i sitt manifest. Den här egenskapen definierar hur DSC kan hämta det aktuella tillståndet för en resursinstans.

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 ledningar 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 JSON-indata 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 – Minimal definition

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

"get": {
  "executable": "osinfo"
}

Den definierar executable bara egenskapen . När ett manifest inte definierar argsskickar DSC inga argument till kommandot. När ett manifest inte definierar inputär standardbeteendet att skicka en JSON-blob till kommandot över stdin.

Med den här definitionen anropar DSC metoden för den här resursen get genom att köra:

{ ... } | osinfo

Exempel 2 – Indata från stdin

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

"get": {
  "executable": "registry",
  "args": [
    "config",
    "get"
  ],
  "input": "stdin"
}

Den definierar executable som registry, i stället registry.exeför . Tillägget krävs inte när operativsystemet känner igen kommandot som en körbar fil. Manifestet definierar två argument, config och get. Egenskapen input anger att get kommandot förväntar sig indata som en JSON-blob från stdin. I kombination med värdet för executableanropar DSC get-metoden för den här resursen genom att köra:

{ ... } | registry config get

Exempel 3 – JSON-indataargument

I det här exemplet används ett JSON-indataargument för att skicka data till kommandot .

"get": {
  "executable": "tstoy",
  "args": [
    "config",
    "get",
    { "jsonInputArg": "--input", "mandatory": true }
  ],
}

Den körbara filen definieras som tstoy. Den definierar två strängargument och ett JSON-indataargument. När DSC anropar åtgärden för den här resursen get--input skickar den JSON-data till resursen som en komprimerad JSON-sträng till argumentet.

Det kombinerade anropet för den här åtgärden är:

tstoy config get --input "{ ... }"

Där { ... } representerar den komprimerade JSON för resursinstansen.

mandatory Eftersom alternativet för JSON-indataargumentet är inställt på trueskickar DSC en tom sträng till argumentet när det inte finns några data att skicka till kommandot. Om egenskapen inte har definierats, eller definierats som false, skulle DSC utelämna argumentet helt när det inte finns några data att skicka.

Obligatoriska egenskaper

Definitionen get 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 bara när kommandot inte känns igen 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 JSON-indata 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 indata ska skickas 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 anropas get .

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
    • arrayvärden integer
    • arrayvärden number
    • arrayvärden string

    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] 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 resursens instansschema.

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