Compartilhar via

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

  • Artigo

Sinopse

Define como testar se uma instância de recurso DSC está no estado desejado.

Metadados

SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json
Type:          object

Descrição

Se um recurso DSC implementar sua própria lógica para determinar se uma instância está no estado desejado, ele deverá definir a test propriedade em seu manifesto. Essa propriedade define como a DSC pode chamar o recurso para testar se uma instância está no estado desejado.

Quando essa propriedade não está definida, a DSC usa um método de teste sintético para o recurso. O método de teste sintético:

  1. Obtém o estado real da instância usando o método do get recurso.
  2. Compara cada propriedade definida do estado desejado da instância com o estado real.
  3. Se o estado desejado de uma propriedade não for igual ao estado real dessa propriedade, a DSC relatará que a instância não está no estado desejado.

Como o teste sintético verifica apenas a equivalência, ele não pode testar com precisão os recursos com propriedades que não podem ser avaliadas apenas com equivalência. Por exemplo, se um recurso gerenciar versões de pacote e permitir a configuração da versão latestcomo , a DSC relatará uma instância com uma versão de 3.1.0 como estando fora do estado desejado, mesmo que 3.1.0 seja a versão mais recente do pacote.

Para recursos com propriedades que não podem ser avaliadas apenas pela equivalência, sempre defina a test propriedade no manifesto.

A 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, a 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 args matriz 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 input propriedade 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 input propriedade , um argumento de entrada JSON na matriz de args propriedades ou ambos.

Exemplos

Exemplo 1 – Definição completa

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

"test": {
  "executable": "registry",
  "args": [
    "config",
    "test"
  ],
  "input": "stdin",
  "return": "state"
}

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

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

Combinado com o valor de executable, o DSC chama o test método para esse recurso executando:

{ ... } | registry config test

O manifesto define return como state, indicando que ele retorna apenas o estado real do recurso quando o test método é executado.

Propriedades obrigatórias

A test definição deve incluir estas propriedades:

Propriedades

executável

A executable propriedade define o nome do comando a ser executado. O valor deve ser o nome de um comando detectável na variável de ambiente do PATH 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 args propriedade 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 jsonInputArg propriedade de cadeia de caracteres e se o argumento é obrigatório para o comando com a mandatory propriedade booliana.

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 a ser passado 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. A 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 o qual passar os dados JSON para o comando, como --input.
  • mandatory (opcional) – indique se a DSC sempre deve passar o argumento para o comando, mesmo quando não há 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 input tipo para um comando, a DSC enviará os dados JSON das duas 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 , o input DSC passará apenas a entrada JSON como uma cadeia de caracteres para o argumento definido.

Se você não definir a input propriedade 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 input propriedade , um argumento de entrada JSON na matriz de args propriedades ou ambos.

Type:                object
RequiredProperties: [jsonInputArg]

input

A input propriedade define como passar a entrada para o recurso. Se essa propriedade não estiver definida, a DSC não enviará nenhuma entrada para o recurso ao invocar a test operação.

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 e minúsculas.

    Essa opção dá suporte apenas aos 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 são de matriz, a DSC define a variável de ambiente como o valor especificado no estado em que se encontra. Quando o tipo de dados é uma matriz de valores, a 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 foo ambiente como "1,2,3".

    Se o recurso precisar dar suporte a propriedades complexas com um object valor ou matrizes de vários tipos, defina-o stdin como .

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

return

A return propriedade 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 real da instância.
  • stateAndDiff – Indica que o recurso retorna o estado real da instância e uma matriz de nomes de propriedade que estão fora do estado desejado.

O valor padrão é state.

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