Class-based resource capabilities in module manifest

[ThomasNieto]

Prerequisites

• Write a descriptive title.
• Make sure you are able to repro it on the latest version
• Search the existing issues.

Summary

There is an option in the module manifest to set which capabilities are present for a resource however that applies to all resources in the module and not to individual resources.

DSC/powershell-adapter/psDscAdapter/powershell.resource.ps1

Lines 90 to 100 in 7ed105e

	# Provide a way for existing resources to specify their capabilities, or default to Get, Set, Test
	# TODO: for perf, it is better to take capabilities from psd1 in Invoke-DscCacheRefresh, not by extra call to Get-Module
	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')
	}
	}

The schema should be updated to allow individual resources to specify their capabilities.

PSData = @{
  DscCapabilities = @{
    TestClassResource = @('get', test', 'export)
    NoExport = @('get', test')
  }
}

The ideal state is to allow class-based resources to not have to implement all methods. This could be done by checking the AST if the method contains a throw [NotImplementedException]::new() so that the code and capabilities match at all times.

Steps to reproduce

n/a

Expected behavior

n/a

Actual behavior

n/a

Error details

Environment data

n/a

Version

3.1-preview6

Visuals

No response

[michaeltlombardi]

I think it would be useful to consider an all-up re-approach to indicating metadata about DSC resources in module manifests. For example, something like:

@{
  PSData = @{
    DscResources = @{
      MyResource = @{
        Capabilities = @('get', 'test', 'set')
        Description = '<synopsis of the resource purpose and usage>'
        Tags        = @('Windows') # Optional
        Kind        = 'resource'   # Default if not specified
        Exceptions  = @(
          @{
            Type           = 'System.UnauthorizedAccessException' # The exception thrown
            MessagePattern = 'requires elevation'                 # Optional pattern to match
            ExitCode       = 2                                    # Exit code to propagate
          }
        )
      }
    }
  }
}

Right now, we don't have a way to surface most of this information. In the future, with the resource development kit (RDK), we'll be able to surface more of this information easier - but I think it's probably still a good idea to define a model to shortcut the adapter needing to analyze resources in full, particularly for use cases like searching for resources or integrating into editors and other higher-order tools.

[michaeltlombardi]

Thought about this a bit more, and I think what I would propose looks more like this:

# MyModule.psd1
@{
    PSData = @{
        'Microsoft.DSC' = @{
            Resources = @(
                @{  # Bundled into manifest for class resource
                    Type = 'MyModule/MyClassResource'
                    Description = 'description'
                    Tags = @('pwsh', 'Windows', 'Linux', 'macOS', 'foo')
                    Kind = 'resource'
                    Capabilities = @('get', 'set', 'export')
                    Schema = @{
                        # JSON Schema
                    }
                }
                @{ # Reference to external resource file (relative to manifest):
                    Manifest = 'MyModule.MyClassResource.dsc.resource.pwsh.yaml'
                }
            )
            # Alternately, point to a JSON or YAML resources file (relative to manifest):
            Resources = 'MyModule.dsc.resources.pwsh.json'
            Extensions = @(
                # Defines similar structure but for extensions implemented in PowerShell
            )
            Configurations = @(
                @{
                    Path = 'Example.dsc.config.yaml' # Relative to manifest
                    Description = 'Explanation of config purpose'
                    Tags = @()
                }
            )
        }
    }
}

Notes:

1. We use the Microsoft.DSC key instead of DscResources.
2. This key relates to how DSC understands the resources. It has no relation to the DscResourcesToExport key or PSDSC. Resources may be PSDSC compatible, but that's handled by existing manifest structure.
3. We could use this to support defining extensions in PowerShell (if we extend the adapter to surface/invoke extensions). We could also support surfacing shared configuration documents. Both are entirely excluded when we use DscResources as the top-level key.
4. We could support directly defining the data in the module manifest or referencing a separate data file, which has the same structure and schema. This is useful for enabling integrating tools to review a resource without needing to execute PowerShell or implement their own PSD1 parser.
5. We could support defining the data files one-per-resource or as a larger blob, which is just an array of definitions.
6. While hand-crafting this is very not-fun, we could provide DevX tooling to generate this information by inspecting the module. With that in place, we would advise authors to incorporate that tooling into their build pipeline instead of trying to ensure the implementation and data representation stay in sync.
7. While we can't (currently) provide much of an enhanced DevX for authoring this data in the module manifest, we can provide a pretty functional DevX for viewing/editing the data files with the enhanced authoring schemas for VS Code.

[gaelcolas]

I think that's a great way to expose the required metadata to the adapter, but is it the best?

If we put aside the adapter implementation for now, could DSC discover PowerShell class-based resources shipped within a module just by looking at a json (i.e. without even spinning up pwsh).

Maybe adding the complete metadata object in the module manifest is a bit too much, and would still require to read the psd1 (spin up pwsh).
Couldn't we have a convention that if there's a ModuleName.Microsoft.DSC.json (by convention) along the module PSD1 or PSM1 it would just find it and read the resources capabilities & info?
Then the right way to have the metadata would be in the class definition in the form of an attribute (and some could be derived/deduced from the class definition).

The RDK (or anyone) could create the attribute, and provide the tools used at compilation to generate the json.
Attribute would be in a third module that has to be Required/Nested for the parser.

Let's discuss, and we could discuss that during the community call tonight.

[gaelcolas]

As discussed with Mikey, discovery needs to look into $Env:PSModulePath, not Path...
So it should still be done from the adapater.

[SteveL-MSFT]

WG discussion is to have a new .dsc.adaptedresource.json (or yaml) file which is the current DscResource schema (not the manifest) with the addition of a new schema property that holds the JSONSchema. A new discover extension would traverse $env:PSModulePath to look for these files and the discover extension would be enhanced to allow extensions to return a list of manifests or a list of these new adapted manifests.

This will make discovery much faster than currently which needs to import the module or parse the module manifest. These resources will also just show up via dsc resource list without specifying the adapter making discovery better in addition to being faster. The current engine logic will fallback to querying adapters if the resource isn't found so existing PS class based resources will still be found the "old way".