Partilhar via

Referência de esquema de manifesto de 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 ficheiro de manifesto deve:

  1. Ser detetável na variável de ambiente PATH.
  2. Ser 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 contra o qual o manifesto é validado. Esta propriedade é obrigatória. O DSC usa esse valor para validar o manifesto em relação ao esquema JSON correto.

Para cada versão do esquema, existem três urls válidas:

  • .../resource/manifest.json

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

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

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

    Este esquema usa o modelo de agregação introduzido para o JSON Schema 2020-12. Embora o DSC ainda possa validar o documento quando ele usa esse esquema, outras ferramentas podem errar 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 trechos que os outros não incluem.

    Este esquema usa palavras-chave que só são reconhecidas pelo VS Code. Embora o DSC ainda possa validar o documento quando ele usa esse esquema, outras ferramentas podem errar 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 do tipo totalmente qualificado do recurso. Ele é usado para especificar o recurso em documentos de configuração e como o valor do sinalizador de --resource ao usar os comandos dsc resource *. Para obter mais informações sobre nomes de tipo de recurso, consulte de referência de esquema de nome de tipo totalmente qualificado de 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 válida (semver). A versão aplica-se ao recurso, não ao software que gere.

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 manipular o recurso. O DSC suporta três tipos de recursos DSC baseados em comando: Resource, Groupe Adapter.

Quando kind não está 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. O 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 de referência de esquema de tipo de recurso DSC .

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

Etiquetas

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 tag deve conter apenas caracteres alfanuméricos e sublinhados. Não são permitidos outros caracteres. Cada tag 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 dsc config export 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 defina cada instância do recurso.
  • Especifique o recurso com o comando dsc resource get e a opção --all para retornar o estado atual de cada instância do recurso.

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

Type:     object
Required: true

Obter

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

O valor dessa propriedade deve ser um objeto. A propriedade executable do objeto, que define o nome do comando a ser chamado, é obrigatória. As propriedades args e input são opcionais. Para obter mais informações, consulte DSC Resource manifest get property schema reference.

Type:     object
Required: true

conjunto

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 seu estado atual e testar se a instância está no estado desejado.

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

Type:     object
Required: false

O quêSe

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 para o recurso no resultado definido.

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

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, que define o nome do comando a ser chamado, é obrigatória. As propriedades argsinpute returns são opcionais. Para obter mais informações, consulte de referência de esquema de propriedade de teste de manifesto de recurso DSC .

Type:     object
Required: false

validar

A propriedade validate define como chamar um recurso de grupo DSC para validar suas instâncias. Esta propriedade é obrigatória para Recursos do 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, que define o nome do comando a ser chamado, é obrigatória. A propriedade args é opcional. Para obter mais informações, consulte Manifesto de recurso DSC validar referência de esquema de propriedade.

Type:     object
Required: false

fornecedor

Quando especificado, 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 ade referência de esquema de propriedade do provedor de manifesto de recursos DSC .

exitCodes

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

  • A chave é uma cadeia de caracteres que contém um inteiro assinado que mapeia para um código de saída conhecido para o recurso. O código de saída deve ser um inteiro assinado literal. Não é possível 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.

Dica

Se você estiver criando seu manifesto de recursos no yaml, certifique-se de envolver 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 deve ser sempre um objeto que define uma das seguintes propriedades:

  • command - Quando você especifica a propriedade command, o DSC chama o comando defined 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 de referência de propriedade de esquema de manifesto de recurso DSC .

Type:     object
Required: true