Referência de esquema de manifesto do recurso DSC baseado em comando
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:
- Seja detectável na variável de ambiente
PATH
. - Seja formatado como JSON ou YAML.
- Siga a convenção de nomenclatura
<name>.dsc.resource.<extension>
. As extensões válidas incluemjson
,yml
eyaml
. - 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
, Group
e 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 args
input
, implementsPretest
e 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 args
input
, implementsPretest
e 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 args
input
e 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 propriedadecommand
, o DSC chama o comando definido para obter o esquema JSON. -
embedded
- Quando você especifica a propriedadeembedded
, 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