Partilhar via

Anatomia de um Recurso DSC baseado em comandos

  • Artigo

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

Os Recursos DSC baseados em comandos são definidos com, pelo menos, dois ficheiros:

  1. Um manifesto de Recurso do DSC que indica ao DSC como interagir com o recurso.
  2. Um ou mais ficheiros executáveis e as respetivas dependências para gerir instâncias do recurso.

Manifestos de Recursos do DSC

Os manifestos de Recursos do DSC são definidos como ficheiros JSON. Para o DSC reconhecer um ficheiro JSON como um manifesto, o ficheiro tem de cumprir os seguintes critérios:

  1. O ficheiro tem de ser detetável na variável de PATH ambiente.
  2. O nome do ficheiro tem de terminar com .dsc.resource.json.

Quando o DSC procura recursos DSC disponíveis no sistema local, procura em todas as pastas no PATH ficheiros que utilizam a convenção de nomenclatura do manifesto de Recurso do DSC. Em seguida, o DSC analisa cada um desses ficheiros detetados e valida-os relativamente ao esquema JSON do Manifesto de Recurso do DSC.

Se o ficheiro JSON for validado em relação ao esquema, o DSC pode utilizar o Recurso do DSC.

No mínimo, o manifesto tem de definir:

  • A versão do esquema JSON do Manifesto de Recurso do DSC com o qual é compatível.
  • O nome completamente qualificado do recurso, como Microsoft.Windows/Registry. A sintaxe de nome completamente qualificado é <owner>[.<group>][.<area>]/<name>. Os componentes de grupo e área do nome completamente qualificado permitem organizar recursos em espaços de nomes.
  • Como o DSC pode chamar o comando para obter o estado atual de uma instância de recurso.
  • Uma forma de validar uma instância. Pode ser um dos seguintes:
    • Um esquema JSON que descreve uma instância
    • Um comando DSC tem de chamar para obter o esquema no runtime
    • Um comando para validar recursos aninhados do DSC. Esta última opção aplica-se apenas aos Recursos de Grupo do DSC e aos Recursos do Fornecedor de DSC.

Opcionalmente, o manifesto pode definir:

  • Como o DSC pode chamar o comando para testar se uma instância está no estado pretendido.
  • Como o DSC pode chamar o comando para definir uma instância para o estado pretendido.
  • O significado dos códigos de saída que não são zero devolvidos pelo comando .
  • Como o DSC pode chamar o comando para gerir outros Recursos do DSC, quando o recurso é um Recurso de Grupo do DSC ou um Recurso do Fornecedor de DSC.
  • Metadados sobre o recurso, como o autor e uma breve descrição.

Se o manifesto não definir como testar uma instância do recurso, o DSC efetua um teste sintético para instâncias de recursos. O teste sintético do DSC obtém sempre o estado real de uma instância e faz uma comparação rigorosa e sensível às maiúsculas e minúsculas das propriedades da instância com o estado pretendido. O teste sintético ignora quaisquer propriedades com prefixo com um caráter de sublinhado (_) ou cifrão ($). Se alguma das propriedades não for exatamente igual ao estado pretendido definido, o DSC comunica que a instância não está em conformidade.

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

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

Executáveis de Recursos do DSC

Os Recursos DSC baseados em comandos requerem sempre um ficheiro executável para o DSC ser executado. O Manifesto de Recurso do DSC não precisa de ser agrupado com o executável. O executável pode ser qualquer ficheiro executável, como uma aplicação binária ou um script de shell. Um recurso pode utilizar executáveis diferentes para operações diferentes.

Para o DSC utilizar um executável, tem de ser detetável na variável de PATH ambiente. O DSC chama o executável uma vez por operação, utilizando o código de saída devolvido pelo executável para determinar se o comando foi bem-sucedido. O 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

O DSC envia a entrada para recursos DSC baseados em comandos como um blob de dados JSON através de stdin ou como um conjunto de sinalizadores e valores de argumentos. O processamento de entrada é definido por operação no Manifesto de Recurso do DSC.

Quando o DSC envia a entrada como JSON através de stdin, o blob de dados é a representação JSON do estado pretendido de uma instância. Esta é a opção mais robusta para um recurso, uma vez que permite que o recurso suporte propriedades complexas com objetos aninhados.

Quando o DSC envia a entrada como argumentos, gera um par de argumentos para cada uma das propriedades especificadas. O primeiro argumento é o nome da propriedade com o prefixo , --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.

Saídas

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

Para os Recursos do Fornecedor de DSC, o DSC espera que o executável passe pelos estados de instância dos recursos que gere como uma única matriz JSON ou como uma série de Linhas JSON.

Os Recursos DSC baseados em comandos podem comunicar informações de registo ao DSC ao emitir Linhas JSON para stderr. Cada entrada de registo tem de ser um objeto JSON que inclua duas chaves:

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

O DSC recolhe mensagens de recursos e apresenta-as nos resultados de uma operação de configuração. Quando o DSC invoca um recurso diretamente fora de uma configuração, não recolhe as mensagens. Em vez disso, são apenas emitidas para stderr.

Conteúdo relacionado