Referência de esquema de documento de configuração de DSC

Artigo
05/11/2024

Sinopse

O arquivo YAML ou JSON que define uma configuração de 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

Descrição

As Configurações de DSC permitem que os usuários definam o estado combinando diferentes recursos de DSC. Um documento de configuração usa parâmetros e variáveis para passar para um conjunto de um ou mais recursos que definem um estado desejado.

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 da DSC reconheçam um arquivo como um documento de Configuração de DSC, o nome do arquivo deve terminar com .dsc.config.json, .dsc.config.ymlou .dsc.config.yaml.

Você pode usar funções de documento de configuração para determinar dinamicamente os valores no documento em runtime. Para obter mais informações, consulte Referência de funções de documento de configuração de DSC

O restante deste documento descreve o esquema que a DSC usa para validar documentos de configuração.

Exemplos

Propriedades obrigatórias

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

[$schema]
[recursos]

Propriedades

$schema

A $schema propriedade indica a URL canônica da versão desse esquema à qual o documento segue. A DSC usa essa propriedade ao validar o documento de configuração antes de qualquer operação de configuração.

Atualmente, há três versões publicadas do esquema, compatíveis com diferentes versões do DSC:

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

Esta documentação destina-se à versão mais recente do esquema. Você deve atualizar seus documentos de configuração e 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 nenhuma atualização.

Para cada versão do esquema, há três URLs válidas:

.../config/document.json

A URL para o esquema canônico não empacotado. Quando ele é usado para validação, o cliente de validação precisa recuperar esse esquema e todos os esquemas referenciados.
.../bundled/config/document.json

A URL para o esquema agrupado. Quando ele é usado para validação, o cliente de validação só precisa recuperar esse esquema.

Esse esquema usa o modelo de agrupamento introduzido para o Esquema JSON 2020-12. Embora a DSC ainda possa validar o documento quando ele usa esse esquema, outras ferramentas podem erro ou se comportar de maneiras inesperadas.
.../bundled/config/document.vscode.json

A URL para o esquema de criação aprimorado. Esse esquema é muito maior do que os outros esquemas, pois inclui definições adicionais que fornecem ajuda contextual e snippets que os outros não incluem.

Esse esquema usa palavras-chave que são reconhecidas apenas pelo VS Code. Embora a DSC ainda possa validar o documento quando ele usa esse esquema, outras ferramentas podem erro ou se comportar de maneiras 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
             ]

metadata

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

Type:     object
Required: false

parameters

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 deve ser um objeto que define o type palavra-chave para indicar como a DSC deve processar o parâmetro.

Os parâmetros podem ser substituídos em tempo de execução, permitindo o reutilização do mesmo documento de configuração para contextos diferentes.

Para obter mais informações sobre como definir parâmetros em uma configuração, consulte Esquema de parâmetro de documento de configuração de 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 fazem referência à variável por nome podem acessar o valor da variável.

Isso pode ajudar a reduzir a quantidade de valores e opções copiados para recursos na configuração, o que facilita a leitura e a manutenção do documento. Ao contrário dos parâmetros, as variáveis só podem ser definidas na configuração e não podem ser substituídas em tempo de execução.

Type:     object
Required: false

recursos

A resources propriedade define uma lista de instâncias de recurso DSC que a configuração gerencia. Cada instância na lista deve ser exclusiva, mas as instâncias podem compartilhar o mesmo tipo de recurso DSC.

Para obter mais informações sobre como definir uma instância de recurso válida em uma configuração, consulte Esquema de recurso de documento de configuração de DSC.

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

Compartilhar via