Obtenção de recursos DSC

Sinopse

Recupera o estado real de uma instância de recurso.

Sintaxe

Sem propriedades de instância

dsc resource get [Options] --resource <RESOURCE>

Propriedades da instância da opção de entrada

dsc resource get --input <INPUT> --resource <RESOURCE>

Propriedades da instância do arquivo

dsc resource get --file <FILE> --resource <RESOURCE>

Propriedades de instância de stdin

cat <FILE> | dsc resource get [Options] --resource <RESOURCE> --file -

Descrição

O get subcomando retorna o estado atual de uma instância de recurso.

Por padrão, esse subcomando retorna uma instância de um recurso DSC específico. Para retornar vários recursos, use o --all parâmetro, um grupo de recursos ou o comando dsc config get .

Todas as propriedades que o recurso requer para recuperar o estado de uma instância devem ser passadas para este comando como um objeto JSON ou YAML com a --input opção or --file .

Exemplos

Exemplo 1 - Obter instância de recurso sem qualquer entrada

Para recursos de instância única que não exigem nenhum valor de propriedade para retornar o estado real da instância de recurso, as propriedades da instância não são necessárias.

dsc resource get --resource Microsoft/OSInfo

actualState:
  $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json
  family: Windows
  version: 10.0.22621
  edition: Windows 11 Enterprise
  bitness: '64'

Exemplo 2 - Obter instância de recurso com opção de entrada

Se um recurso exigir um ou mais valores de propriedade para retornar o estado real da instância, as propriedades da instância poderão ser passadas com a --input opção como JSON ou YAML.

dsc resource get --resource Microsoft.Windows/Registry --input '{
    "keyPath": "HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion",
    "valueName": "SystemRoot"
}'

actualState:
  $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
  keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
  valueName: SystemRoot
  valueData:
    String: C:\WINDOWS

Exemplo 3 - Obter instância de recurso com entrada do stdin

Se um recurso exigir um ou mais valores de propriedade para retornar o estado real da instância, as propriedades da instância podem ser passadas sobre stdin como JSON ou YAML com a --file opção.

'{
    "keyPath": "HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion",
    "valueName": "SystemRoot"
}' | dsc resource get --resource Microsoft.Windows/Registry --file -

actualState:
  $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
  keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
  valueName: SystemRoot
  valueData:
    String: C:\WINDOWS

Exemplo 4 - Obter instância de recurso com entrada de um arquivo YAML

Se um recurso exigir um ou mais valores de propriedade para retornar o estado real da instância, as propriedades da instância poderão ser recuperadas de um arquivo JSON ou YAML salvo.

# ./example.yaml
keyPath:   HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion
valueName: SystemRoot

dsc resource get --resource Microsoft.Windows/Registry --path ./example.yaml

actualState:
  $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
  keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
  valueName: SystemRoot
  valueData:
    String: C:\WINDOWS

Opções

-a, --todos

Especifica que o comando deve retornar cada instância do recurso DSC especificado em vez de uma instância específica.

Essa opção só é válida quando o Recurso é um recurso exportável que define a seção de exportação na configuração de entrada. Se o tipo de recurso não for exportável, o DSC gerará um erro.

Quando essa opção é especificada, o DSC ignora as --input opções e --path .

Type:      Boolean
Mandatory: false

-r, --recurso

Especifica o nome do tipo totalmente qualificado do recurso DSC a ser usado, como Microsoft.Windows/Registry.

A sintaxe do nome de tipo totalmente qualificada é: <owner>[.<group>][.<area>]/<name>, onde:

• O owner é o autor ou organização mantenedora do recurso.
• Os group e area são componentes de nome opcionais que habilitam o namepacing para um recurso.
• O name identifica o componente que o recurso gerencia.

Type        : string
Mandatory   : true
LongSyntax  : --resource <RESOURCE>
ShortSyntax : -r <RESOURCE>

-i, --entrada

Especifica a instância de recurso a ser recuperada.

A instância deve ser uma cadeia de caracteres contendo um objeto JSON ou YAML. O DSC valida o objeto em relação ao esquema de instância do recurso. Se a validação falhar, o DSC gerará um erro.

Esta opção exclui-se mutuamente com a --file opção.

Type        : string
Mandatory   : false
LongSyntax  : --input <INPUT>
ShortSyntax : -i <INPUT>

-f, --ficheiro

Define o caminho para um arquivo, definindo a instância de recurso a ser recuperada.

O arquivo especificado deve conter um objeto JSON ou YAML que represente propriedades válidas para o recurso. O DSC valida o objeto em relação ao esquema de instância do recurso. Se a validação falhar ou se o arquivo especificado não existir, o DSC gerará um erro.

Você também pode usar essa opção para passar uma instância do stdin, conforme mostrado no Exemplo 3.

Esta opção exclui-se mutuamente com a --input opção.

Type        : string
Mandatory   : false
LongSyntax  : --file <FILE>
ShortSyntax : -f <FILE>

-o, --formato de saída

A --output-format opção controla qual formato o DSC usa para os dados retornados pelo comando. Os formatos disponíveis são:

• json para emitir os dados como uma linha JSON. Quando você usa a opção --all, cada instância é retornada como uma linha JSON.
• pretty-json para emitir os dados como JSON com novas linhas, recuo e espaços para legibilidade.
• yaml para emitir os dados como YAML. Quando você usa a --all opção, cada instância é retornada como um documento YAML com o separador de --- documento entre cada instância retornada.
• json-array para emitir os dados como uma única matriz JSON milti-line contendo cada objeto. Esta opção só é válida com a opção --all.
• pass-through para retornar os dados do recurso diretamente sem envolvê-los em um resultado DSC. Quando você usa essa opção de saída, a linha JSON emitida adere ao esquema de instância do recurso, não ao esquema de resultado de obtenção de DSC.

O formato de saída padrão depende se o DSC deteta que a saída está sendo redirecionada ou capturada como uma variável:

• Se o comando não estiver sendo redirecionado ou capturado, o DSC exibirá a saída como o yaml formato no console.
• Se a saída do comando for redirecionada ou capturada, o DSC emitirá os dados como o json formato para stdout.

Quando você usa essa opção, o DSC usa o formato especificado, independentemente de o comando estar sendo redirecionado ou capturado.

Quando o comando não é redirecionado ou capturado, a saída no console é formatada para melhorar a legibilidade. Quando o comando não é redirecionado ou capturado, a saída inclui sequências de terminal para formatação.

Type        : string
Mandatory   : false
ValidValues : [json, pretty-json, yaml, json-array, pass-through]
LongSyntax  : --output-format <OUTPUT_FORMAT>
ShortSyntax : -o <OUTPUT_FORMAT>

-h, --ajuda

Exibe a ajuda para o comando ou subcomando atual. Quando você especifica essa opção, o aplicativo ignora todas as outras opções e argumentos.

Type        : boolean
Mandatory   : false
LongSyntax  : --help
ShortSyntax : -h

Resultado

Por padrão, esse comando retorna um objeto de dados formatado que inclui o estado real da instância. Quando a --all opção é especificada, o comando retorna os dados formatados para cada instância. Quando você especifica a pass-through opção de formato de saída, os dados emitidos são a saída não modificada do recurso, não um resultado de obtenção de recurso DSC.

Para obter mais informações sobre a estrutura do JSON de saída, consulte dsc resource get result schema.

Para obter mais informações sobre a formatação dos dados de saída, consulte a opção --output-format.