Should DscCapabilities become a standard

[Gijsreyn]

Hi all,

When working with the PowerShell adapters, I notice the following code block when discovering capabilities:

if ($DscResourceInfo.ModuleName) {
  $module = Get-Module -Name $DscResourceInfo.ModuleName -ListAvailable | Sort-Object -Property Version -Descending | Select-Object -First 1
  if ($module.PrivateData.PSData.DscCapabilities) {
      $capabilities = $module.PrivateData.PSData.DscCapabilities
  }
  else {
      $capabilities = @('Get', 'Set', 'Test')
  }
}

In many DSC community modules, I couldn't really find the DscCapabilities property included in the .psd1 file extension. Is this a standard or should this be documented in this project for DSC class-based resources?

[michaeltlombardi]

This usage isn't stable or standardized yet - none of the community PSDSC modules use this because I don't think any of them have updated (or are likely to update until closer to GA) for DSCv3 enhancements.

As far as I know, every class-based PSDSC resource currently available only implements Get, Set, and Test per the classic model (where get returns the current state, test returns a boolean, set returns nothing).

In the future, class-based PSDSC resources might also support the export, delete, or what-if operations, or they might forego implementing test to rely on v3's built-in synthetic test functionality.

The current implementation of capabilities in private data also applies to every resource in the module, not specific resources.

[Gijsreyn]

Hey Mikey, thanks for your extensive reply. Love to see your vision on it.

What I was primarily looking for, is the fact that "if" customers are implementing different operations that adhere to the v3 core engine, they should have some kind of document that states, add it to the .psd1 file with these key/value properties. Clearly, that's at least what the script is currently looking at. Something for DSC community call to discuss?

[michaeltlombardi]

I'm not sure we should document this behavior just yet, because we haven't stabilized on a design and model - it's the current implementation, but the only resources implementing any of the v3 enhancements are test resources in this repo.

I've been having some thoughts and prototyping a model for both resource development and advertising in the manifest, but nothing concrete yet.

My concern with documenting this behavior (which applies to every resource in the module, rather than per-resource) is that folks will adopt it and then not realize the model has changed. Once we document it, the chance it gets picked up in blog posts and shared on community help forums skyrockets.

I am planning a full set of documentation about writing and publishing DSCv3 resources in PowerShell - those docs will definitely exist and describe how to author resources to take advantage of all the features in v3.

[Gijsreyn]

Cool, thanks again Mikey. I have documented this in my handbook on LeanPub. I'm trying to incorporate as many changes when it is updated in this repository.

If you need any help with documentation, would always love to brainstorm about it and help write where possible.

[michaeltlombardi]

I would be happy to sync about docs at some point! Up until very recently my focus has been on reference docs for the schema and commands, but I'll be expanding the narrative and concept docs as things stabilize.

[Gijsreyn]

Love to see the work coming Mikey.