Dela via

Schemareferens för kommandobaserad DSC-resursmanifest

  • Artikel

Sammanfattning

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/2024/04/resource/manifest.json
Type:          object

Beskrivning

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

  1. Identifieras i miljövariabeln PATH.
  2. Formateras som antingen JSON eller YAML.
  3. Följ namngivningskonventionen <name>.dsc.resource.<extension>. Giltiga tillägg omfattar json, ymloch 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:

Egenskaper

$schema

Egenskapen $schema anger den kanoniska URI 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.

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 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. Även om DSC fortfarande kan verifiera dokumentet när det använder det här schemat, kan andra verktyg fel eller bete sig på oväntade sätt.

  • .../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. Även om DSC fortfarande kan verifiera dokumentet när det använder det här schemat, kan andra verktyg fel eller bete sig på oväntade sätt.

Type:        string
Required:    true
Format:      URI
ValidValues: [
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json
             ]

typ

Egenskapen type representerar resursens fullständigt kvalificerade typnamn. Den används för att ange resursen i konfigurationsdokumenten och som värdet för flaggan --resource när du använder dsc resource * kommandon. Mer information om resurstypsnamn finns i DSC-resursens fullständigt kvalificerade typnamnsschemareferens.

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-]+)*))?$

beskrivning

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

Type:     string
Required: false

sort

Egenskapen kind definierar hur DSC ska hantera resursen. DSC stöder tre typer av kommandobaserade DSC-resurser: Resource, Groupoch Adapter.

När kind inte har definierats i resursmanifestet härleder DSC värdet för egenskapen. Om egenskapen adapter definieras i resursmanifestet härleder DSC värdet för kind som Adapter. Om egenskapen adapter inte har definierats härleder DSC värdet för kind som Resource. DSC kan inte härleda om ett manifest är för en gruppresurs.

När du definierar en gruppresurs definierar du alltid uttryckligen egenskapen kind i manifestet som Group.

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

Type:        string
Required:    false
ValidValues: [Resource, Adapter, Group]

Taggar

Egenskapen tags definierar en lista över 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 du anropar resursen för att hämta det aktuella tillståndet för varje instans. När den här egenskapen har definierats kan användarna:

  • Ange en instans av resursen i indatakonfigurationen för kommandot dsc config export för att generera ett användbart konfigurationsdokument.
  • Ange resursen med kommandot dsc-resursexport för att generera ett konfigurationsdokument som definierar varje instans av resursen.
  • Ange resursen med kommandot dsc get och alternativet - all för att returnera det aktuella tillståndet för varje instans av resursen.

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

Type:     object
Required: true

få

Egenskapen get definierar hur du anropar resursen 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 egenskap executable, som definierar namnet på kommandot som ska anropas, är obligatorisk. Egenskaperna args och input är valfria. Mer information finns i DSC-resursmanifestet hämta egenskapsschemareferensen.

Type:     object
Required: true

ställa

Egenskapen set definierar hur du anropar resursen 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 DSC Resource Manifest set property schema reference.

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 DSC-resursmanifestet whatIf property schema reference.

test

Egenskapen test definierar hur du anropar resursen 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 egenskap executable, som definierar namnet på kommandot som ska anropas, är obligatorisk. Egenskaperna argsinputoch returns är valfria. Mer information finns i referens för DSC-resursmanifestets testegenskaper.

Type:     object
Required: false

validera

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 egenskap executable, som definierar namnet på kommandot som ska anropas, är obligatorisk. Egenskapen args är valfri. Mer information finns i DSC-resursmanifestet verifierar egenskapsschemareferensen.

Type:     object
Required: false

familjeförsörjare

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

Värdet för den här egenskapen måste vara ett objekt. Objektets egenskaper för list och config är obligatoriska. Egenskapen list definierar hur providern 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 DSC-resursmanifestproviderns egenskapsschemareferens.

exitCodes

Egenskapen exitCodes definierar en uppsättning giltiga slutkoder för resursen och deras innebörd. 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 hexadecimalt värde 0x80070005 för "Åtkomst nekad" anger du till exempel 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 slutkod 0 som en lyckad åtgärd och annan slutkod som ett fel.

Dricks

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

Schemat

Egenskapen schema definierar hur du hämtar JSON-schemat som verifierar 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 egenskapen command anropar DSC det definierade kommandot för att hämta JSON-schemat.
  • embedded – När du anger egenskapen embedded använder DSC det definierade värdet som JSON-schema.

Mer information finns i DSC-resursmanifestets egenskapsreferens.

Type:     object
Required: true