DSC3 Help and Feedback

[wekempf]

I'm new to DSC in general and I'm finding using DSC3 to be quite difficult. The documentation on Microsoft Learn is a decent start, but there's major gaps there. For instance, while I am on Windows and using PowerShell, the fact that the documentation entirely uses PowerShell to access the results of dsc seems very wrong for a "cross platform" tool. It also illustrates some shortcomings in the tool itself. To discover resources and how they are used requires a lot of finesse with the data returned. There really needs to be some sort of query mechanism built in to the tool. One would also hope that this would go beyond the data that's available today. For instance, I'm simply trying to figure out how to declare some PowerShell modules as desired state, and while I can get data that tells me to use the adapter Microsoft.Windows/WindowsPowerShell and the resource PowerShellGet/PSModule with known properties... there's no description for those properties, just a name. What's the type? What's the allowed values? What's the purpose?

Worse, while trying to figure all this out, the error messages produced are really, quite frankly, horrid.

2025-04-15T14:40:35.300549Z ERROR Not implemented: Custom resource not supported

This doesn't tell me anything. What does it think is a custom resource? Where in the configuration did it discover this problem? How would I go about fixing it?

2025-04-15T14:41:55.526155Z ERROR PID 4488: Exception: Resource PSModule was not found.
2025-04-15T14:41:55.556312Z ERROR Command: Resource 'powershell' [exit code 1] manifest description: Error

Really, who cares about the PID here? PID of what? I can make a guess, but this is information ONLY useful to the developers and maintainers of dsc. It's meaningless information to the users of dsc. I also have no idea why it can't find PSModule when this was found via dsc resource list -adapter *?

The output from dsc can be interpreted, but really, there should be a summary. With dsc test there's no indication of success or failure, and instead you have to interpret every bit of the data returned. All that data is useful, but it's not user friendly in the slightest.

The documentation lacks any sort of tutorial on setting up a real-world configuration file with common resources. Finding examples online is currently unsatisfactory, which is understandable given how new DSC3 is, but it really illustrates why the documentation needs this.

Does anyone know of any books on DSC3 that are planned? Anyone working on tutorials or other helpful documentation? Anyone have any real examples with complex configurations?

[haodeon]

After using DSC v3 for a couple of months I believe the tool, at this stage, is focused on being easy to automate, rather than easy to use interactively.

Here are a few things I’ve learned that might help you get started:

• Resource PSModule was not found might be related to WindowsPowerShell adapter should not discover resources unavailable in Windows PowerShell #707 which was fixed in v3.1.0-preview.5.
• When running config test, check the inDesiredState: field. For an overall result there is actualState/inDesiredState:.
• It helps to have prior DSCv1/v2 experience. Reading PSDSC resource documentation is, for me, the easiest way to discover resources and how they work. It's probably not a beginner friendly pathway but I couldn't find another path.
• Learning about the schemas that define DSC v3 resource contracts will help you apply what you know from DSC v1/v2 to DSC v3.

Here is a working example of PSModule, note the repository value LocalRepo is a private repo.

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Install modules
    type: Microsoft.Windows/WindowsPowerShell
    properties:
      resources:
        - name: xPSDesiredStateConfiguration module
          type: PowerShellGet/PSModule
          properties:
            Name: xPSDesiredStateConfiguration
            MinimumVersion: 9.2.1
            Repository: LocalRepo
            Ensure: Present
        - name: Schannel module
          type: PowerShellGet/PSModule
          properties:
            Name: SChannelDsc
            MinimumVersion: 1.4.0
            Repository: LocalRepo
            Ensure: Present

There're probably easier modules to learn DSC with, PSModule was a bit of a trap for me.

I haven't done anything truly complex yet, but I would look at GitOps approaches to k8s yaml. There's a lot of good ideas you can use from there. There's also Bicep support coming which should ease authoring.

[mimachniak]

I tryed your example with PSGallery options and don't work on PS: 5.1 and 7.1

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Install modules
    type: Microsoft.Windows/WindowsPowerShell
    properties:
      resources:
        - name: xPSDesiredStateConfiguration module
          type: PowerShellGet/PSModule
          properties:
            Name: xPSDesiredStateConfiguration
            MinimumVersion: 9.2.1
            Repository: PSGallery
            Ensure: Present
        - name: Schannel module
          type: PowerShellGet/PSModule
          properties:
            Name: SChannelDsc
            MinimumVersion: 1.4.0
            Repository: PSGallery
            Ensure: Present

025-05-27T06:23:43.996627Z ERROR PID 8240: DSC resource 'PowerShellGet/PSModule' module not found.
2025-05-27T06:23:44.033016Z ERROR Error: Command: Resource 'powershell' [exit code 1] manifest description: Error