Add support for reporting how a DSC Resource is out-of-state via the Test method

[michaeltlombardi]

As an operator and integrating vendor, I want to be able to rely on the DSC Resource to tell me not just that a resource is out of the desired state but how by returning the list of properties that are out of state with their current and desired states.

With the current implementation of DSC, I can verify that a particular DSC Resource is in or out of desired state with the Test method. I can manually compare the current state (retrieved with the Get method) to my desired state; however, this manual comparison will often require me to reimplement the functionality of the DSC Resource's own test code for complex resources; only DSC Resources whose values can be compared directly are relatively easy to inspect. Even then, it's additional work on the part of integrating vendors and users.

I propose extending the interface definition of a DSC Resource by enabling them to return a report on out-of-state properties when Invoke-DscResource -Method Test would return a $false result (i.e. the resource is out of desired state) for the purposes of both investigation and integration.

Proposed Solution

The implementation for this could break the existing usage of the Test method for Invoke-DscResource, so should perhaps be placed behind a switch like Detailed.

In the class, this could be implemented with a new TestDetailed() method which returns a hashtable like:

# out of desired state
@{
  InDesiredState = $false
  OutOfStateProperties = @{
    Foo = @{
      Current = 'Bar'
      Desired = 'Baz'
    }
  }
}
# in desired state
@{ InDesiredState = $true }

Probably, this hashtable should itself be a defined and exported class, maybe DscTestResult.

Another option to maintain (some) backwards compatibility would be to update the logic of Invoke-DscResource when calling Test: if the result of the call is a simple boolean, report the information in the existing result info.

[SteveL-MSFT]

The use case makes sense. I think a new switch for invoking Test also makes sense. However, I think we should also define a new capability that the DSCResource would provide if it implements this directly otherwise Invoke-DscResource would perform the Get and synthesize the diff.

[michaeltlombardi]

For class-based DSC Resources, I wonder if we could just check the available methods of the class and:

• if it has the TestDetailed() method, call it
• if it doesn't, call the Test() method and, if it returns false, call Get() and provide a best-attempt diff.

[ThomasNieto]

Isn't this already covered if the resource implements the Reasons property on the Get() method as to why the resource is out of compliance?

[michaeltlombardi]

No, for two reasons:

1. That's an extension of the resource definition that is specific to a single integrating tool.
2. It improperly (imo) moves the logic for validating the state of a DSC Resource from test to get. The updated guidance on implementing Reasons is to populate a reason for every resource property even when they're in the desired state. That makes them very human-readable, but also very difficult for integrating software to parse for usefulness.

From an integrating vendor perspective (and anyone who is looking to write script automation that uses the return information from Invoke-DscResource, I expect:

1. The validation logic is called for a DSC Resource when I invoke the Test method, not the Get method.
2. That I can programmatically determine from the result of Test both:
   • Whether the DSC Resource as a whole is in the desired state or not.
   • If the DSC Resource is not in the desired state, which properties are out-of-state and how. Sometimes, that's as simple as "foo is not bar" but sometimes it needs to address things like "a newer valid version is available."