Referência de esquema do tipo de recurso DSC

Synopsis

Identifica se um recurso é um recurso de adaptador, um recurso de grupo, um recurso de importador, um recurso de exportador ou um recurso normal.

Metadata

SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/definitions/resourceKind.json
Type:          string
ValidValues:  [resource, adapter, group, importer, exporter]

Description

O DSC suporta vários tipos de recursos de comando:

resource - Indica que o manifesto é para um recurso típico.
group - Indica que o manifesto é para um recurso de grupo.
adapter - Indica que o manifesto é para um recurso do adaptador.
importer - Indica que o manifesto é para um recurso importador.
exporter - Indica que o manifesto é para um recurso exportador.

Quando kind não está definido no manifesto do recurso para um recurso de comando, o DSC infere o valor da propriedade. Se a adapter propriedade for definida no manifesto do recurso, o DSC inferirá o valor de kind as adapter. Se a propriedade não estiver definida, o adapter DSC inferirá o valor de kind como resource. O DSC não pode inferir se um manifesto é para um recurso de grupo, importador ou exportador.

Ao definir um recurso de grupo, importador ou exportador com um manifesto de recurso, sempre defina kindexplicitamente .

Recursos do adaptador

Um recurso do adaptador disponibiliza recursos sem comando para o DSC. Eles sempre têm uma resources propriedade que usa uma matriz de instâncias de recursos aninhados. Os adaptadores podem fornecer controle adicional sobre como os recursos adaptados são processados.

Um recurso de adaptador deve sempre definir o adaptador e validar propriedades no manifesto do recurso.

Por exemplo, o Microsoft.DSC/PowerShell adaptador permite que você use recursos de Configuração de Estado Desejado (PSDSC) do PowerShell no DSC. Os recursos PSDSC são publicados como componentes dos módulos do PowerShell. Eles não definem manifestos de recursos.

Recursos do grupo

Os recursos de grupo sempre operam em instâncias de recurso DSC aninhadas. Os recursos de grupo podem alterar a forma como as instâncias aninhadas são processadas, como o recurso de Microsoft.DSC/Assertion grupo.

Um recurso de grupo deve sempre definir a propriedade kind no manifesto do recurso.

Os recursos de grupo também podem ser usados para agrupar conjuntos de recursos para processamento, como o Microsoft.DSC/Group recurso. Você pode usar a propriedade dependsOn para uma instância de recurso em uma configuração para apontar para um recurso de grupo em vez de enumerar cada recurso na lista.

Recursos do importador

Os recursos do importador resolvem uma fonte externa para um conjunto de instâncias aninhadas de Recursos DSC. As propriedades de um recurso importador definem como localizar e resolver a fonte externa.

Um recurso importador deve sempre definir o tipo e resolver propriedades no manifesto do recurso.

Por exemplo, o Microsoft.DSC/Import recurso do importador resolve instâncias de um documento de configuração externo, permitindo que você componha configurações a partir de vários arquivos.

Recursos do exportador

Os recursos do exportador implementam a operação Exportar para retornar instâncias de recursos completas para o DSC exportar recursivamente. Isso permite que um recurso exportador ajude os usuários a exportar rapidamente a configuração atual de um sistema sem ter que conhecer todos os recursos disponíveis.

Por exemplo, um recurso de exportador pode descobrir se o Apache está instalado e, em seguida, retornar uma instância para cada recurso suportado para exportar totalmente a configuração para o Apache.

Um recurso exportador deve sempre definir o tipo e as propriedades de exportação no manifesto do recurso.

Instâncias de recursos aninhados

As instâncias de recursos declaradas em recursos de adaptador e grupo ou resolvidas por recursos de importador são chamadas de instâncias de recursos aninhados.

Para instâncias aninhadas, uma instância de recurso é adjacente se:

É declarado no mesmo grupo ou instância do adaptador.
É resolvido pela mesma instância do importador.

Uma instância de recurso é externa a uma instância aninhada se:

É declarado fora do grupo ou da instância do adaptador
É resolvido por uma instância de importador diferente
Ele está aninhado dentro de um grupo, adaptador ou instância de importador adjacente.

Para instâncias de nível superior, outras instâncias de nível superior são adjacentes. Todas as outras instâncias são externas.

Considere o seguinte trecho de configuração. Ele define sete instâncias de recursos:

No nível superior, a configuração define as TopLevelEchoinstâncias , TopLevelOSInfoe TopLevelGroup .
A TopLevelGroup instância define as instâncias NestedEcho aninhadas e NestedGroup.
A NestedGroup instância define as instâncias DeeplyNestedEcho aninhadas e DeeplyNestedOSInfo.

resources:
- name: TopLevelEcho
  type: Microsoft.DSC.Debug/Echo
  properties: { output: 'top level instance' }
- name: TopLevelOSInfo
  type: Microsoft/OSInfo
  properties: { }
- name: TopLevelGroup
  type: Microsoft.DSC/Group
  properties:
    $schema:
    resources:
    - name: NestedEcho
      type: Microsoft.DSC.Debug/Echo
      properties: { output: 'nested instance' }
    - name: NestedGroup
      type: Microsoft.DSC/Group
      properties:
        $schema:
        resources:
        - name: DeeplyNestedEcho
          type: Microsoft.DSC.Debug/Echo
          properties: { output: 'deeply nested instance' }
        - name: DeeplyNestedOSInfo
          type: Microsoft/OSInfo
          properties: { }

A matriz a seguir define as relações de cada instância na configuração:

	TopLevelEcho	TopLevelOSInfo	TopLevelGroup	NestedEcho	NestedGroup	DeeplyNestedEcho	DeeplyNestedOSInfo
TopLevelEcho	Self	Adjacent	Adjacent	External	External	External	External
TopLevelOSInfo	Adjacent	Self	Adjacent	External	External	External	External
TopLevelGroup	Adjacent	Adjacent	Self	External	External	External	External
NestedEcho	External	External	External	Self	Adjacent	External	External
NestedGroup	External	External	External	Adjacent	Self	External	External
DeeplyNestedEcho	External	External	External	External	External	Self	Adjacent
DeeplyNestedOSInfo	External	External	External	External	External	Adjacent	Self

Referenciando instâncias aninhadas

As instâncias de recursos aninhados têm limitações para a propriedade dependsOn e a função de configuração reference( ).

Você só pode fazer referência a instâncias adjacentes. Não é possível fazer referência a uma instância aninhada de fora da instância que a declara ou resolve. Não é possível usar uma referência a um recurso fora do grupo, adaptador ou recurso importador para uma instância aninhada.
Você só pode usar a dependsOn propriedade para instâncias adjacentes. Você deve adicionar uma dependência no grupo, adaptador ou instância do importador, não uma instância aninhada. As instâncias aninhadas não podem depender de instâncias externas.

Os exemplos a seguir mostram referências e dependências válidas e inválidas. Os exemplos usam o Microsoft.DSC/Group recurso, mas a funcionalidade é a mesma para recursos de adaptador e importação.

Exemplo 1 - Referências e dependências válidas

Este exemplo de configuração define várias referências e dependências válidas. Ele também define duas instâncias do Microsoft.DSC/Group recurso, uma aninhada dentro da outra.

A instância de nível superior do Microsoft.DSC.Debug/Echo recurso faz referência e depende da instância de nível superior do Microsoft/OSInfo recurso. As instâncias de nível superior do Microsoft.DSC.Debug/Echo e Microsoft/OSInfo recursos dependem da instância de nível superior do Microsoft.DSC/Group recurso.

# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
resources:
# The top level echo references and depends on the top-level OSInfo.
# It also depends on the top-level Group.
- name: Top level echo
  type: Microsoft.DSC.Debug/Echo
  properties:
    output:  >-
      [reference(
        resourceId('Microsoft/OSInfo', 'Top level OSInfo')
      ).actualState]
  dependsOn:
    - "[resourceId('Microsoft/OSInfo', 'Top level OSInfo')]"
    - "[resourceId('Microsoft.DSC/Group', 'Top level group')]"
# The top level OSInfo depends on the top-level Group.
- name: Top level OSInfo
  type: Microsoft/OSInfo
  properties: {}
  dependsOn:
    - "[resourceId('Microsoft.DSC/Group', 'Top level group')]"
- name: Top level group
  type: Microsoft.DSC/Group
  properties: # snipped for brevity

A instância de nível superior de define três instâncias de Microsoft.DSC/Group recursos aninhados: Microsoft.DSC.Debug/Echo, Microsoft/OSInfoe Microsoft.DSC/Group. Como no nível superior, a Microsoft.DSC.Debug/Echo instância faz referência e depende da instância aninhadaMicrosoft/OSInfo adjacente e essa instância depende da instância aninhada Microsoft.DSC/Group adjacente.

# Other top-level instances snipped for brevity
- name: Top level group
  type: Microsoft.DSC/Group
  properties:
    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
    resources:
    # The nested echo references and depends on the adjacent nested OSInfo.
    - name: Nested echo
      type: Microsoft.DSC.Debug/Echo
      properties:
        output:  >-
          [reference(
            resourceId('Microsoft/OSInfo', 'Nested OSInfo')
          ).actualState]
      dependsOn:
        - "[resourceId('Microsoft/OSInfo', 'Nested OSInfo')]"
    # The nested OSInfo depends on the adjacent nested Group.
    - name: Nested OSInfo
      type: Microsoft/OSInfo
      properties: {}
    - name: Nested Group
      type: Microsoft.DSC/Group
      properties: # snipped for brevity

Finalmente, a instância aninhada de Microsoft.DSC/Group define duas instâncias aninhadas. A instância profundamente aninhada de Microsoft.DSC.Debug/Echo referências e depende da instância profundamente aninhada de Microsoft/OSInfo.

- name: Top level group
  type: Microsoft.DSC/Group
  properties:
    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
    resources:
    # Snipped the Microsoft.DSC.Debug/Echo and Microsoft/OSInfo instances for brevity
    - name: Nested Group
      type: Microsoft.DSC/Group
      properties:
        $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
        resources:
        # The deeply nested echo references and depends on the adjacent
        # deeply nested OSInfo.
        - name: Deeply nested echo
          type: Microsoft.DSC.Debug/Echo
          properties:
            output:  >-
              [reference(
                resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')
              ).actualState]
          dependsOn:
            - "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]"
        - name: Deeply nested OSInfo
          type: Microsoft.OSInfo
          properties: {}

Em todos os casos, as referências e dependências são para instâncias adjacentes na configuração. As instâncias no nível superior dependem apenas ou fazem referência a outras instâncias no nível superior. As instâncias aninhadas no grupo de nível superior dependem apenas ou fazem referência a outras instâncias aninhadas no mesmo grupo. As instâncias profundamente aninhadas definidas no grupo aninhado dependem apenas ou fazem referência a outras instâncias profundamente aninhadas no mesmo grupo.

Juntando a configuração, você obtém este documento completo:

# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
# The top level echo references and depends on the top-level OSInfo.
- name: Top level echo
  type: Microsoft.DSC.Debug/Echo
  properties:
    output:  >-
      [reference(
        resourceId('Microsoft/OSInfo', 'Top level OSInfo')
      ).actualState]
  dependsOn:
    - "[resourceId('Microsoft/OSInfo', 'Top level OSInfo')]"
# The top level OSInfo depends on the top-level Group.
- name: Top level OSInfo
  type: Microsoft/OSInfo
  properties: {}
  dependsOn:
    - "[resourceId('Microsoft.DSC/Group', 'Top level group')]"
- name: Top level group
  type: Microsoft.DSC/Group
  properties:
    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
    resources:
    # The nested echo references and depends on the adjacent nested OSInfo.
    - name: Nested echo
      type: Microsoft.DSC.Debug/Echo
      properties:
        output:  >-
          [reference(
            resourceId('Microsoft/OSInfo', 'Nested OSInfo')
          ).actualState]
      dependsOn:
        - "[resourceId('Microsoft/OSInfo', 'Nested OSInfo')]"
    # The nested OSInfo depends on the adjacent nested Group.
    - name: Nested OSInfo
      type: Microsoft/OSInfo
      properties: {}
    - name: Nested Group
      type: Microsoft.DSC/Group
      properties:
        $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
        resources:
        # The deeply nested echo references and depends on the adjacent
        # deeply nested OSInfo.
        - name: Deeply nested echo
          type: Microsoft.DSC.Debug/Echo
          properties:
            output:  >-
              [reference(
                resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')
              ).actualState]
          dependsOn:
            - "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]"
        - name: Deeply nested OSInfo
          type: Microsoft.OSInfo
          properties: {}

Exemplo 2 - Referência inválida e dependência em uma instância aninhada

Este exemplo de configuração é inválido, porque a instância de nível superior do Microsoft.DSC.Debug/Echo recurso faz referência e depende da instância aninhada Microsoft/OSInfo . A instância aninhada é externa à instância de nível superior, não adjacente.

# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Top level echo
  type: Microsoft.DSC.Debug/Echo
  properties:
    output:  >-
      [reference(
        resourceId('Microsoft/OSInfo', 'Nested OSInfo')
      ).actualState]
  dependsOn:
    - "[resourceId('Microsoft/OSInfo', 'Nested OSInfo')]"
- name: Top level group
  type: Microsoft.DSC/Group
  properties:
    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
    resources:
    - name: Nested OSInfo
      type: Microsoft/OSInfo
      properties: {}

Exemplo 3 - Referência inválida e dependência de uma instância externa

Este exemplo de configuração é inválido, porque a Microsoft.DSC.Debug/Echo instância aninhada do recurso faz referência e depende da instância de nível Microsoft/OSInfo superior. A instância de nível superior é externa à instância aninhada, não adjacente.

# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Top level OSInfo
  type: Microsoft/OSInfo
  properties: {}
- name: Top level group
  type: Microsoft.DSC/Group
  properties:
    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
    resources:
    - name: Nested echo
      type: Microsoft.DSC.Debug/Echo
      properties:
        output:  >-
          [reference(
            resourceId('Microsoft/OSInfo', 'Top level OSInfo')
          ).actualState]
      dependsOn:
        - "[resourceId('Microsoft/OSInfo', 'Top level OSInfo')]"

Feedback

Esta página foi útil?

Last updated on 2025-08-21