Compartilhar via

Referência de esquema de manifesto do recurso DSC baseado em comando

  • Artigo

Sinopse

O arquivo de dados que define um recurso DSC baseado em comando.

Metadados

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

Descrição

Cada recurso DSC baseado em comando deve ter um manifesto. O arquivo de manifesto deve:

  1. Seja detectável na variável de ambiente PATH.
  2. Seja formatado como JSON ou YAML.
  3. Siga a convenção de nomenclatura <name>.dsc.resource.<extension>. As extensões válidas incluem json, ymle yaml.
  4. Seja válido para o esquema descrito neste documento.

O restante deste documento descreve o esquema do manifesto.

Propriedades necessárias

O manifesto deve incluir estas propriedades:

Propriedades

$schema

A propriedade $schema indica o URI canônico desse esquema no qual o manifesto é validado. Essa propriedade é obrigatória. O DSC usa esse valor para validar o manifesto no esquema JSON correto.

Para cada versão do esquema, há três URLs válidas:

  • .../resource/manifest.json

    A URL para o esquema não empacotado canônico. Quando ele é usado para validação, o cliente de validação precisa recuperar esse esquema e todos os esquemas que ele faz referência.

  • .../bundled/resource/manifest.json

    A URL para o esquema agrupado. Quando ele é usado para validação, o cliente de validação só precisa recuperar esse esquema.

    Esse esquema usa o modelo de agrupamento introduzido para o Esquema JSON 2020-12. Embora o DSC ainda possa validar o documento quando ele usa esse esquema, outras ferramentas podem erro ou se comportar de maneiras inesperadas.

  • .../bundled/resource/manifest.vscode.json

    A URL para o esquema de criação aprimorado. Esse esquema é muito maior do que os outros esquemas, pois inclui definições adicionais que fornecem ajuda contextual e snippets que os outros não incluem.

    Esse esquema usa palavras-chave que são reconhecidas apenas pelo VS Code. Embora o DSC ainda possa validar o documento quando ele usa esse esquema, outras ferramentas podem erro ou se comportar de maneiras inesperadas.

Type:        string
Required:    true
Format:      URI
ValidValues: [
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json
             ]

tipo

A propriedade type representa o nome de tipo totalmente qualificado do recurso. Ele é usado para especificar o recurso em documentos de configuração e como o valor do sinalizador --resource ao usar os comandos dsc resource *. Para obter mais informações sobre nomes de tipo de recurso, consulte referência de esquema de nome de tipo totalmente qualificado do Recurso DSC.

Type:     string
Required: true
Pattern:  ^\w+(\.\w+){0,2}\/\w+$

Versão

A propriedade version deve ser a versão atual do recurso como uma cadeia de caracteres semântica (semver) válida. A versão se aplica ao recurso, não ao software que ele gerencia.

Type:     string
Required: true
Pattern:  ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

descrição

A propriedade description define uma sinopse para a finalidade do recurso. O valor dessa propriedade deve ser uma cadeia de caracteres curta.

Type:     string
Required: false

tipo

A propriedade kind define como o DSC deve lidar com o recurso. O DSC dá suporte a três tipos de recursos DSC baseados em comando: Resource, Groupe Adapter.

Quando kind não é definido no manifesto do recurso, o DSC infere o valor da propriedade. Se a propriedade adapter for definida no manifesto do recurso, o DSC inferirá o valor de kind como Adapter. Se a propriedade adapter não estiver definida, o DSC inferirá o valor de kind como Resource. A DSC não pode inferir se um manifesto é para um recurso de grupo.

Ao definir um recurso de grupo, sempre defina explicitamente a propriedade kind no manifesto como Group.

Para obter mais informações, consulte referência de esquema de tipo de recurso DSC.

Type:        string
Required:    false
ValidValues: [Resource, Adapter, Group]

Tags

A propriedade tags define uma lista de termos pesquisáveis para o recurso. O valor dessa propriedade deve ser uma matriz de cadeias de caracteres. Cada marca deve conter apenas caracteres alfanuméricos e sublinhados. Nenhum outro caractere é permitido. Cada marca deve ser exclusiva.

Type:              array
Required:          false
ItemsMustBeUnique: true
ItemsType:         string
ItemsPattern:      ^\w+$

exportação

A propriedade export define como chamar o recurso para obter o estado atual de cada instância. Quando essa propriedade é definida, os usuários podem:

  • Especifique uma instância do recurso na configuração de entrada para o comando de exportação de configuração dsc para gerar um documento de configuração utilizável.
  • Especifique o recurso com o comando dsc resource export para gerar um documento de configuração que define todas as instâncias do recurso.
  • Especifique o recurso com o comando recurso dsc get e o -- todas as opção para retornar o estado atual para cada instância do recurso.

O valor dessa propriedade deve ser um objeto. A propriedade executable do objeto, definindo o nome do comando a ser chamado, é obrigatória. A propriedade args é opcional. Para obter mais informações, consulte referência de esquema de propriedade de exportação de manifesto do recurso DSC.

Type:     object
Required: true

Obter

A propriedade get define como chamar o recurso para obter o estado atual de uma instância. Essa propriedade é obrigatória para todos os recursos.

O valor dessa propriedade deve ser um objeto. A propriedade executable do objeto, definindo o nome do comando a ser chamado, é obrigatória. As propriedades args e input são opcionais. Para obter mais informações, consulte manifesto do recurso DSC obter referência de esquema de propriedade.

Type:     object
Required: true

pôr

A propriedade set define como chamar o recurso para definir o estado desejado de uma instância. Ele também define como processar a saída do recurso para esse método. Quando essa propriedade não é definida, o DSC não pode gerenciar instâncias do recurso. Ele só pode obter o estado atual e testar se a instância está no estado desejado.

O valor dessa propriedade deve ser um objeto. A propriedade executable, definindo o nome do comando a ser chamado, é obrigatória. As propriedades argsinput, implementsPreteste returns são opcionais. Para obter mais informações, consulte referência de esquema de propriedade do conjunto de manifestos do recurso DSC.

Type:     object
Required: false

whatIf

Define como o DSC deve chamar o Recurso DSC para indicar se e como o comando set modificará uma instância e como processar a saída do recurso DSC. Se um recurso não definir esse método no manifesto, o DSC sintetizará esse comportamento convertendo o resultado da operação de teste do recurso no resultado do conjunto.

O valor dessa propriedade deve ser um objeto. A propriedade executable, definindo o nome do comando a ser chamado, é obrigatória. As propriedades argsinput, implementsPreteste returns são opcionais. Para obter mais informações, consulte referência de esquema de propriedade whatIf do manifesto do recurso DSC.

teste

A propriedade test define como chamar o recurso para testar se uma instância está no estado desejado. Ele também define como processar a saída do recurso para esse método. Quando essa propriedade não é definida, o DSC executa um teste sintético básico para instâncias do Recurso DSC.

O valor dessa propriedade deve ser um objeto. A propriedade executable do objeto, definindo o nome do comando a ser chamado, é obrigatória. As propriedades argsinpute returns são opcionais. Para obter mais informações, consulte referência de esquema de propriedade de teste de manifesto do recurso DSC.

Type:     object
Required: false

validar

A propriedade validate define como chamar um Recurso de Grupo DSC para validar suas instâncias. Essa propriedade é obrigatória para recursos de grupo DSC. O DSC ignora essa propriedade para todos os outros recursos.

O valor dessa propriedade deve ser um objeto. A propriedade executable do objeto, definindo o nome do comando a ser chamado, é obrigatória. A propriedade args é opcional. Para obter mais informações, consulte referência de esquema de propriedade de validação do manifesto do recurso DSC.

Type:     object
Required: false

provedor

Quando especificada, a propriedade provider define o recurso como um Provedor de Recursos DSC.

O valor dessa propriedade deve ser um objeto. As propriedades list e config do objeto são obrigatórias. A propriedade list define como chamar o provedor para retornar os recursos que o provedor pode gerenciar. A propriedade config define como o provedor espera entrada. Para obter mais informações, consulte a referência de esquema de propriedade do provedor de manifesto do recurso DSC .

exitCodes

A propriedade exitCodes define um conjunto de códigos de saída válidos para o recurso e seu significado. Defina essa propriedade como um conjunto de pares chave-valor em que:

  • A chave é uma cadeia de caracteres que contém um inteiro com sinal que é mapeado para um código de saída conhecido para o recurso. O código de saída deve ser um inteiro com sinal literal. Você não pode usar formatos alternativos para o código de saída. Por exemplo, em vez do valor hexadecimal 0x80070005 para "Acesso negado", especifique o código de saída como -2147024891.
  • O valor é uma cadeia de caracteres que descreve o significado semântico desse código de saída para um leitor humano.

O DSC interpreta o código de saída 0 como uma operação bem-sucedida e qualquer outro código de saída como um erro.

Ponta

Se você estiver criando seu manifesto de recurso no yaml, lembre-se de encapsular o código de saída entre aspas simples para garantir que o arquivo YAML possa ser analisado corretamente. Por exemplo:

exitCodes:
  '0': Success
  '1': Invalid parameter
  '2': Invalid input
  '3': Registry error
  '4': JSON serialization failed

Type:                object
Required:            false
PropertyNamePattern: ^-?[0-9]+#
PropertyValueType:   string

esquema

A propriedade schema define como obter o esquema JSON que valida uma instância do recurso. Essa propriedade sempre deve ser um objeto que define uma das seguintes propriedades:

  • command - Quando você especifica a propriedade command, o DSC chama o comando definido para obter o esquema JSON.
  • embedded - Quando você especifica a propriedade embedded, o DSC usa o valor definido como o esquema JSON.

Para obter mais informações, consulte referência da propriedade de esquema de manifesto do recurso DSC.

Type:     object
Required: true