Dokumentacja schematu manifestu zasobu DSC oparta na poleceniach

Artykuł
06/25/2024

Streszczenie

Plik danych definiujący zasób DSC oparty na poleceniach.

Metadane

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

Opis

Każdy zasób DSC oparty na poleceniach musi mieć manifest. Plik manifestu musi:

Możliwość odnajdywania w zmiennej środowiskowej PATH.
Być sformatowane jako JSON lub YAML.
Postępuj zgodnie z konwencją nazewnictwa <name>.dsc.resource.<extension>. Prawidłowe rozszerzenia obejmują json, ymli yaml.
Prawidłowe dla schematu opisanego w tym dokumencie.

W pozostałej części tego dokumentu opisano schemat manifestu.

Wymagane właściwości

Manifest musi zawierać następujące właściwości:

$schema
typ
wersji
uzyskiwanie

Właściwości

$schema

Właściwość $schema wskazuje kanoniczny identyfikator URI tego schematu, względem którego manifest sprawdza poprawność. Ta właściwość jest obowiązkowa. Rozszerzenie DSC używa tej wartości do sprawdzania poprawności manifestu względem poprawnego schematu JSON.

Dla każdej wersji schematu istnieją trzy prawidłowe adresy URL:

.../resource/manifest.json

Adres URL schematu kanonicznego, który nie jest powiązany. Gdy jest on używany do walidacji, walidacja klienta musi pobrać ten schemat i każdy schemat, do którego się odwołuje.
.../bundled/resource/manifest.json

Adres URL schematu dołączonego. Jeśli jest on używany do walidacji, walidacja klienta musi pobrać ten schemat tylko.

Ten schemat używa modelu tworzenia pakietów wprowadzonego dla schematu JSON 2020-12. Mimo że rozszerzenie DSC może nadal weryfikować dokument w przypadku korzystania z tego schematu, inne narzędzia mogą błędy lub zachowywać się w nieoczekiwany sposób.
.../bundled/resource/manifest.vscode.json

Adres URL rozszerzonego schematu tworzenia. Ten schemat jest znacznie większy niż inne schematy, ponieważ zawiera dodatkowe definicje, które zapewniają kontekstową pomoc i fragmenty kodu, które inne nie zawierają.

Ten schemat używa słów kluczowych rozpoznawanych tylko przez program VS Code. Mimo że rozszerzenie DSC może nadal weryfikować dokument w przypadku korzystania z tego schematu, inne narzędzia mogą błędy lub zachowywać się w nieoczekiwany sposób.

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

Właściwość type reprezentuje w pełni kwalifikowaną nazwę typu zasobu. Służy do określania zasobu w dokumentach konfiguracji oraz jako wartości flagi --resource podczas używania poleceń dsc resource *. Aby uzyskać więcej informacji na temat nazw typów zasobów, zobacz dokumentacja schematu nazwy w pełni kwalifikowanego typu zasobu DSC.

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

Wersja

Właściwość version musi być bieżącą wersją zasobu jako prawidłowy ciąg semantyczny (semver). Wersja ma zastosowanie do zasobu, a nie oprogramowania, którymi zarządza.

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

opis

Właściwość description definiuje streszczenie dla celu zasobu. Wartość tej właściwości musi być krótkim ciągiem.

Type:     string
Required: false

rodzaj

Właściwość kind definiuje sposób obsługi zasobu przez rozszerzenie DSC. Rozszerzenie DSC obsługuje trzy rodzaje zasobów DSC opartych na poleceniach: Resource, Groupi Adapter.

Jeśli kind nie jest zdefiniowana w manifeście zasobu, rozszerzenie DSC wywnioskuje wartość właściwości. Jeśli właściwość adapter jest zdefiniowana w manifeście zasobu, rozszerzenie DSC wywnioskuje wartość kind jako Adapter. Jeśli właściwość adapter nie jest zdefiniowana, rozszerzenie DSC wywnioskuje wartość kind jako Resource. DsC nie może wywnioskować, czy manifest dotyczy zasobu grupy.

Podczas definiowania zasobu grupy zawsze jawnie zdefiniuj właściwość kind w manifeście jako Group.

Aby uzyskać więcej informacji, zobacz dokumentacja schematu typu zasobów DSC.

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

Tagi

Właściwość tags definiuje listę wyszukiwalnych terminów dla zasobu. Wartość tej właściwości musi być tablicą ciągów. Każdy tag musi zawierać tylko znaki alfanumeryczne i podkreślenia. Żadne inne znaki nie są dozwolone. Każdy tag musi być unikatowy.

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

eksport

Właściwość export definiuje sposób wywoływania zasobu w celu uzyskania bieżącego stanu każdego wystąpienia. Po zdefiniowaniu tej właściwości użytkownicy mogą:

Określ wystąpienie zasobu w konfiguracji wejściowej dla polecenia eksportu konfiguracji dsc dsc, aby wygenerować dokument konfiguracji do użycia.
Określ zasób za pomocą polecenia eksportu zasobów dsc w celu wygenerowania dokumentu konfiguracji definiującego każde wystąpienie zasobu.
Określ zasób za pomocą zasobu dsc get i --all opcji zwrócić bieżący stan dla każdego wystąpienia zasobu.

Wartość tej właściwości musi być obiektem. Właściwość executable obiektu, definiująca nazwę polecenia do wywołania, jest obowiązkowa. Właściwość args jest opcjonalna. Aby uzyskać więcej informacji, zobacz dokumentacja schematu właściwości eksportu manifestu DSC.

Type:     object
Required: true

Pobierz

Właściwość get definiuje sposób wywoływania zasobu w celu uzyskania bieżącego stanu wystąpienia. Ta właściwość jest obowiązkowa dla wszystkich zasobów.

Wartość tej właściwości musi być obiektem. Właściwość executable obiektu, definiująca nazwę polecenia do wywołania, jest obowiązkowa. Właściwości args i input są opcjonalne. Aby uzyskać więcej informacji, zobacz Manifest zasobu DSC get property schema reference.

Type:     object
Required: true

zbiór

Właściwość set definiuje sposób wywoływania zasobu w celu ustawienia żądanego stanu wystąpienia. Definiuje również sposób przetwarzania danych wyjściowych z zasobu dla tej metody. Jeśli ta właściwość nie jest zdefiniowana, rozszerzenie DSC nie może zarządzać wystąpieniami zasobu. Może uzyskać bieżący stan i sprawdzić, czy wystąpienie jest w żądanym stanie.

Wartość tej właściwości musi być obiektem. Właściwość executable definiująca nazwę polecenia do wywołania jest obowiązkowa. Właściwości argsinput, implementsPretesti returns są opcjonalne. Aby uzyskać więcej informacji, zobacz dokumentacja schematu właściwości zestawu zasobów DSC.

Type:     object
Required: false

whatIf

Definiuje sposób, w jaki rozszerzenie DSC musi wywołać zasób DSC, aby wskazać, czy i jak ustawić polecenie zmodyfikuje wystąpienie i jak przetworzyć dane wyjściowe z zasobu DSC. Jeśli zasób nie definiuje tej metody w manifeście, DSC syntetyzuje to zachowanie, konwertując wynik operacji testowej zasobu na wynik zestawu.

Wartość tej właściwości musi być obiektem. Właściwość executable definiująca nazwę polecenia do wywołania jest obowiązkowa. Właściwości argsinput, implementsPretesti returns są opcjonalne. Aby uzyskać więcej informacji, zobacz manifestu zasobu DSC whatIf property schema reference.

test

Właściwość test definiuje sposób wywoływania zasobu w celu sprawdzenia, czy wystąpienie jest w żądanym stanie. Definiuje również sposób przetwarzania danych wyjściowych z zasobu dla tej metody. Gdy ta właściwość nie jest zdefiniowana, DSC wykonuje podstawowy test syntetyczny dla wystąpień zasobu DSC.

Wartość tej właściwości musi być obiektem. Właściwość executable obiektu, definiująca nazwę polecenia do wywołania, jest obowiązkowa. Właściwości argsinputi returns są opcjonalne. Aby uzyskać więcej informacji, zobacz dokumentacja schematu właściwości testowej manifestu usługi DSC.

Type:     object
Required: false

walidować

Właściwość validate definiuje sposób wywoływania zasobu grupy DSC w celu zweryfikowania jego wystąpień. Ta właściwość jest obowiązkowa dla zasobów grupy DSC. Rozszerzenie DSC ignoruje tę właściwość dla wszystkich innych zasobów.

Wartość tej właściwości musi być obiektem. Właściwość executable obiektu, definiująca nazwę polecenia do wywołania, jest obowiązkowa. Właściwość args jest opcjonalna. Aby uzyskać więcej informacji, zobacz DSC Resource manifest validate property schema reference.

Type:     object
Required: false

dostawca

Po określeniu właściwość provider definiuje zasób jako dostawcę zasobów DSC.

Wartość tej właściwości musi być obiektem. Właściwości list i config obiektu są obowiązkowe. Właściwość list definiuje sposób wywoływania dostawcy w celu zwrócenia zasobów, którymi może zarządzać dostawca. Właściwość config definiuje sposób, w jaki dostawca oczekuje danych wejściowych. Aby uzyskać więcej informacji, zobacz dokumentację schematu właściwości dostawcy DSC resource provider.

exitCodes

Właściwość exitCodes definiuje zestaw prawidłowych kodów zakończenia dla zasobu i ich znaczenia. Zdefiniuj tę właściwość jako zestaw par klucz-wartość, w których:

Klucz jest ciągiem zawierającym podpisaną liczbę całkowitą, która mapuje na znany kod zakończenia zasobu. Kod zakończenia musi być liczbą całkowitą ze znakiem literału. Nie można używać alternatywnych formatów dla kodu zakończenia. Na przykład zamiast wartości szesnastkowej 0x80070005 dla opcji "Odmowa dostępu" określ kod zakończenia jako -2147024891.
Wartość jest ciągiem opisującym semantyczne znaczenie tego kodu zakończenia dla czytelnika ludzkiego.

DSC interpretuje kod zakończenia 0 jako pomyślnej operacji i dowolny inny kod zakończenia jako błąd.

Napiwek

Jeśli tworzysz manifest zasobu w pliku yaml, pamiętaj, aby opakować kod zakończenia w pojedynczych cudzysłowach, aby upewnić się, że plik YAML może być poprawnie przeanalizowany. Na przykład:

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

Właściwość schema definiuje sposób pobierania schematu JSON, który weryfikuje wystąpienie zasobu. Ta właściwość musi zawsze być obiektem definiującym jedną z następujących właściwości:

command — po określeniu właściwości command rozszerzenie DSC wywołuje zdefiniowane polecenie w celu pobrania schematu JSON.
embedded — po określeniu właściwości embedded dsC używa zdefiniowanej wartości jako schematu JSON.

Aby uzyskać więcej informacji, zobacz dokumentacja właściwości schematu manifestu zasobu DSC.

Type:     object
Required: true

Udostępnij za pośrednictwem