Compartilhar via

Referência de 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 o --what-if opção 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 de 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 de hipóteses sintético não retornará informações suficientes ao usuário:

  • Um recurso que exige um parâmetro de credencial pode testar com êxito a instância, mas não ter 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 precisa investigar. Se outros recursos forem aplicados com êxito antes da instância que falhou, o sistema poderá 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 de um resultado sintético. Depois de examinar o impacto da configuração com base no resultado de hipóteses, um usuário poderá 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 usar parâmetros ou retornar propriedades somente leitura de uma operação de 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 de hipóteses.

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 linhas novas 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 de 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 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 esse recurso executando:

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

O manifesto define return como state, indicando que ele retorna apenas o estado final esperado do recurso após a execução do método set. O DSC compara o estado desejado com os dados de retorno desse recurso para identificar quais das propriedades do recurso o método set aplicará, 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 detectável na variável de ambiente PATH do sistema ou no caminho completo para o comando. Uma extensão de arquivo só é necessária quando o comando não é reconhecível pelo sistema operacional como 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 cadeias de caracteres. Se você quiser passar o objeto JSON que representa o recipiente de propriedades do recurso para um argumento, poderá definir um único item na matriz como um objeto JSON, indicando o nome do argumento com a propriedade de cadeia de caracteres jsonInputArg e se o argumento é obrigatório para o comando com a propriedade booliana 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 houver nenhuma 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 de 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 maiúsculas.

    Essa opção só dá suporte aos seguintes tipos de dados para propriedades de instância:

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

    Para valores que não são 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írgulas. 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 dar suporte a propriedades complexas com um valor object ou matrizes de vários tipos, defina-o como stdin em vez disso.

  • stdin - Indica que o recurso espera um blob JSON que representa uma instância de stdin. O JSON deve aderir ao esquema de instância do 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 para true quando o recurso testar a instância como parte da operação de set. Defina essa propriedade como false quando não o fizer. 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 sempre devem chamar dsc resource test na instância antes de invocar o comando dsc resource set no recurso.

O valor padrão é false.

Type:     boolean
Required: false
Default:  false

handlesExist

A propriedade handlesExist define se o recurso tem tratamento interno 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 para true quando o recurso atender aos seguintes requisitos de implementação:

  • O esquema de instância de do recurso define a propriedade _exist como uma propriedade de instância válida.
  • O comando set do recurso manipula 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 , o recurso indica que ela tem a funcionalidadeSetHandlesExist . 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 essa funcionalidade, 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 de delete, o DSC gerará um erro quando encontrar uma instância do recurso com _exist definido como false.

retornar

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 apenas 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]