Add a default implementation of a DSC Resource

[michaeltlombardi]

As an engineer developing and maintaining DSC Resources, I want to be able to inherit my implementation of a DSC Resource from a known implementation, overwriting defaults with my own custom handling only if needed.

As a follow up to #81, if there is a defined interface for basic DSC Resources, it would be even more useful to have a starting point for the implementation. This would reduce the amount of copy-paste and boilerplate code needed by DSC Resource authors while helping to ensure a more standardized experience for users as well.

By way of example, a common pattern I noticed when inspecting DSC Resources while working on the integration code for Puppet is that many DSC Resources reimplement their Get logic in their Test implementation. This is okay (though not necessary) as long as the implementations match. Unfortunately, in my experience, the implementations often did not match and this caused problems for integrating tools.

Instead, a default implementation could make it more difficult (and unnecessary) to implement anti-patterns, saving developer effort and improving the experience for integrating tools and end users.

Example Resources

Each of these DSC Resources reimplements some of the functionality of their own Get logic in Test instead of having Test compare the state reported by Get to the desired state.

HyperVDsc/DSC_VMNetworkAdapter

Source. This implementation calls Get-VMNetworkAdapter in both Get and Test.

NetworkingDsc/

Source. This implementation calls Get-NetAdapterAdvancedProperty in both Get and Test.

xExchange/ExchangeServer

Source. This implementation calls Get-ExchangeServerInternal in both Get and Test.

StorageDsc/DiskAccessPath

Source. This implementation calls Get-DiskByIdentifier in both Get and Test.

cChoco/cChocoSource

Source. This implementation retrieves the current state of the configuration in the Test method but the Get method always returns an object that actually seems to represent the desired state instead of current state.

cNtfsAccessControl/cNtfsPermissionEntry

Source. This implementation calls Get-Acl in both Get and Test.

ComputerManagementDsc

Source. This implementation calls Test-TimeZoneId in Test instead of reusing the value returned from Get (which calls Get-TimeZoneId). On inspection, Test-TimeZoneId is defined to call Get-TimeZoneId and compare the value it returns.

AccessControlDsc/NTFSAccessEntry

Source. This implementation calls Get-AccessControl in both Get and Test but processes that return value differently in both implementations which may be functionally identical but are not guaranteed to be.

GroupPolicyDsc/

Source. This implementation calls Get-GPO in both Get and Test.

Proposal

I propose that the IDscResource be extended with default implementations (proposed high-level implementation below).

This would allow, for example, a default Test method which compares each property specified for testing with the results of calling the Get method. If all of the properties of a DSC Resource can be compared directly to the values returned from Get, a DSC Resource author wouldn't need to override the method.

High Level Implementation

The IDscResource could be updated to:

• Have a hidden GetResourceState method which returns an empty hash (user will need to override this with their own logic to return the actual state, equivalent to the Get method today).
• Implement the Get method to:
  1. Initialize $CurrentState as an empty instance of the DSC Resource's class
  2. Call GetResourceState to find the current state of the resource
  3. Loop over the key-value pairs returned by GetResourceState to set the appropriate values on $CurrentState
  4. Return $CurrentState
• Implement the Test method to:
  1. Call the Get method to define $CurrentState
  2. Compare $CurrentState to the verifiable class properties (anything that isn't marked NotConfigurable or Parameter -see Add a Write-Only / Parameter Attribute for the DscProperty attribute #76), returning $false if any property is not equal and $true only if they are all correct. If Add support for reporting how a DSC Resource is out-of-state via the Test method #77 is accepted and implemented, this would need to behave differently so it can return the detailed information about how the resource is out of state (if it is).
• Have the Set method defined but do nothing (user will need to override this with their own logic to enforce desired state)

Alternative

If it is not possible to support default implementations in an interface, I believe the least work / best experience is to directly add default implementations to the interface proposed in #81. If that is not feasible, having a base class would also be valuable and functional.

[michaeltlombardi]

Additional benefits for this approach:

1. This could resolve the explicit vs default value for value-type properties problem (Support distinguishing between default and explicit values for value type properties #116)
2. This could enable supporting DSCv3's synthetic test behavior.
3. This could be a way forward for more reliably converting DSC Resource definitions into their JSON schema, supporting a default ToJsonSchema() method that a resource could override to return a more robust schema, without requiring a set of custom attributes.