Udostępnij za pośrednictwem

Dokumentacja schematu właściwości zestawu manifestu zasobu DSC

  • Artykuł

Streszczenie

Definiuje sposób wymuszania stanu dla wystąpienia zasobu DSC.

Metadane

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

Opis

Aby zarządzać wystąpieniem za pomocą rozszerzenia DSC, zasób DSC musi zdefiniować set właściwość w manifeście. Ta właściwość definiuje sposób wymuszania bieżącego stanu wystąpienia przez rozszerzenie DSC.

Jeśli ta właściwość nie jest zdefiniowana, rozszerzenie DSC może uzyskać tylko bieżący stan wystąpień i sprawdzić, czy są w żądanym stanie. Rozszerzenie DSC nie może wymusić żądanego stanu zasobu.

Rozszerzenie DSC wysyła dane do polecenia na trzy sposoby:

  1. Gdy input parametr ma stdinwartość , ROZSZERZENIE DSC wysyła dane jako ciąg reprezentujący dane jako skompresowany obiekt JSON bez spacji lub nowych linii między właściwościami obiektu.
  2. Gdy input parametr ma envwartość , rozszerzenie DSC wysyła dane jako zmienne środowiskowe. Tworzy zmienną środowiskową dla każdej właściwości w obiekcie danych wejściowych przy użyciu nazwy i wartości właściwości.
  3. Gdy tablica args zawiera definicję argumentu wejściowego JSON, rozszerzenie DSC wysyła dane jako ciąg reprezentujący dane jako skompresowany obiekt JSON do określonego argumentu.

Jeśli nie zdefiniujesz właściwości i nie zdefiniujesz input argumentu wejściowego JSON, rozszerzenie DSC nie może przekazać wejściowego kodu JSON do zasobu. Dla polecenia można zdefiniować tylko jeden argument wejściowy JSON.

Należy zdefiniować input właściwość , jeden argument wejściowy JSON w tablicy args właściwości lub oba te elementy.

Przykłady

Przykład 1 — pełna definicja

Ten przykład pochodzi z Microsoft.Windows/Registry zasobu DSC.

"set": {
  "executable": "registry",
  "args": [
    "config",
    "set"
  ],
  "input":            "stdin",
  "implementsPretest": true,
  "return":           "state"
}

Definiuje executable jako registry, a nie registry.exe. Rozszerzenie nie jest wymagane, gdy system operacyjny rozpoznaje polecenie jako plik wykonywalny.

Manifest definiuje dwa argumenty i configset. Wartość input właściwości wskazuje, że set polecenie oczekuje danych wejściowych jako obiektu blob JSON z stdin.

W połączeniu z wartością parametru executableDSC wywołuje metodę set dla tego zasobu, uruchamiając polecenie:

{ ... } | registry config set

Ponieważ manifest definiuje implementsPretest się jako true, rozszerzenie DSC nie wywoła test metody dla zasobu przed wywołaniem metody set. To ustawienie wskazuje, że sam zasób testuje wystąpienia przed wymusieniem żądanego stanu.

Manifest definiuje return wartość state, co oznacza, że zwraca tylko końcowy stan zasobu po uruchomieniu set metody. Rozszerzenie DSC porównuje żądany stan z danymi zwrotnymi tego zasobu, aby określić, które właściwości set zasobu są wymuszane przez metodę, jeśli istnieją.

Wymagane właściwości

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

Właściwości

Pliku wykonywalnego

Właściwość executable definiuje nazwę polecenia do uruchomienia. Wartość musi być nazwą polecenia wykrywalnego w zmiennej środowiskowej systemu PATH lub pełną ścieżką do polecenia. Rozszerzenie pliku jest wymagane tylko wtedy, gdy polecenie nie jest rozpoznawalne przez system operacyjny jako plik wykonywalny.

Type:     string
Required: true

args

Właściwość args definiuje listę argumentów, które mają być przekazywane do polecenia . Argumenty mogą być dowolną liczbą ciągów. Jeśli chcesz przekazać obiekt JSON reprezentujący worek właściwości dla zasobu do argumentu, możesz zdefiniować pojedynczy element w tablicy jako obiekt [JSON], wskazując nazwę argumentu z właściwością jsonInputArg string i czy argument jest obowiązkowy dla polecenia z właściwością logiczną mandatory .

Type:     array
Required: false
Default:  []
Type:     [string, object(JSON Input Argument)]

Argumenty ciągów

Każdy element w tablicy argumentów może być ciągiem reprezentującym argument statyczny do przekazania do polecenia, na przykład config lub --format.

Type: string

Argument wejściowy JSON

Definiuje argument polecenia, który akceptuje obiekt wejściowy JSON jako ciąg. Rozszerzenie DSC przekazuje dane wejściowe JSON do nazwanego argumentu, jeśli jest dostępny. Argument wejściowy JSON jest definiowany jako obiekt JSON z następującymi właściwościami:

  • jsonInputArg (wymagane) — argument do przekazania danych JSON do polecenia, na przykład --input.
  • mandatory (opcjonalnie) — wskazuje, czy rozszerzenie DSC powinno zawsze przekazywać argument do polecenia, nawet jeśli nie ma danych wejściowych JSON dla polecenia. W takim przypadku rozszerzenie DSC przekazuje pusty ciąg do argumentu wejściowego JSON.

Można zdefiniować tylko jeden argument wejściowy JSON dla tablicy argumentów.

Jeśli zdefiniujesz argument wejściowy JSON i input rodzaj polecenia, rozszerzenie DSC wysyła dane JSON na oba sposoby:

  • Jeśli definiujesz input jako env argument wejściowy JSON i , DSC ustawia zmienną środowiskową dla każdej właściwości w danych wejściowych JSON i przekazuje obiekt wejściowy JSON jako ciąg do zdefiniowanego argumentu.
  • Jeśli zdefiniujesz inputstdin jako i argument wejściowy JSON, DSC przekazuje dane wejściowe JSON przez stdin i jako ciąg do zdefiniowanego argumentu.
  • Jeśli zdefiniujesz argument wejściowy JSON bez definiowania input właściwości, rozszerzenie DSC przekazuje dane wejściowe JSON tylko jako ciąg do zdefiniowanego argumentu.

Jeśli nie zdefiniujesz właściwości i nie zdefiniujesz input argumentu wejściowego JSON, rozszerzenie DSC nie może przekazać wejściowego kodu JSON do zasobu. Powoduje to, że manifest jest nieprawidłowy. Należy zdefiniować input właściwość, argument wejściowy JSON w tablicy args właściwości lub oba te elementy.

Type:                object
RequiredProperties: [jsonInputArg]

wejście

Właściwość input definiuje sposób przekazywania danych wejściowych do zasobu. Jeśli ta właściwość nie jest zdefiniowana, a definicja nie definiuje argumentu wejściowego JSON, rozszerzenie DSC nie wysyła żadnych danych wejściowych do zasobu podczas wywoływania set operacji.

Wartość tej właściwości musi być jednym z następujących ciągów:

  • env — Wskazuje, że zasób oczekuje, że właściwości wystąpienia mają być określone jako zmienne środowiskowe o tych samych nazwach i wielkości liter.

    Ta opcja obsługuje tylko następujące typy danych dla właściwości wystąpienia:

    • boolean
    • integer
    • number
    • string
    • arraywartości integer
    • arraywartości number
    • arraywartości string

    W przypadku wartości innych niż tablica DSC ustawia zmienną środowiskową na określoną wartość, zgodnie z rzeczywistymi wartościami. Gdy typ danych jest tablicą wartości, DSC ustawia zmienną środowiskową jako ciąg rozdzielany przecinkami. Na przykład właściwość foo z wartością [1, 2, 3] jest zapisywana w zmiennej środowiskowej foo jako "1,2,3".

    Jeśli zasób musi obsługiwać złożone właściwości z wartością object lub tablicami wielo typowymi, ustaw tę wartość na stdin wartość .

  • stdin — Wskazuje, że zasób oczekuje obiektu blob JSON reprezentującego wystąpienie z stdinklasy . Kod JSON musi być zgodny ze schematem wystąpienia zasobu.

Type:        string
Required:    false
ValidValues: [env, stdin]

implementsPretest

Właściwość implementsPretest określa, czy zasób sprawdza, czy wystąpienie znajduje się wewnętrznie w żądanym stanie przed wymusiniem żądanego stanu. Ustaw tę właściwość na true wartość , gdy zasób testuje wystąpienie w ramach set operacji. Ustaw tę właściwość na false , gdy jej nie ma.

Gdy ta wartość to false, oznacza to, że użytkownicy powinni zawsze wywoływać wystąpienie dsc resource test przed wywołaniem dsc resource set polecenia względem zasobu.

Wartość domyślna to false.

Type:     boolean
Required: false
Default:  false

handlesExist

Właściwość handlesExist określa, czy zasób ma wbudowaną obsługę właściwości _exist w set operacji. Wartość domyślna to false.

Ustaw tę właściwość na true , gdy zasób spełnia następujące wymagania dotyczące implementacji:

  • Schemat wystąpienia zasobu definiuje _exist właściwość jako prawidłową właściwość wystąpienia.
  • Polecenie zasobu set obsługuje tworzenie, aktualizowanie i usuwanie wystąpienia na podstawie bieżącego stanu wystąpienia oraz wartości _exist właściwości w żądanym stanie.

Gdy ta właściwość jest ustawiona na truewartość , zasób wskazuje, że ma ona funkcjęSetHandlesExist. Podczas przetwarzania zasobów z SetHandlesExist możliwością w konfiguracji rozszerzenie DSC wywołuje operację set dla zasobu, gdy wystąpienie definiuje _exist jako false. Bez tej możliwości zasób musi zdefiniować operację usuwania , aby obsługiwać usuwanie wystąpień zasobu.

Jeśli manifest zasobu nie definiuje tej właściwości jako true i nie definiuje delete operacji, rozszerzenie DSC zgłasza błąd, gdy napotka wystąpienie zasobu z ustawioną wartością _existfalse.

return

Właściwość return określa sposób przetwarzania danych wyjściowych przez rozszerzenie DSC dla tej metody. Wartość tej właściwości musi być jednym z następujących ciągów:

  • state — Wskazuje, że zasób zwraca tylko stan końcowy wystąpienia po operacji zestawu jako obiekt blob JSON.
  • stateAndDiff — Wskazuje, że zasób zwraca stan końcowy wystąpienia i tablicę nazw właściwości zmodyfikowanych przez zasób.

Wartość domyślna to state.

Type:        string
Required:    false
Default:     state
ValidValues: [state, stateAndDiff]