Referência do esquema do documento de Configuração do DSC

Artigo
05/11/2024

Sinopse

O ficheiro YAML ou JSON que define uma Configuração do DSC.

Metadados

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

Description

As Configurações do DSC permitem que os utilizadores definam o estado ao combinar diferentes Recursos do DSC. Um documento de configuração utiliza parâmetros e variáveis para transmitir para um conjunto de um ou mais recursos que definem um estado pretendido.

Um documento de configuração pode ser definido como YAML ou JSON. Para facilitar a criação, a Microsoft recomenda a elaboração de documentos de configuração no YAML.

Para que as ferramentas de criação do DSC reconheçam um ficheiro como um documento de Configuração do DSC, o nome de ficheiro tem de terminar com .dsc.config.json, .dsc.config.ymlou .dsc.config.yaml.

Pode utilizar funções de documento de configuração para determinar dinamicamente os valores no documento no runtime. Para obter mais informações, veja DSC Configuration document functions reference (Referência de funções de documentos de Configuração do DSC)

O resto deste documento descreve o esquema que o DSC utiliza para validar documentos de configuração.

Exemplos

Propriedades Necessárias

Cada documento de configuração tem de incluir estas propriedades:

[$schema]
[recursos]

Propriedades

$schema

A $schema propriedade indica o URL canónico da versão deste esquema a que o documento cumpre. O DSC utiliza esta propriedade ao validar o documento de configuração antes de quaisquer operações de configuração.

Existem atualmente 3 versões publicadas do esquema, compatíveis com versões diferentes do DSC:

2024/04 é a versão mais recente do esquema, compatível com a versão 3.0.0-preview.7 e posterior do DSC.
2023/10 é a versão anterior do esquema, compatível com as versões 3.0.0-alpha.4 do DSC e 3.0.0-alpha.5.
2023/08 é a primeira versão do esquema, compatível com versões do DSC através 3.0.0-alpha.1 do 3.0.0-alpha.3.

Esta documentação destina-se à versão mais recente do esquema. Deve atualizar os documentos de configuração e os manifestos de recursos para a versão mais recente do esquema. As versões anteriores não funcionam com novas versões do DSC. Os esquemas permanecem publicados, mas não receberão atualizações.

Para cada versão do esquema, existem três URLs válidos:

.../config/document.json

O URL para o esquema canónico não agrupado. Quando é utilizado para validação, o cliente de validação tem de obter este esquema e todos os esquemas que referenciar.
.../bundled/config/document.json

O URL para o esquema agrupado. Quando é utilizado para validação, o cliente de validação só precisa de obter este esquema.

Este esquema utiliza o modelo de agrupamento introduzido para o Esquema JSON 2020-12. Embora o DSC ainda possa validar o documento quando utiliza este esquema, outras ferramentas podem efetuar erros ou comportar-se de formas inesperadas.
.../bundled/config/document.vscode.json

O URL para o esquema de criação melhorado. Este esquema é muito maior do que os outros esquemas, uma vez que inclui definições adicionais que fornecem ajuda contextual e fragmentos que os outros não incluem.

Este esquema utiliza palavras-chave que só são reconhecidas pelo VS Code. Embora o DSC ainda possa validar o documento quando utiliza este esquema, outras ferramentas podem efetuar erros ou comportar-se de formas inesperadas.

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
             ]

do IdP

A metadata propriedade define um conjunto de pares chave-valor como anotações para a configuração. O DSC não valida os metadados. Uma configuração pode incluir informações arbitrárias nesta propriedade.

Type:     object
Required: false

parâmetros

A parameters propriedade define um conjunto de opções de runtime para a configuração. Cada parâmetro é definido como par chave-valor. A chave para cada par define o nome do parâmetro . O valor de cada par tem de ser um objeto que defina a type palavra-chave para indicar como o DSC deve processar o parâmetro.

Os parâmetros podem ser substituídos no tempo de execução, o que permite reutilizar o mesmo documento de configuração para diferentes contextos.

Para obter mais informações sobre como definir parâmetros numa configuração, veja DSC Configuration document parameter schema (Esquema de parâmetros de documentos da Configuração do DSC).

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

variáveis

A variables propriedade define um conjunto de valores reutilizáveis para os recursos no documento como pares chave-valor. A chave para cada par define o nome da variável. Os recursos que referenciam a variável por nome podem aceder ao valor da variável.

Isto pode ajudar a reduzir a quantidade de valores copiados e opções para recursos na configuração, o que torna o documento mais fácil de ler e manter. Ao contrário dos parâmetros, as variáveis só podem ser definidas na configuração e não podem ser substituídas no tempo de execução.

Type:     object
Required: false

resources

A resources propriedade define uma lista de instâncias de Recursos do DSC que a configuração gere. Todas as instâncias na lista têm de ser exclusivas, mas as instâncias podem partilhar o mesmo tipo de Recurso DSC.

Para obter mais informações sobre como definir uma instância de recurso válida numa configuração, veja DSC Configuration document resource schema (Esquema de recursos de documentos da Configuração do DSC).

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

Partilhar via