Udostępnij za pośrednictwem

Manifest zasobu DSC whatIf odwołanie do schematu właściwości

  • Artykuł

Streszczenie

Definiuje sposób wskazywania, czy i jak polecenie set zmodyfikuje wystąpienie.

Metadane

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

Opis

Podczas wymuszania dokumentu konfiguracji przy użyciu dsc config set polecenie, użytkownicy mogą określić --what-if opcji, aby zobaczyć, czy i jak zasoby zmienią stan systemu bez faktycznego wykonania. Ta właściwość definiuje sposób, w jaki dsC może wywołać zasób, aby bezpośrednio zwrócić te informacje.

Jeśli ta właściwość nie jest zdefiniowana, rozszerzenie DSC syntetyzuje to zachowanie, konwertując wynik operacji testowej względem zasobu na wynik zestawu. Wynik syntetyczny może wskazywać tylko, jak operacja zmieni właściwości zasobu. Nie można wskazać, czy operacja set zakończy się niepowodzeniem z powodu nieprawidłowych parametrów lub które właściwości tylko do odczytu zasób zwróci z operacji. Poniższa lista zawiera opis kilku przypadków, w których syntetyczny wynik analizy co-jeżeli nie zwróci wystarczających informacji użytkownikowi:

  • Zasób wymagający parametru poświadczeń może pomyślnie przetestować wystąpienie, ale nie ma uprawnień do jego modyfikowania. W takim przypadku użytkownik może uruchomić dsc config set --what-if i zobaczyć pozornie pomyślne przewidywanie zasobu. Następnie po uruchomieniu polecenia bez opcji --what-if zasób zgłasza błąd, który użytkownik musi zbadać. Jeśli jakiekolwiek inne zasoby zostały pomyślnie zastosowane przed wystąpieniem, które zakończyło się niepowodzeniem, system może pozostać w stanie częściowo skonfigurowanym.
  • Zasób z usługą zależności nie będzie mógł zgłosić, czy ta usługa musi zostać uruchomiona ponownie z syntetycznego wyniku. Po przejrzeniu wpływu konfiguracji na podstawie wyniku analizy warunkowej użytkownik może przypadkowo ponownie uruchomić usługę lub pozostawić konfigurację w stanie częściowo skonfigurowanym do czasu ponownego uruchomienia tej usługi.

Jeśli zasób używa parametrów lub zwraca właściwości tylko do odczytu z operacji set, zdefiniuj tę metodę, aby zapewnić użytkownikom najlepsze informacje o tym, czy i jak zasób zmodyfikuje stan systemu w trybie warunkowym.

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

  1. Gdy input jest stdin, 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 jest env, 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 input i nie zdefiniujesz 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ć właściwość input, jeden argument wejściowy JSON w tablicy właściwości args lub oba te elementy.

Przykłady

Przykład 1 — pełna definicja

"set": {
  "executable": "my_app",
  "args": [
    "config",
    "set",
    "--what-if"
  ],
  "input":            "stdin",
  "return":           "state"
}

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

Manifest definiuje trzy argumenty, config, seti --what-if. Wartość właściwości input wskazuje, że polecenie whatIf oczekuje danych wejściowych jako obiektu blob JSON z stdin.

W połączeniu z wartością executabledsC wywołuje metodę analizy warunkowej dla tego zasobu, uruchamiając polecenie:

{ ... } | my_app config set --what-if

Manifest definiuje return jako state, wskazując, że zwraca tylko oczekiwany stan końcowy zasobu po uruchomieniu metody set. Rozszerzenie DSC porównuje żądany stan z danymi zwrotnymi tego zasobu, aby określić, które z właściwości zasobu set metoda będzie wymuszać, jeśli istnieje.

Wymagane właściwości

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

  • wykonywalnych

Właściwości

plik wykonywalny

Właściwość executable definiuje nazwę polecenia do uruchomienia. Wartość musi być nazwą polecenia wykrywalnego w PATH zmiennej środowiskowej systemu lub pełnej ścieżki 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 torbę 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ą ciągu jsonInputArg 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ągu

Każdy element w tablicy argumentów może być ciągiem reprezentującym argument statyczny do przekazania do polecenia, takiego jak 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, gdy jest dostępny. Argument wejściowy JSON jest definiowany jako obiekt JSON z następującymi właściwościami:

  • jsonInputArg (wymagane) — argument umożliwiający przekazanie danych JSON do polecenia, na przykład --input.
  • mandatory (opcjonalnie) — wskazuje, czy rozszerzenie DSC zawsze powinno przekazać 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 rodzaj input dla polecenia, rozszerzenie DSC wysyła dane JSON na oba sposoby:

  • Jeśli zdefiniujesz input jako env i argument wejściowy JSON, 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 input jako stdin 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 zdefiniowania właściwości input, rozszerzenie DSC przekazuje tylko dane wejściowe JSON jako ciąg do zdefiniowanego argumentu.

Jeśli nie zdefiniujesz właściwości input i nie zdefiniujesz 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ć właściwość input, argument wejściowy JSON w tablicy właściwości args lub oba te elementy.

Type:                object
RequiredProperties: [jsonInputArg]

wkład

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 operacji whatIf.

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 takich 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
    • array wartości integer
    • array wartości number
    • array wartości string

    W przypadku wartości innych niż tablica DSC ustawia zmienną środowiskową na określoną wartość as-is. 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 typem, ustaw tę wartość na stdin.

  • stdin — wskazuje, że zasób oczekuje obiektu blob JSON reprezentującego wystąpienie z stdin. 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 jest w żądanym stanie wewnętrznie przed wymusiniem żądanego stanu. Ustaw tę właściwość na true, gdy zasób testuje wystąpienie w ramach operacji set. Ustaw tę właściwość na false, gdy nie. W większości przypadków ta wartość powinna być ustawiona tak samo jak właściwość implementsPretest w definicji metody zestawu w manifeście zasobu.

Gdy ta wartość jest false, wskazuje, że użytkownicy powinni zawsze wywoływać dsc resource test względem wystąpienia przed wywołaniem polecenia dsc resource set 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 operacji set. Wartość domyślna to false. W większości przypadków ta wartość powinna być ustawiona tak samo jak właściwość implementsPretest w definicji metody zestawu w manifeście zasobu.

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

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

Gdy ta właściwość jest ustawiona na true, zasób wskazuje, że ma SetHandlesExist możliwości. Podczas przetwarzania zasobów za pomocą możliwości SetHandlesExist w konfiguracji 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 w celu obsługi usuwania wystąpień zasobu.

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

wrócić

Właściwość return definiuje 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 oczekiwany stan końcowy wystąpienia po operacji zestawu jako obiekt blob JSON.
  • stateAndDiff — wskazuje, że zasób zwraca oczekiwany 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]