Sdílet prostřednictvím

Referenční informace ke schématu manifestu prostředků DSC založenému na příkazech

  • Článek

Přehled

Datový soubor, který definuje prostředek DSC založený na příkazech.

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

Popis

Každý prostředek DSC založený na příkazech musí mít manifest. Soubor manifestu musí:

  1. Být zjistitelný v proměnné prostředí PATH.
  2. Formátovat jako JSON nebo YAML.
  3. Postupujte podle zásad vytváření názvů <name>.dsc.resource.<extension>. Platná rozšíření zahrnují json, ymla yaml.
  4. Pro schéma popsané v tomto dokumentu je platné.

Zbytek tohoto dokumentu popisuje schéma manifestu.

Požadované vlastnosti

Manifest musí obsahovat tyto vlastnosti:

Vlastnosti

$schema

Vlastnost $schema označuje kanonický identifikátor URI tohoto schématu, který manifest ověřuje. Tato vlastnost je povinná. DSC tuto hodnotu používá k ověření manifestu ve správném schématu JSON.

Pro každou verzi schématu existují tři platné adresy URL:

  • .../resource/manifest.json

    Adresa URL kanonického nebaleného schématu. Když se používá k ověření, klient ověřování potřebuje načíst toto schéma a každé schéma, na které odkazuje.

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

    Adresa URL sbaleného schématu. Pokud se používá k ověření, ověřování klienta potřebuje pouze načíst toto schéma.

    Toto schéma používá model sdružování zavedený pro schéma JSON 2020–12. I když DSC může dokument při použití tohoto schématu stále ověřit, ostatní nástroje se mohou chybovat nebo se chovat neočekávaně.

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

    Adresa URL rozšířeného schématu vytváření Toto schéma je mnohem větší než ostatní schémata, protože obsahuje další definice, které poskytují kontextovou nápovědu a fragmenty kódu, které ostatní nezahrnují.

    Toto schéma používá klíčová slova, která jsou rozpoznána pouze nástrojem VS Code. I když DSC může dokument při použití tohoto schématu stále ověřit, ostatní nástroje se mohou chybovat nebo se chovat neočekávaně.

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

Vlastnost type představuje plně kvalifikovaný název typu prostředku. Používá se k určení prostředku v konfiguračních dokumentech a jako hodnota příznaku --resource při použití příkazů dsc resource *. Další informace o názvech typů prostředků najdete v tématu Plně kvalifikovaný odkaz na schéma názvu typu prostředku DSC.

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

verze

Vlastnost version musí být aktuální verzí prostředku jako platný sémantický řetězec (semver). Verze se vztahuje na prostředek, nikoli na software, který spravuje.

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

popis

Vlastnost description definuje synopzi pro účel prostředku. Hodnota této vlastnosti musí být krátký řetězec.

Type:     string
Required: false

laskavý

Vlastnost kind definuje způsob zpracování prostředku DSC. DSC podporuje tři druhy prostředků DSC založených na příkazech: Resource, Groupa Adapter.

Pokud kind není definován v manifestu prostředků, DSC odvodí hodnotu vlastnosti. Pokud je vlastnost adapter definována v manifestu prostředku, DSC odvodí hodnotu kind jako Adapter. Pokud není vlastnost adapter definována, DSC odvodí hodnotu kind jako Resource. DSC nemůže odvodit, jestli je manifest pro prostředek skupiny.

Při definování prostředku skupiny vždy explicitně definujte vlastnost kind v manifestu jako Group.

Další informace naleznete v tématu referenční informace o schématu typu prostředku DSC.

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

visačky

Vlastnost tags definuje seznam hledaných termínů pro prostředek. Hodnota této vlastnosti musí být pole řetězců. Každá značka musí obsahovat pouze alfanumerické znaky a podtržítka. Nejsou povoleny žádné další znaky. Každá značka musí být jedinečná.

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

vývoz

Vlastnost export definuje, jak volat prostředek, aby získal aktuální stav každé instance. Při definování této vlastnosti můžou uživatelé:

  • Zadejte instanci prostředku ve vstupní konfiguraci pro dsc config export příkaz k vygenerování použitelného konfiguračního dokumentu.
  • Zadejte prostředek pomocí příkazu dsc resource export k vygenerování konfiguračního dokumentu, který definuje každou instanci prostředku.
  • Zadejte prostředek pomocí příkazu get dsc resource get a --all možnost vrátit aktuální stav pro každou instanci prostředku.

Hodnota této vlastnosti musí být objekt. Vlastnost executable objektu definující název příkazu, který se má volat, je povinný. Vlastnost args je volitelná. Další informace najdete v tématu referenční informace o schématu vlastností exportu manifestu prostředků DSC.

Type:     object
Required: true

dostat

Vlastnost get definuje, jak volat prostředek pro získání aktuálního stavu instance. Tato vlastnost je povinná pro všechny prostředky.

Hodnota této vlastnosti musí být objekt. Vlastnost executable objektu definující název příkazu, který se má volat, je povinný. Vlastnosti args a input jsou volitelné. Další informace naleznete v tématu DSC Resource Manifest získání odkazu schématu vlastnosti.

Type:     object
Required: true

nastavit

Vlastnost set definuje, jak volat prostředek pro nastavení požadovaného stavu instance. Také definuje, jak zpracovat výstup z prostředku pro tuto metodu. Pokud tato vlastnost není definovaná, DSC nemůže spravovat instance prostředku. Může získat pouze aktuální stav a otestovat, jestli je instance v požadovaném stavu.

Hodnota této vlastnosti musí být objekt. Vlastnost executable definující název příkazu, který se má volat, je povinný. Vlastnosti argsinput, implementsPretesta returns jsou volitelné. Další informace najdete v tématu odkaz na schéma schématu manifestu prostředků DSC.

Type:     object
Required: false

whatIf

Definuje, jak DSC musí volat prostředek DSC, který určuje, jestli a jak příkaz set upraví instanci a jak zpracovat výstup z prostředku DSC. Pokud prostředek nedefinuje tuto metodu v manifestu, DSC toto chování syntetizuje převodem výsledku testovací operace pro prostředek na nastavený výsledek.

Hodnota této vlastnosti musí být objekt. Vlastnost executable definující název příkazu, který se má volat, je povinný. Vlastnosti argsinput, implementsPretesta returns jsou volitelné. Další informace naleznete v tématu Manifest prostředku DSC whatIf schéma reference.

test

Vlastnost test definuje, jak volat prostředek k otestování, zda je instance v požadovaném stavu. Také definuje, jak zpracovat výstup z prostředku pro tuto metodu. Pokud tato vlastnost není definována, DSC provede základní syntetický test pro instance prostředku DSC.

Hodnota této vlastnosti musí být objekt. Vlastnost executable objektu definující název příkazu, který se má volat, je povinný. Vlastnosti argsinputa returns jsou volitelné. Další informace naleznete v tématu referenční informace o schématu vlastností manifestu prostředku DSC.

Type:     object
Required: false

ověřit

Vlastnost validate definuje, jak volat prostředek skupiny DSC k ověření jeho instancí. Tato vlastnost je povinná pro prostředky skupiny DSC. DSC tuto vlastnost ignoruje pro všechny ostatní prostředky.

Hodnota této vlastnosti musí být objekt. Vlastnost executable objektu definující název příkazu, který se má volat, je povinný. Vlastnost args je volitelná. Další informace naleznete v tématu DSC Manifest ověření schématu vlastnosti.

Type:     object
Required: false

poskytovatel

Při zadání vlastnost provider definuje prostředek jako poskytovatele prostředků DSC.

Hodnota této vlastnosti musí být objekt. Vlastnosti list a config objektu jsou povinné. Vlastnost list definuje, jak volat poskytovatele, aby vrátil prostředky, které může poskytovatel spravovat. Vlastnost config definuje, jak zprostředkovatel očekává vstup. Další informace najdete v referenční informace o schématu vlastností zprostředkovatele manifestu prostředků DSC.

exitCodes

Vlastnost exitCodes definuje sadu platných ukončovacích kódů pro prostředek a jejich význam. Definujte tuto vlastnost jako sadu párů klíč-hodnota, kde:

  • Klíč je řetězec obsahující podepsané celé číslo, které mapuje na známý ukončovací kód prostředku. Ukončovací kód musí být celé číslo podepsané literálem. Pro ukončovací kód nemůžete použít alternativní formáty. Například místo šestnáctkové hodnoty 0x80070005 "Přístup odepřen", zadejte ukončovací kód jako -2147024891.
  • Hodnota je řetězec popisující sémantický význam tohoto ukončovacího kódu pro člověka.

DSC interpretuje ukončovací kód 0 jako úspěšnou operaci a jakýkoli jiný ukončovací kód jako chybu.

Spropitné

Pokud v yaml vytvoříte manifest prostředku, nezapomeňte ukončovací kód zabalit do jednoduchých uvozovek, abyste měli jistotu, že soubor YAML je možné správně analyzovat. Například:

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

schéma

Vlastnost schema definuje, jak získat schéma JSON, které ověřuje instanci prostředku. Tato vlastnost musí být vždy objektem, který definuje jednu z následujících vlastností:

  • command – Když zadáte vlastnost command, DSC zavolá definovaný příkaz pro získání schématu JSON.
  • embedded – Když zadáte vlastnost embedded, DSC použije definovanou hodnotu jako schéma JSON.

Další informace najdete v tématu referenční informace o vlastnosti schématu manifestu prostředku DSC.

Type:     object
Required: true