Partilhar via

Anatomia de um recurso DSC baseado em comando

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

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

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

Manifestos de recursos DSC

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

  1. Os dados no arquivo devem ser formatados como YAML ou JSON.

  2. O arquivo deve usar codificação UTF-8.

  3. O arquivo deve ser detetável na PATH variável de ambiente.

  4. O nome do arquivo deve terminar com um dos seguintes sufixos:

    • .dsc.resource.json
    • .dsc.resource.yaml
    • .dsc.resource.yml

Quando o DSC procura recursos de comando disponíveis no sistema local, ele procura em todas as pastas arquivos PATH que usam a convenção de nomenclatura do manifesto de recursos do DSC. Em seguida, o DSC analisa cada um desses arquivos descobertos e os valida em relação ao esquema JSON do Manifesto de Recursos 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 de manifesto de recurso DSC com a qual é compatível.
  • O nome totalmente qualificado do recurso, como Microsoft.Windows/Registry. A sintaxe de nome totalmente qualificada é <owner>[.<group>][.<area>]/<name>. Os componentes de grupo e área do nome totalmente qualificado permitem organizar recursos em namespaces.
  • Como o DSC pode chamar o comando para obter o estado atual de uma instância de recurso.
  • Uma maneira de validar uma instância. As opções para validar uma instância incluem:
    • Um esquema JSON que descreve uma instância
    • Um comando DSC deve chamar para obter o esquema em tempo de execução
    • Um comando para validar recursos DSC aninhados. Esta última opção aplica-se apenas aos recursos do grupo DSC e aos recursos do adaptador DSC.

O manifesto pode definir:

  • O tipo de recurso que o manifesto descreve: adapter, group, importer, ou resource.

    Se o manifesto não definir o tipo de recurso, ele assume resource como padrão e é interpretado como um recurso típico que gerencia diretamente uma instância.

  • Como o DSC pode chamar o comando para testar se uma instância está no estado desejado.

    Se o manifesto não definir como testar uma instância do recurso, o DSC executará um teste sintético para instâncias de recurso. O teste sintético do DSC sempre obtém o estado real de uma instância e faz uma comparação rigorosa que diferencia maiúsculas de minúsculas das propriedades da instância com o estado desejado. Se qualquer uma das propriedades não for exatamente igual ao estado desejado definido, o DSC relatará a instância como não compatível.

  • Como o DSC pode chamar o comando para definir uma instância para o estado desejado.

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

  • O significado dos códigos de saída diferentes de zero retornados pelo comando.

    Se o manifesto não definir o significado dos códigos de saída, todos os códigos de saída diferentes de zero serão relatados como uma falha genérica.

  • Como o DSC pode chamar o comando para exportar uma lista de cada instância desse recurso na máquina.

  • Como o DSC pode chamar o comando para excluir uma instância específica do recurso.

  • Metadados sobre o recurso, como o seu autor e uma breve descrição.

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 recursos DSC

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

Para que o DSC use um executável, ele deve ser detetável na PATH variável de ambiente. O 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. O DSC trata o código 0 de saída como um sucesso e todos os outros códigos de saída como um erro.

Insumos

O DSC envia entrada para recursos de comando de uma das seguintes maneiras:

  • Um blob de dados JSON sobre stdin.

    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. Esta opção de entrada suporta propriedades complexas com objetos aninhados.

  • Um blob de dados JSON como o valor para um argumento específico.

    Quando o recurso define um argumento de entrada JSON, o DSC invoca o comando com o argumento definido e passa a representação JSON do estado desejado de uma instância para esse argumento. Esta opção de entrada suporta propriedades complexas com objetos aninhados.

  • Um conjunto de sinalizadores e valores de argumento.

    Quando o DSC envia a entrada como argumentos, ele 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. Este método de entrada não suporta propriedades complexas.

  • Variáveis de ambiente.

    Quando o DSC envia a entrada como variáveis de ambiente, ele define uma variável de ambiente para cada propriedade da instância de recurso e define o valor para a representação de cadeia de caracteres dessa propriedade. Essas variáveis de ambiente são definidas apenas para a execução do comando para essa operação específica. As variáveis de ambiente não afetam nenhum outro processo.

A manipulação de entrada é definida por operação no manifesto do recurso. Um recurso pode definir diferentes manipulações de entrada para as operações às quais dá suporte.

Saídas

O executável para um recurso de 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 adaptador, o DSC espera que o executável passe pelos estados da instância para os recursos que gerencia como uma única matriz JSON ou como uma série de linhas JSON.

Os recursos de comando podem relatar informações de log para 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 por humanos para a entrada de log.
  2. A level chave define se a mensagem representa um error, um warningou information.

O 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, o DSC emite as mensagens para stderr.

Conteúdo relacionado

  • Last updated on