Skip to content

Make output for group and provider resources in dsc config * more readable #266

@michaeltlombardi

Description

@michaeltlombardi

Summary of the new feature / enhancement

As a user, I want to be able to use group and provider resources in my configuration documents and understand the output for dsc config commands without having to know how DSC works internally or investigate the data to know which keys mean what.

While inspecting the output for group and provider resources, I noticed that the output structure for those resources is very difficult to read.

  1. Define a configuration that uses a group or provider resource.

    Configuration document
    # repro.dsc.config.yaml
    $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
    resources:
      - name: current user registry
        type: Microsoft.Windows/Registry
        properties:
          keyPath: HKCU\example
          _exist:  true
        dependsOn:
          - "[resourceId('DSC/AssertionGroup','my assertions')]"
      - name: my assertions
        type: DSC/AssertionGroup
        properties:
          $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
          resources:
            - name: os
              type: Microsoft/OSInfo
              properties:
                family: Windows
            - name: system root
              type: Microsoft.Windows/Registry
              properties:
                keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
                valueName: SystemRoot
                valueData:
                  String: Z:\Windows
  1. Get the current state of the configuration.

    dsc --input-file ./assertion.dsc.config.yaml config get
    Actual Output
    results:
    - name: my assertions
      type: DSC/AssertionGroup
      result:
        actualState:
          results:
          - name: os
            type: Microsoft/OSInfo
            result:
              desiredState:
                family: Windows
              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'
              inDesiredState: true
              differingProperties: []
          - name: system root
            type: Microsoft.Windows/Registry
            result:
              desiredState:
                keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
                valueName: SystemRoot
                valueData:
                  String: Z:\Windows
              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
                _exist: true
                _inDesiredState: false
              inDesiredState: false
              differingProperties:
              - valueData
          messages: []
          hadErrors: false
    - name: current user registry
      type: Microsoft.Windows/Registry
      result:
        actualState:
          $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
          keyPath: HKCU\example
          _exist: false
    messages: []
    hadErrors: false
    Proposed Output
    results:
    - name: my assertions
      type: DSC/AssertionGroup
      results:
      - name: os
        type: Microsoft/OSInfo
        result:
          desiredState:
            family: Windows
          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'
          inDesiredState: true
          differingProperties: []
      - name: system root
        type: Microsoft.Windows/Registry
        result:
          desiredState:
            keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
            valueName: SystemRoot
            valueData:
              String: Z:\Windows
          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
            _exist: true
            _inDesiredState: false
          inDesiredState: false
          differingProperties:
          - valueData
      messages: []
      hadErrors: false
    - name: current user registry
      type: Microsoft.Windows/Registry
      result:
        actualState:
          $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
          keyPath: HKCU\example
          _exist: false
    messages: []
    hadErrors: false
  2. Test whether the configuration is in the desired state

    dsc --input-file ./assertion.dsc.config.yaml config test
    Actual Output
    results:
    - name: my assertions
      type: DSC/AssertionGroup
      result:
        desiredState:
          $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
          resources:
          - name: os
            type: Microsoft/OSInfo
            properties:
              family: Windows
          - name: system root
            type: Microsoft.Windows/Registry
            properties:
              keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
              valueName: SystemRoot
              valueData:
                String: Z:\Windows
        actualState:
          results:
          - name: os
            type: Microsoft/OSInfo
            result:
              desiredState:
                family: Windows
              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'
              inDesiredState: true
              differingProperties: []
          - name: system root
            type: Microsoft.Windows/Registry
            result:
              desiredState:
                keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
                valueName: SystemRoot
                valueData:
                  String: Z:\Windows
              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
                _exist: true
                _inDesiredState: false
              inDesiredState: false
              differingProperties:
              - valueData
          messages: []
          hadErrors: false
        inDesiredState: false
        differingProperties:
        - $schema
        - resources
    - name: current user registry
      type: Microsoft.Windows/Registry
      result:
        desiredState:
          keyPath: HKCU\example
          _exist: true
        actualState:
          $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
          keyPath: HKCU\example
          _exist: false
          _inDesiredState: false
        inDesiredState: false
        differingProperties:
        - _exist
    messages: []
    hadErrors: false
    Proposed Output
    results:
    - name: my assertions
      type: DSC/AssertionGroup
      results:
      - name: os
        type: Microsoft/OSInfo
        result:
          desiredState:
            family: Windows
          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'
          inDesiredState: true
          differingProperties: []
      - name: system root
        type: Microsoft.Windows/Registry
        result:
          desiredState:
            keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
            valueName: SystemRoot
            valueData:
              String: Z:\Windows
          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
            _exist: true
            _inDesiredState: false
          inDesiredState: false
          differingProperties:
          - valueData
      messages: []
      hadErrors: false
    - name: current user registry
      type: Microsoft.Windows/Registry
      result:
        desiredState:
          keyPath: HKCU\example
          _exist: true
        actualState:
          $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
          keyPath: HKCU\example
          _exist: false
          _inDesiredState: false
        inDesiredState: false
        differingProperties:
        - _exist
    messages: []
    hadErrors: false
  3. Enforce the configuration to the desired state

    dsc --input-file ./assertion.dsc.config.yaml config set
    Actual Output
    results:
    - name: my assertions
      type: DSC/AssertionGroup
      result:
        beforeState:
          results:
          - name: os
            type: Microsoft/OSInfo
            result:
              desiredState:
                family: Windows
              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'
              inDesiredState: true
              differingProperties: []
          - name: system root
            type: Microsoft.Windows/Registry
            result:
              desiredState:
                keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
                valueName: SystemRoot
                valueData:
                  String: Z:\Windows
              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
                _exist: true
                _inDesiredState: false
              inDesiredState: false
              differingProperties:
              - valueData
          messages: []
          hadErrors: false
        afterState:
          results:
          - name: os
            type: Microsoft/OSInfo
            result:
              desiredState:
                family: Windows
              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'
              inDesiredState: true
              differingProperties: []
          - name: system root
            type: Microsoft.Windows/Registry
            result:
              desiredState:
                keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
                valueName: SystemRoot
                valueData:
                  String: Z:\Windows
              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
                _exist: true
                _inDesiredState: false
              inDesiredState: false
              differingProperties:
              - valueData
          messages: []
          hadErrors: false
        changedProperties: []
    - name: current user registry
      type: Microsoft.Windows/Registry
      result:
        beforeState:
          $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
          keyPath: HKCU\example
          _exist: false
        afterState:
          $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
          keyPath: HKCU\example
        changedProperties:
        - _exist
    messages: []
    hadErrors: false
    Proposed Output
    results:
    - name: my assertions
      type: DSC/AssertionGroup
      results: [] # none because the assertion group doesn't participate in set.
      messages: []
      hadErrors: false
    - name: current user registry
      type: Microsoft.Windows/Registry
      result:
        beforeState:
          $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
          keyPath: HKCU\example
          _exist: false
        afterState:
          $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
          keyPath: HKCU\example
        changedProperties:
        - _exist
    messages: []
    hadErrors: false

Proposed technical implementation details (optional)

Currently, DSC treats group and provider resources, which definitionally declare an array of resource instances, the same as normal instances.

Options

  1. Instead of defining the result property adhering to the dsc resource * output schema for each group/provider instance, those instances should define the results property adhering to the dsc config * output schemas. This would make it much easier to read and process the results.
  2. Have a transitory step that flattens the deeply nested map of resources and always return the top-level results as a flat array, associating nested instances to their parent with a parentResource or resourceGraphPath property. Using the examples above, the os resource instance would have my assertions as the parentResource or something like my assertions>os for resourceGraphPath.

Option 1 requires DSC, users, and integrating tools to distinguish between group/provider resource instances and normal resource instances in the output, but leaves the data more walkable/comparable to the configuration document definition.

Option 2 ensures that the output is always the same structurally, but may require integrating tools to handle re-grouping instance results.

Metadata

Metadata

Assignees

Type

No type

Projects

Status

Done

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions