Dela via

Schemareferens för kommandobaserad DSC-resursmanifest

Synopsis

Datafilen som definierar en kommandobaserad DSC-resurs.

Metadata

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

Description

Varje kommandobaserad DSC-resurs måste ha ett manifest. Manifestfilen måste:

  1. Kan identifieras i miljövariabeln PATH .
  2. Formateras som antingen JSON eller YAML.
  3. Följ namngivningskonventionen <name>.dsc.resource.<extension>. Giltiga tillägg är json, yml, och yaml.
  4. Vara giltigt för schemat som beskrivs i det här dokumentet.

I resten av det här dokumentet beskrivs manifestets schema.

Nödvändiga egenskaper

Manifestet måste innehålla följande egenskaper:

Properties

$schema

Egenskapen $schema anger den kanoniska URI:n för det här schemat som manifestet verifierar mot. Den här egenskapen är obligatorisk. DSC använder det här värdet för att verifiera manifestet mot rätt JSON-schema.

JSON-scheman för DSC publiceras i flera versioner och formulär. Den här dokumentationen är för den senaste versionen av schemat. För enkelhetens skull kan du ange antingen den fullständiga URI:n för schemat som finns i GitHub eller använda den kortare aka.ms URI:n. Du kan ange schemat för en specifik semantisk version, det senaste schemat för en delversion eller det senaste schemat för en huvudversion av DSC. Mer information om schema-URI:er och versionshantering finns i DSC JSON-schema-URI:er.

För varje version av schemat finns det tre giltiga URL:ar:

  • .../resource/manifest.json

    URL:en till det kanoniska icke-paketerade schemat. När det används för validering måste valideringsklienten hämta det här schemat och alla scheman som det refererar till.

  • .../bundled/resource/manifest.json

    URL:en till det kanoniskt paketerade schemat. När den används för validering behöver valideringsklienten bara hämta det här schemat.

    Det här schemat använder den paketeringsmodell som introducerades för JSON Schema 2020-12. DSC kan fortfarande validera dokumentet när det använder det här schemat, men andra verktyg kan fel eller bete sig på oväntade sätt om de inte har fullt stöd för specifikationen för 2020-12.

  • .../bundled/resource/manifest.vscode.json

    URL:en till det utökade redigeringsschemat. Det här schemat är mycket större än de andra schemana, eftersom det innehåller ytterligare definitioner som ger sammanhangsberoende hjälp och kodfragment som de andra inte inkluderar.

    Det här schemat använder nyckelord som endast identifieras av VS Code. DSC kan fortfarande verifiera dokumentet när det använder det här schemat, men andra verktyg kan fel eller bete sig på oväntade sätt.

Type:        string
Required:    true
Format:      URI
ValidValues: [
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3/resource/manifest.json
               https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.1/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.1/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.1/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.1.0/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.1.0/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.1.0/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.0/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.0.2/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.2/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.2/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.0.1/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.1/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.1/bundled/resource/manifest.vscode.json
               https://aka.ms/dsc/schemas/v3.0.0/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.0/bundled/resource/manifest.json
               https://aka.ms/dsc/schemas/v3.0.0/bundled/resource/manifest.vscode.json
             ]

type

Egenskapen type representerar det fullständigt kvalificerade typnamnet för resursen. Den används för att ange resursen i konfigurationsdokument och som värdet för flaggan --resource när du dsc resource * använder kommandona. Mer information om namn på resurstyper finns i schemareferens för schemat för fullständigt kvalificerat typnamn för DSC-resurs.

Type:     string
Required: true
Pattern:  ^\w+(\.\w+){0,2}\/\w+$

version

Egenskapen version måste vara den aktuella versionen av resursen som en giltig semantisk versionssträng (semver). Versionen gäller för resursen, inte den programvara som den hanterar.

Type:     string
Required: true
Pattern:  ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

description

Egenskapen description definierar en sammanfattning för resursens syfte. Värdet för den här egenskapen måste vara en kort sträng.

Type:     string
Required: false

kind

Egenskapen kind definierar hur DSC ska hantera resursen. DSC stöder flera typer av DSC-resurser: resource, group, importeradapter, och exporter.

När kind det inte definieras i resursmanifestet härleder DSC värdet för egenskapen. adapter Om egenskapen definieras i resursmanifestet härleder DSC värdet för kind as adapter. adapter Om egenskapen inte har definierats härleder DSC värdet för kind as resource. DSC kan inte härleda om ett manifest är för en group eller importer resurs.

När du definierar en gruppresurs definierar kind du alltid uttryckligen egenskapen i manifestet som group. När du definierar en importresurs definierar kind du alltid uttryckligen egenskapen i manifestet som importer.

Mer information finns i Schemareferens för DSC-resurstyp.

Type:        string
Required:    false
ValidValues: [resource, adapter, group, importer, exporter]

tags

Egenskapen tags definierar en lista med sökbara termer för resursen. Värdet för den här egenskapen måste vara en matris med strängar. Varje tagg får endast innehålla alfanumeriska tecken och understreck. Inga andra tecken tillåts. Varje tagg måste vara unik.

Type:              array
Required:          false
ItemsMustBeUnique: true
ItemsType:         string
ItemsPattern:      ^\w+$

export

Egenskapen export definierar hur resursen ska anropas för att hämta det aktuella tillståndet för varje instans. När den här egenskapen har definierats kan användarna:

Värdet för den här egenskapen måste vara ett objekt. Objektets executable egenskap, som definierar namnet på kommandot som ska anropas, är obligatorisk. Egenskapen args är valfri. Mer information finns i schemareferens för export av egenskapsegenskap för DSC-resursmanifest.

Type:     object
Required: true

get

Egenskapen get definierar hur resursen ska anropas för att hämta det aktuella tillståndet för en instans. Den här egenskapen är obligatorisk för alla resurser.

Värdet för den här egenskapen måste vara ett objekt. Objektets executable egenskap, som definierar namnet på kommandot som ska anropas, är obligatorisk. Egenskaperna args och input är valfria. Mer information finns i Schemareferens för DSC-resursmanifest för att hämta egenskap.

Type:     object
Required: true

set

Egenskapen set definierar hur resursen ska anropas för att ange önskat tillstånd för en instans. Den definierar också hur du bearbetar utdata från resursen för den här metoden. När den här egenskapen inte har definierats kan DSC inte hantera instanser av resursen. Den kan bara hämta sitt aktuella tillstånd och testa om instansen är i önskat tillstånd.

Värdet för den här egenskapen måste vara ett objekt. Egenskapen executable , som definierar namnet på kommandot som ska anropas, är obligatorisk. Egenskaperna argsinput, implementsPretestoch returns är valfria. Mer information finns i Schemareferens för egenskapsschema för DSC-resursmanifestuppsättning.

Type:     object
Required: false

whatIf

Definierar hur DSC måste anropa DSC-resursen för att ange om och hur set-kommandot ska ändra en instans och hur utdata från DSC-resursen ska bearbetas. Om en resurs inte definierar den här metoden i manifestet syntetiserar DSC det här beteendet genom att konvertera resultatet av teståtgärden för resursen till det angivna resultatet.

Värdet för den här egenskapen måste vara ett objekt. Egenskapen executable , som definierar namnet på kommandot som ska anropas, är obligatorisk. Egenskaperna argsinput, implementsPretestoch returns är valfria. Mer information finns i Schemareferens för DSC-resursmanifest whatIf-egenskap.

test

Egenskapen test definierar hur resursen ska anropas för att testa om en instans är i önskat tillstånd. Den definierar också hur du bearbetar utdata från resursen för den här metoden. När den här egenskapen inte har definierats utför DSC ett grundläggande syntetiskt test för instanser av DSC-resursen.

Värdet för den här egenskapen måste vara ett objekt. Objektets executable egenskap, som definierar namnet på kommandot som ska anropas, är obligatorisk. Egenskaperna argsinputoch returns är valfria. Mer information finns i schemareferens för testegenskapsegenskap för DSC-resursmanifest.

Type:     object
Required: false

validate

Egenskapen validate definierar hur du anropar en DSC-gruppresurs för att verifiera dess instanser. Den här egenskapen är obligatorisk för DSC-gruppresurser. DSC ignorerar den här egenskapen för alla andra resurser.

Värdet för den här egenskapen måste vara ett objekt. Objektets executable egenskap, som definierar namnet på kommandot som ska anropas, är obligatorisk. Egenskapen args är valfri. Mer information finns i Schemareferens för DSC-resursmanifest för validering av egenskap.

Type:     object
Required: false

provider

När det provider anges definierar egenskapen resursen som en DSC-resursprovider.

Värdet för den här egenskapen måste vara ett objekt. Objektens list och config egenskaperna är obligatoriska. Egenskapen list definierar hur providern ska anropas för att returnera de resurser som providern kan hantera. Egenskapen config definierar hur providern förväntar sig indata. Mer information finns i schemareferensen för DSC-resursmanifestproviderns egenskap.

exitCodes

Egenskapen exitCodes definierar en uppsättning giltiga slutkoder för resursen och deras betydelse. Definiera den här egenskapen som en uppsättning nyckel/värde-par där:

  • Nyckeln är en sträng som innehåller ett signerat heltal som mappar till en känd slutkod för resursen. Slutkoden måste vara ett literalsignerat heltal. Du kan inte använda alternativa format för slutkoden. I stället för det hexadecimala värdet 0x80070005 för "Åtkomst nekad" anger du slutkoden som -2147024891.
  • Värdet är en sträng som beskriver den semantiska innebörden av slutkoden för en mänsklig läsare.

DSC tolkar slutkoden 0 som en lyckad åtgärd och all annan slutkod som ett fel.

Tip

Om du redigerar resursmanifestet i yaml måste du omsluta slutkoden med enkla citattecken för att säkerställa att YAML-filen kan parsas korrekt. Till exempel:

exitCodes:
  '0': Success
  '1': Invalid parameter
  '2': Invalid input
  '3': Registry error
  '4': JSON serialization failed

Type:                object
Required:            false
PropertyNamePattern: ^-?[0-9]+#
PropertyValueType:   string

schema

Egenskapen schema definierar hur du hämtar JSON-schemat som validerar en instans av resursen. Den här egenskapen måste alltid vara ett objekt som definierar någon av följande egenskaper:

  • command - När du anger command egenskapen anropar DSC det definierade kommandot för att hämta JSON-schemat.
  • embedded - När du anger embedded egenskapen använder DSC det definierade värdet som JSON-schema.

Mer information finns i egenskapsreferens för schemat för DSC-resursmanifestet.

Type:     object
Required: true