Przeczytaj w języku angielskim

Udostępnij za pośrednictwem

Dokumentacja schematu dokumentu konfiguracji DSC

  • Artykuł

Streszczenie

Plik YAML lub JSON, który definiuje konfigurację DSC.

Metadane

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

Opis

Konfiguracje DSC umożliwiają użytkownikom definiowanie stanu przez połączenie różnych zasobów DSC. Dokument konfiguracji używa parametrów i zmiennych do przekazania do zestawu co najmniej jednego zasobu definiującego żądany stan.

Dokument konfiguracji można zdefiniować jako PLIK YAML lub JSON. Aby ułatwić tworzenie, firma Microsoft zaleca tworzenie dokumentów konfiguracji w języku YAML.

Aby narzędzia do tworzenia rozszerzenia DSC rozpoznawały plik jako dokument konfiguracji DSC, nazwa pliku musi kończyć się ciągiem .dsc.config.json, .dsc.config.ymllub .dsc.config.yaml.

Funkcje dokumentu konfiguracji umożliwiają dynamiczne określanie wartości w dokumencie w czasie wykonywania. Aby uzyskać więcej informacji, zobacz dokumentacja funkcji dokumentu DSC

W pozostałej części tego dokumentu opisano schemat DSC używany do weryfikacji dokumentów konfiguracji.

Przykłady

Wymagane właściwości

Każdy dokument konfiguracji musi zawierać następujące właściwości:

  • [$schema]
  • [resources]

Właściwości

$schema

Właściwość $schema wskazuje kanoniczny adres URL wersji tego schematu, z którym jest zgodny dokument. Rozszerzenie DSC używa tej właściwości podczas sprawdzania poprawności dokumentu konfiguracji przed wszelkimi operacjami konfiguracji.

Obecnie istnieje 3 opublikowane wersje schematu, zgodne z różnymi wersjami rozszerzenia DSC:

  • 2024/04 to najnowsza wersja schematu zgodna z dsC w wersji 3.0.0-preview.7 lub nowszej.
  • 2023/10 to poprzednia wersja schematu zgodna z wersjami 3.0.0-alpha.4 DSC i 3.0.0-alpha.5.
  • 2023/08 jest pierwszą wersją schematu zgodną z wersjami 3.0.0-alpha.1 DSC za pośrednictwem polecenia 3.0.0-alpha.3.

Ta dokumentacja dotyczy najnowszej wersji schematu. Należy zaktualizować dokumenty konfiguracji i manifesty zasobów do najnowszej wersji schematu. Wcześniejsze wersje nie działają z nowymi wersjami rozszerzenia DSC. Schematy pozostają opublikowane, ale nie będą otrzymywać żadnych aktualizacji.

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

  • .../config/document.json

    Adres URL schematu kanonicznego, który nie jest powiązany. Gdy jest on używany do weryfikacji, klient sprawdzania poprawności musi pobrać ten schemat i każdy schemat, do którego się odwołuje.

  • .../bundled/config/document.json

    Adres URL schematu dołączonego. Jeśli jest on używany do weryfikacji, klient sprawdzania poprawności musi pobrać ten schemat tylko.

    Ten schemat korzysta z 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/config/document.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 nie zawierają innych.

    Ten schemat używa słów kluczowych, które są rozpoznawane 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/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json
             ]

metadane

Właściwość metadata definiuje zestaw par klucz-wartość jako adnotacje dla konfiguracji. Rozszerzenie DSC nie weryfikuje metadanych. Konfiguracja może zawierać dowolne informacje w tej właściwości.

Type:     object
Required: false

parameters

Właściwość parameters definiuje zestaw opcji środowiska uruchomieniowego dla konfiguracji. Każdy parametr jest definiowany jako para klucz-wartość. Klucz dla każdej pary definiuje nazwę parametru. Wartość dla każdej pary musi być obiektem definiującym type słowo kluczowe, aby wskazać sposób przetwarzania parametru PRZEZ DSC.

Parametry mogą być zastępowane w czasie wykonywania, umożliwiając ponowne użycie tego samego dokumentu konfiguracji dla różnych kontekstów.

Aby uzyskać więcej informacji na temat definiowania parametrów w konfiguracji, zobacz Schemat parametrów dokumentu konfiguracji DSC.

Type:                object
Required:            false
ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.parameter.json

Zmiennych

Właściwość variables definiuje zestaw wartości wielokrotnego użytku dla zasobów w dokumencie jako pary klucz-wartość. Klucz dla każdej pary definiuje nazwę zmiennej. Zasoby odwołujące się do zmiennej według nazwy mogą uzyskiwać dostęp do wartości zmiennej.

Może to pomóc zmniejszyć ilość skopiowanych wartości i opcji zasobów w konfiguracji, co ułatwia odczytywanie i konserwowanie dokumentu. W przeciwieństwie do parametrów zmienne można definiować tylko w konfiguracji i nie można ich zastąpić w czasie wykonywania.

Type:     object
Required: false

zasoby

Właściwość resources definiuje listę wystąpień zasobów DSC zarządzanych przez konfigurację. Każde wystąpienie na liście musi być unikatowe, ale wystąpienia mogą współużytkować ten sam typ zasobu DSC.

Aby uzyskać więcej informacji na temat definiowania prawidłowego wystąpienia zasobu w konfiguracji, zobacz Schemat zasobów dokumentu konfiguracji DSC.

Type:             array
Required:         true
MinimumItemCount: 1
ValidItemSchema:  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.resource.json