Partilhar via

Referência do esquema de propriedade whatIf do manifesto do recurso DSC

  • Artigo

Sinopse

Define como indicar se e como o comando set modificará uma instância.

Metadados

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

Descrição

Ao impor um documento de configuração com o comando dsc config set, os usuários podem especificar a opção --what-if para ver se e como os recursos alterarão o estado do sistema sem realmente fazê-lo. Essa propriedade define como o DSC pode invocar o recurso para retornar essas informações diretamente.

Quando essa propriedade não é definida, o DSC sintetiza esse comportamento convertendo o resultado de uma operação de teste em relação ao recurso em um resultado definido. O resultado sintético só pode indicar como a operação alterará as propriedades do recurso. Ele não pode indicar se a operação set falhará devido a parâmetros inválidos ou quais propriedades somente leitura o recurso retornará da operação. A lista a seguir descreve alguns casos em que um resultado hipotético sintético não retornará informações suficientes para o usuário:

  • Um recurso que requer um parâmetro de credencial pode testar a instância com êxito, mas não tem permissões para modificá-la. Nesse caso, o usuário pode executar dsc config set --what-if e ver uma previsão aparentemente bem-sucedida para o recurso. Em seguida, quando eles executam o comando sem a opção --what-if, o recurso gera um erro que o usuário tem que investigar. Se quaisquer outros recursos aplicados com êxito antes da instância que falhou, o sistema pode ser deixado em um estado parcialmente configurado.
  • Um recurso com um serviço de dependência não poderá relatar se esse serviço precisa ser reiniciado a partir de um resultado sintético. Depois de analisar o impacto da configuração com base no resultado hipotético, um usuário pode reiniciar inadvertidamente um serviço ou deixar a configuração em um estado parcialmente configurado até que esse serviço seja reinicializado.

Se o recurso usa parâmetros ou retorna propriedades somente leitura de uma operação set, defina esse método para garantir que os usuários obtenham as melhores informações sobre se e como o recurso modificará o estado do sistema no modo hipotético.

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

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

Se você não definir a propriedade input e não definir um argumento de entrada JSON, o DSC não poderá passar o JSON de entrada para o recurso. Você só pode definir um argumento de entrada JSON para um comando.

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

Exemplos

Exemplo 1 - Definição completa

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

Ele define executable como my_app, em vez de my_app.exe. A extensão não é necessária quando o sistema operacional reconhece o comando como um executável.

O manifesto define três argumentos: config, sete --what-if. O valor da propriedade input indica que o comando whatIf espera sua entrada como um blob JSON de stdin.

Combinado com o valor de executable, o DSC chama o método what-if para este recurso executando:

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

O manifesto define return como state, indicando que ele só retorna o estado final esperado do recurso depois que o método set é executado. O DSC compara o estado desejado com os dados de retorno desse recurso para identificar quais das propriedades do recurso o método set irá impor, se houver.

Propriedades necessárias

A definição de whatIf deve incluir estas propriedades:

  • executável

Propriedades

executável

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

Type:     string
Required: true

Args

A propriedade args define a lista de argumentos a serem passados para o comando. Os argumentos podem ser qualquer número de strings. Se desejar passar o objeto JSON que representa o conjunto de propriedades do recurso para um argumento, você pode definir um único item na matriz como um objeto JSON, indicando o nome do argumento com a propriedade string jsonInputArg e se o argumento é obrigatório para o comando com a propriedade booleana mandatory.

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

Argumentos de cadeia de caracteres

Qualquer item na matriz de argumentos pode ser uma cadeia de caracteres 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 de caracteres. O DSC passa a entrada JSON para o argumento nomeado quando disponível. Um argumento de entrada JSON é definido como um objeto JSON com as seguintes propriedades:

  • jsonInputArg (obrigatório) - o argumento para passar os dados JSON para o comando, como --input.
  • mandatory (opcional) - Indique se o DSC deve sempre passar o argumento para o comando, mesmo quando não há entrada JSON para o comando. Nesse caso, o DSC passa uma cadeia de caracteres vazia para o argumento de entrada JSON.

Você só pode definir um argumento de entrada JSON por matriz de argumentos.

Se você definir um argumento de entrada JSON e um tipo de input para um comando, o DSC enviará os dados JSON de ambas as maneiras:

  • Se você definir input como env e um argumento de entrada JSON, o DSC definirá uma variável de ambiente para cada propriedade na entrada JSON e passará o objeto de entrada JSON como uma cadeia de caracteres para o argumento definido.
  • Se você definir input como stdin e um argumento de entrada JSON, o DSC passará a entrada JSON sobre stdin e como uma cadeia de caracteres para o argumento definido.
  • Se você definir um argumento de entrada JSON sem definir a propriedade input, o DSC passará apenas a entrada JSON como uma cadeia de caracteres para o argumento definido.

Se você não definir a propriedade input e não definir um argumento de entrada JSON, o DSC não poderá passar o JSON de entrada para o recurso. Isso torna o manifesto inválido. Você deve definir a propriedade input, um argumento de entrada JSON na matriz de propriedades args ou ambos.

Type:                object
RequiredProperties: [jsonInputArg]

entrada

A propriedade input define como passar a entrada para o recurso. Se essa propriedade não estiver definida e a definição não definir um argumento de entrada JSON, o DSC não enviará nenhuma entrada para o recurso ao invocar a operação whatIf.

O valor dessa propriedade deve ser uma das seguintes cadeias de caracteres:

  • 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 invólucro.

    Esta opção suporta apenas os seguintes tipos de dados para propriedades de exemplo:

    • boolean
    • integer
    • number
    • string
    • array de valores de integer
    • array de valores de number
    • array de valores de string

    Para valores que não sejam de matriz, o DSC define a variável de ambiente como o valor especificado as-is. Quando o tipo de dados é uma matriz de valores, o DSC define a variável de ambiente como uma cadeia de caracteres delimitada por vírgula. Por exemplo, a propriedade foo com um valor de [1, 2, 3] é salva na variável de ambiente foo como "1,2,3".

    Se o recurso precisar oferecer suporte a propriedades complexas com um valor object ou matrizes de vários tipos, defina isso como stdin em vez disso.

  • stdin - Indica que o recurso espera um blob JSON representando uma instância de stdin. O JSON deve aderir ao esquema de instância para o recurso.

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

implementsPretest

A propriedade implementsPretest define se o recurso testa se a instância está no estado desejado internamente antes de impor o estado desejado. Defina essa propriedade como true quando o recurso testar a instância como parte da operação set. Defina essa propriedade como false quando isso não acontecer. Na maioria dos casos, esse valor deve ser definido da mesma forma que a propriedade implementsPretest na definição do método set no manifesto do recurso.

Quando esse valor é false, ele indica que os usuários devem sempre chamar dsc resource test contra a instância antes de invocar o comando dsc resource set contra o recurso.

O valor padrão é false.

Type:     boolean
Required: false
Default:  false

handlesExist

A propriedade handlesExist define se o recurso tem manipulação interna para a propriedade _exist na operação set. O valor padrão é false. Na maioria dos casos, esse valor deve ser definido da mesma forma que a propriedade implementsPretest na definição do método set no manifesto do recurso.

Defina essa propriedade como true quando o recurso atender aos seguintes requisitos de implementação:

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

Quando essa propriedade é definida como true, o recurso indica que ele tem o SetHandlesExistcapacidade. Ao processar recursos com o recurso SetHandlesExist em uma configuração, o DSC chama a operação set para o recurso quando uma instância define _exist como false. Sem esse recurso, um recurso deve definir o excluir operação para dar suporte à remoção de instâncias do recurso.

Se um manifesto de recurso não definir essa propriedade como true e não definir a operação delete, o DSC gerará um erro quando encontrar uma instância do recurso com _exist definida como false.

regresso

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

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

O valor padrão é state.

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