Sdílet prostřednictvím

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

Synopsis

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

Description

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

  1. Být zjistitelný v proměnné PATH prostředí.
  2. Formátovat jako JSON nebo YAML.
  3. Dodržujte konvenci <name>.dsc.resource.<extension>pojmenování . Mezi platné přípony patří json, yml, a 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:

Properties

$schema

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

Schémata JSON pro DSC jsou publikována v několika verzích a formách. Tato dokumentace je určena pro nejnovější verzi schématu. Pro usnadnění práce můžete zadat buď úplný identifikátor URI pro schéma hostované na GitHubu, nebo použít kratší aka.ms identifikátor URI. Můžete zadat schéma pro konkrétní sémantickou verzi, nejnovější schéma pro podverzi nebo nejnovější schéma pro hlavní verzi DSC. Další informace o identifikátorech URI schématu a správě verzí najdete v tématu Identifikátory URI schématu DSC 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 kanonicky 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 ověřit i při použití tohoto schématu, jiné nástroje mohou chybovat nebo se chovat neočekávaným způsobem, pokud plně nepodporují specifikaci 2020-12.

  • .../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 ověřit, když používá toto schéma, jiné nástroje mohou chybovat nebo se chovat neočekávaným způsobem.

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
             ]

typ

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

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

verze

Vlastnost version musí být aktuální verzí prostředku jako platný řetězec sémantické verze (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-]+)*))?$

description

Tato description vlastnost definuje přehled pro účel zdroje. Hodnota této vlastnosti musí být krátký řetězec.

Type:     string
Required: false

kind

Vlastnost kind definuje, jak má DSC zpracovat prostředek. DSC podporuje několik druhů prostředků DSC: resource, group, adapter, importera exporter.

Pokud kind není definována v manifestu prostředku, DSC odvodí hodnotu vlastnosti. Pokud je vlastnost definována adapter v manifestu prostředku, DSC odvodí hodnotu kind as adapter. Pokud vlastnost není definována adapter , DSC odvodí hodnotu kind as resource. DSC nemůže odvodit, jestli je manifest pro prostředek nebo groupimporter nebo.

Při definování prostředku skupiny vždy explicitně definujte kind vlastnost v manifestu jako group. Při definování prostředku importéru vždy explicitně definujte kind vlastnost v manifestu jako importer.

Další informace najdete v referenčních informacích ke schématu druhu prostředku DSC.

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

tags

Tato tags vlastnost definuje seznam prohledávatelný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+$

exportovat

Tato export vlastnost definuje, jak se má volat prostředek, aby se 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 příkaz dsc config export , aby se vygeneroval použitelný konfigurační dokument.
  • Určete prostředek pomocí příkazu pro export prostředku dsc a vygenerujte konfigurační dokument, který definuje každou instanci prostředku.
  • Určete prostředek pomocí příkazu dsc resource get a parametru --all , který vrátí aktuální stav pro každou instanci prostředku.

Hodnota této vlastnosti musí být objekt. Vlastnost objektu executable , definující název příkazu, který se má volat, je povinná. Vlastnost args je nepovinná. Další informace naleznete v tématu Referenční informace ke schématu vlastností exportu manifestu prostředku DSC.

Type:     object
Required: true

get

Tato get vlastnost definuje, jak volat prostředek, aby se získal aktuální stav instance. Tato vlastnost je povinná pro všechny prostředky.

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

Type:     object
Required: true

set

Tato set vlastnost definuje, jak volat prostředek k 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 naleznete v tématu Referenční informace ke schématu vlastností sady 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 referenčních informacích ke schématu vlastností whatIf manifestu prostředku DSC.

test

Tato test vlastnost 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 objektu executable , definující název příkazu, který se má volat, je povinná. Vlastnosti argsinput, a returns jsou volitelné. Další informace naleznete v referenčních informacích ke schématu vlastností testu manifestu prostředku DSC.

Type:     object
Required: false

ověřit

Tato validate vlastnost 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 objektu executable , definující název příkazu, který se má volat, je povinná. Vlastnost args je nepovinná. Další informace naleznete v tématu Referenční informace k ověření vlastnosti manifestu prostředku DSC.

Type:     object
Required: false

poskytovatel

Pokud je tato vlastnost zadána provider , definuje prostředek jako poskytovatele prostředků DSC.

Hodnota této vlastnosti musí být objekt. Objekt list a config vlastnosti jsou povinné. Tato list vlastnost definuje, jak volat poskytovatele, aby vrátil prostředky, které může poskytovatel spravovat. Tato config vlastnost definuje, jak poskytovatel očekává vstup. Další informace naleznete v referenčních informacích ke schématu vlastností poskytovatele manifestu prostředku DSC.

exitCodes

Tato exitCodes vlastnost definuje sadu platných ukončovacích kódů pro daný zdroj 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 pro "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.

Tip

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

Tato schema vlastnost 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 command vlastnost, DSC zavolá definovaný příkaz, aby získal schéma JSON.
  • embedded - Když zadáte embedded vlastnost, DSC použije definovanou hodnotu jako schéma JSON.

Další informace naleznete v referenčních informacích k vlastnosti schématu manifestu prostředku DSC.

Type:     object
Required: true
  • Last updated on