Referência do esquema de propriedade do conjunto de manifestos de recursos do DSC

Artigo
05/11/2024

Sinopse

Define como impor o estado para uma instância de Recurso do DSC.

Metadados

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

Description

Para gerir uma instância com o DSC, um Recurso do DSC tem de definir a set propriedade no respetivo manifesto. Esta propriedade define como o DSC pode impor o estado atual de uma instância.

Quando esta propriedade não está definida, o DSC só pode obter o estado atual das instâncias e testar se estão no estado pretendido. O DSC não consegue impor o estado pretendido para o recurso.

O DSC envia dados para o comando de três formas:

Quando input é stdin, o DSC envia os dados como uma cadeia que representa os dados como um objeto JSON comprimido sem espaços ou novas linhas entre as propriedades do objeto.
Quando input é env, o DSC envia os dados como variáveis de ambiente. Cria uma variável de ambiente para cada propriedade no objeto de dados de entrada, utilizando o nome e o valor da propriedade.
Quando a args matriz inclui uma definição de argumento de entrada JSON, o DSC envia os dados como uma cadeia que representa os dados como um objeto JSON comprimido para o argumento especificado.

Se não definir a input propriedade e não definir um argumento de entrada JSON, o DSC não poderá transmitir o JSON de entrada para o recurso. Só pode definir um argumento de entrada JSON para um comando.

Tem de definir a input propriedade, um argumento de entrada JSON na matriz de args propriedades ou ambos.

Exemplos

Exemplo 1 - Definição completa

Este exemplo é do Recurso do Microsoft.Windows/Registry DSC.

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

Define executable como registry, em vez de registry.exe. A extensão não é necessária quando o sistema operativo reconhece o comando como um executável.

O manifesto define dois argumentos config e set. O valor da input propriedade indica que o comando espera a set respetiva entrada como um blob JSON de stdin.

Combinado com o valor para executable, o DSC chama o método set para este recurso ao executar:

{ ... } | registry config set

Uma vez que o manifesto define implementsPretest como true, o DSC não chamará o test método do recurso antes de chamar set. Esta definição indica que o próprio recurso testa instâncias antes de impor o estado pretendido.

O manifesto define return como state, indicando que só devolve o estado final do recurso após a execução do set método. O DSC compara o estado pretendido com os dados devolvidos deste recurso para identificar quais das propriedades do recurso o set método imposto, se existirem.

Propriedades Necessárias

A set definição tem de incluir estas propriedades:

executável

Propriedades

executável

A executable propriedade define o nome do comando a executar. O valor tem de ser o nome de um comando detetável na variável de ambiente do PATH sistema ou o caminho completo para o comando. Uma extensão de ficheiro só é necessária quando o comando não é reconhecível pelo sistema operativo como executável.

Type:     string
Required: true

args

A args propriedade define a lista de argumentos a transmitir para o comando . Os argumentos podem ser qualquer número de cadeias. Se quiser transmitir o objeto JSON que representa o saco de propriedades do recurso para um argumento, pode definir um único item na matriz como um [objeto JSON], indicando o nome do argumento com a jsonInputArg propriedade de cadeia e se o argumento é obrigatório para o comando com a mandatory propriedade booleana.

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

Argumentos de cadeia

Qualquer item na matriz de argumentos pode ser uma cadeia que representa um argumento estático para passar para o comando, como config ou --format.

Type: string

Argumento de entrada JSON

Define um argumento para o comando que aceita o objeto de entrada JSON como uma cadeia. O DSC transmite a entrada JSON para o argumento com nome quando disponível. Um argumento de entrada JSON é definido como um objeto JSON com as seguintes propriedades:

jsonInputArg (obrigatório) – o argumento para transmitir os dados JSON para para o comando, como --input.
mandatory (opcional) - Indique se o DSC deve passar sempre o argumento para o comando, mesmo quando não existe nenhuma entrada JSON para o comando. Nesse caso, o DSC transmite uma cadeia vazia ao argumento de entrada JSON.

Só pode definir um argumento de entrada JSON por matriz de argumentos.

Se definir um argumento de entrada JSON e um input tipo para um comando, o DSC envia os dados JSON de ambas as formas:

Se definir input como env e um argumento de entrada JSON, o DSC define uma variável de ambiente para cada propriedade na entrada JSON e transmite o objeto de entrada JSON como uma cadeia para o argumento definido.
Se definir input como stdin e um argumento de entrada JSON, o DSC transmite a entrada JSON sobre stdin e como uma cadeia para o argumento definido.
Se definir um argumento de entrada JSON sem definir a propriedade, o input DSC só transmite a entrada JSON como uma cadeia para o argumento definido.

Se não definir a input propriedade e não definir um argumento de entrada JSON, o DSC não poderá transmitir o JSON de entrada para o recurso. Isto torna o manifesto inválido. Tem de definir a input propriedade, um argumento de entrada JSON na matriz de args propriedades ou ambos.

Type:                object
RequiredProperties: [jsonInputArg]

entrada

A input propriedade define como transmitir entradas para o recurso. Se esta propriedade não estiver definida e a definição não definir um argumento de entrada JSON, o DSC não envia nenhuma entrada para o recurso ao invocar a set operação.

O valor desta propriedade tem de ser uma das seguintes cadeias:

env - Indica que o recurso espera que as propriedades de uma instância sejam especificadas como variáveis de ambiente com os mesmos nomes e maições.

Esta opção suporta apenas os seguintes tipos de dados para propriedades de instância:
- boolean
- integer
- number
- string
- array de integer valores
- array de number valores
- array de string valores
Para valores que não sejam de matriz, o DSC define a variável de ambiente para o valor especificado tal como está. Quando o tipo de dados é uma matriz de valores, o DSC define a variável de ambiente como uma cadeia delimitada por vírgulas. Por exemplo, a propriedade foo com um valor de [1, 2, 3] é guardada na variável de foo ambiente como "1,2,3".

Se o recurso precisar de suportar propriedades complexas com um object valor ou matrizes de vários tipos, defina esta opção como stdin .
stdin - Indica que o recurso espera um blob JSON que representa uma instância de stdin. O JSON tem de cumprir o esquema da instância do recurso.

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

implementsPretest

A implementsPretest propriedade define se o recurso testa se a instância está no estado pretendido internamente antes de impor o estado pretendido. Defina esta propriedade como true quando o recurso testar a instância como parte da set operação. Defina esta propriedade como false quando não o faz.

Quando este valor é false, indica que os utilizadores devem sempre chamar dsc resource test contra a instância antes de invocar o dsc resource set comando contra o recurso.

O valor predefinido é false.

Type:     boolean
Required: false
Default:  false

handlesExist

A handlesExist propriedade define se o recurso tem processamento incorporado para a propriedade _exist na set operação. O valor predefinido é false.

Defina esta propriedade para true quando o recurso cumprir os seguintes requisitos de implementação:

O esquema de instância do recurso define a _exist propriedade como uma propriedade de instância válida.
O comando do set recurso processa a criação, atualização e eliminação de uma instância com base no estado atual da instância e no valor da _exist propriedade no estado pretendido.

Quando esta propriedade está definida como true, o recurso indica que tem a capacidade SetHandlesExist. Ao processar recursos com a SetHandlesExist capacidade numa configuração, o DSC chama a set operação para o recurso quando uma instância define _exist como false. Sem esta capacidade, um recurso tem de definir a operação de eliminação para suportar a remoção de instâncias do recurso.

Se um manifesto de recurso não definir esta propriedade como true e não definir a operação, o delete DSC gera um erro quando encontra uma instância do recurso com _exist definido como false.

regressar

A return propriedade define como o DSC deve processar a saída para este método. O valor desta propriedade tem de ser uma das seguintes cadeias:

state - Indica que o recurso devolve apenas o estado final da instância após a operação definida como um blob JSON.
stateAndDiff - Indica que o recurso devolve o estado final da instância e uma matriz de nomes de propriedade que o recurso modificou.

O valor predefinido é state.

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

Partilhar via