Share via

Anatomia de um recurso DSC baseado em comando

  • Artigo

Os recursos de DSC fornecem uma interface padronizada para gerenciar as configurações de um sistema. Um recurso define as propriedades que você pode gerenciar e implementa o código necessário para obter uma instância do recurso.

Os recursos DSC baseados em comando são definidos com pelo menos dois arquivos:

  1. Um manifesto de recurso DSC que informa à DSC como interagir com o recurso.
  2. Um ou mais arquivos executáveis e suas dependências para gerenciar instâncias do recurso.

Manifestos do recurso DSC

Os manifestos de recurso DSC são definidos como arquivos JSON. Para que a DSC reconheça um arquivo JSON como um manifesto, o arquivo deve atender aos seguintes critérios:

  1. O arquivo deve ser detectável na variável de PATH ambiente.
  2. O nome do arquivo deve terminar com .dsc.resource.json.

Quando o DSC pesquisa recursos DSC baseados em comando disponíveis no sistema local, ele pesquisa todas as pastas no PATH para arquivos que usam a convenção de nomenclatura do manifesto do recurso DSC. Em seguida, a DSC analisa cada um desses arquivos descobertos e os valida no esquema JSON do manifesto de recurso DSC.

Se o arquivo JSON for validado em relação ao esquema, o DSC poderá usar o recurso DSC.

No mínimo, o manifesto deve definir:

  • A versão do esquema JSON do manifesto de recurso DSC com a qual ele é compatível.
  • O nome totalmente qualificado do recurso, como Microsoft.Windows/Registry. A sintaxe de nome totalmente qualificado é <owner>[.<group>][.<area>]/<name>. Os componentes de grupo e área do nome totalmente qualificado permitem organizar recursos em namespaces.
  • Como a DSC pode chamar o comando para obter o estado atual de uma instância de recurso.
  • Uma maneira de validar uma instância. Pode ser um dos seguintes:
    • Um esquema JSON que descreve uma instância
    • Uma DSC de comando deve chamar para obter o esquema em runtime
    • Um comando para validar recursos aninhados de DSC. Essa última opção só se aplica a recursos de grupo de DSC e recursos do provedor de DSC.

Opcionalmente, o manifesto pode definir:

  • Como a DSC pode chamar o comando para testar se uma instância está no estado desejado.
  • Como a DSC pode chamar o comando para definir uma instância para o estado desejado.
  • O significado dos códigos de saída diferentes de zero retornados pelo comando .
  • Como a DSC pode chamar o comando para gerenciar outros recursos de DSC, quando o recurso é um recurso de grupo de DSC ou um recurso de provedor de DSC.
  • Metadados sobre o recurso, como seu autor e uma breve descrição.

Se o manifesto não definir como testar uma instância do recurso, a DSC executará um teste sintético para instâncias de recurso. O teste sintético da DSC sempre obtém o estado real de uma instância e faz uma comparação estrita que diferencia maiúsculas de minúsculas das propriedades da instância com o estado desejado. O teste sintético ignora todas as propriedades prefixadas com um sublinhado (_) ou cifrão ($). Se qualquer uma das propriedades não for exatamente igual ao estado desejado definido, a DSC relatará que a instância não está em conformidade.

Se o manifesto não definir como definir uma instância do Recurso DSC, a DSC não poderá usar o recurso para impor o estado desejado.

O manifesto não precisa especificar o mesmo arquivo executável para cada operação. A definição para cada operação é independente.

Executáveis de recurso DSC

Os recursos DSC baseados em comando sempre exigem um arquivo executável para que a DSC seja executada. O manifesto do recurso DSC não precisa ser agrupado com o executável. O executável pode ser qualquer arquivo executável, como um aplicativo binário ou um script de shell. Um recurso pode usar executáveis diferentes para operações diferentes.

Para que a DSC use um executável, ela deve ser detectável na variável de PATH ambiente. A DSC chama o executável uma vez por operação, usando o código de saída retornado pelo executável para determinar se o comando foi bem-sucedido. A DSC trata o código 0 de saída como um êxito e todos os outros códigos de saída como um erro.

Entradas

A DSC envia a entrada para recursos DSC baseados em comando como um blob de dados JSON sobre stdin ou como um conjunto de sinalizadores e valores de argumento. A manipulação de entrada é definida por operação no manifesto de recurso DSC.

Quando o DSC envia a entrada como JSON sobre stdin, o blob de dados é a representação JSON do estado desejado de uma instância. Essa é a opção mais robusta para um recurso, pois permite que o recurso dê suporte a propriedades complexas com objetos aninhados.

Quando a DSC envia a entrada como argumentos, ela gera um par de argumentos para cada uma das propriedades especificadas. O primeiro argumento é o nome da propriedade prefixada com --, como --duration. O segundo argumento é o valor da propriedade. A ordenação dos pares de argumentos não é garantida. Esse método de entrada não dá suporte a propriedades complexas.

Saídas

O executável para um recurso DSC baseado em comando deve retornar dados JSON para stdout quando chamado pelo DSC. A codificação de saída deve ser UTF-8. Quando o recurso retorna o estado de uma instância, o DSC valida os dados JSON em relação ao esquema de instância do recurso.

Para recursos do provedor de DSC, a DSC espera que o executável passe pelos estados de instância para os recursos que gerencia como uma única matriz JSON ou como uma série de linhas JSON.

Os recursos DSC baseados em comando podem relatar informações de registro em log para a DSC emitindo linhas JSON para stderr. Cada entrada de log deve ser um objeto JSON que inclua duas chaves:

  1. A message chave define a cadeia de caracteres legível para a entrada de log.
  2. A level chave define se a mensagem representa um Error, um Warningou Information.

A DSC coleta mensagens de recursos e as exibe nos resultados de uma operação de configuração. Quando o DSC invoca um recurso diretamente fora de uma configuração, ele não coleta as mensagens. Em vez disso, eles são apenas emitidos para stderr.

Conteúdo relacionado