Include metadata in result objects

[michaeltlombardi]

Summary of the new feature / enhancement

As a user, I want to have my configuration result objects¹ include contextual information about the operation in the result data, so that I don't need to collate the metadata myself manually.

For example, it would be useful to have a metadata property in the result object that indicates the security context the operation was run under, when the run started/ended, the duration, and whether it was for a what-if operation.

Currently, I get a response like this from dsc config set:

results:
 - name: my foo bar
   type: Foo/Bar
   result:
     beforeState:
       foo: 1
       bar: false
     afterState:
       foo: 1
       bar: true
     changedProperties:
     - bar
messages: []
hadErrors: false

With metadata, I could get something like:

metadata:
  Microsoft.DSC:
    operation: set
    whatIf: false
    startTime: 2024-04-12T14:24:23.132085-05:00
    endTime: 2024-04-12T14:28:13.431173-05:00
    duration: 00:03:50.2990880
    securityContext: Elevated
results:
 - name: my foo bar
   type: Foo/Bar
   result:
     beforeState:
       foo: 1
       bar: false
     afterState:
       foo: 1
       bar: true
     changedProperties:
     - bar
messages: []
hadErrors: false

Starting with a property bag of returned metadata makes the output easier to extend and modify over time. Out of scope for this request, I think it would also enable resources and adapters to return metadata that might be useful for the caller. Also out of scope for this initial request is control over whether/which metadata items get included in the result - we may want to make this configurable and extensible in the future, but the initial request is to extend the schema and output with an initial set of metadata properties.

Proposed technical implementation details (optional)

Update the code and schemas for the configuration results to include a metadata property with the following keys under the Microsoft.DSC property:

• operation - which operation DSC performed - this can take the guesswork out of the object type inference.
• whatIf - only for set operations, indicates whether the config was called with the whatIf flag.
• startTime - When the operation started.
• endTime - When the operation ended.
• duration - Pre-calculated duration between startTime and endTime so callers don't need to perform the calculation.
• securityContext - what security context the operation was performed under.

Footnotes

1. For now, I'm scoping this request to the configuration results, but I can see value in it on a resource-level, too. ↩

[SteveL-MSFT]

@michaeltlombardi would it be better to have executionType: whatIf instead? It would allow future execution types if any exist but I think it's more readable than true/false.

[michaeltlombardi]

I think executionType: whatIf is a good alternative. Mostly I kept it as a separate property to simplify object handling (the structure for the output object is the same for both whatIf and set in your proposal) and be more explicit, but it's straightforward to document that whatIf and set share a structure, too.

As you note, we might have other execution types, which could also be property keys or values, like executionType: rollbackOnFailure, executionType: stopOnFailure vs onFailure: rollback etc. I don't think either is more inherently extensible, but I'm open to executionType: whatIf being more readable.