Support enhanced export with `dsc config export`

[michaeltlombardi]

Summary of the new feature / enhancement

As an operator generating an exportable configuration from an existing system, I want more control over the generation for my exported configuration document. I want to be able to specify whether specific instances should be passed through to the generated document, even if they don't exist on the current system, are in the incorrect state, or are instances of non-exportable resources.

For example, a user might want to generate a configuration that:

• Creates a file instance using the existing contents of a file, even thought the Microsoft/File resource isn't exportable.
• Defines a set of registry keys, even though they don't exist on the current system.
• Retrieves and enumerates every instance of the Microsoft.IIS/WebServer resource in the output document.

Currently, only the last use case is supported.

Proposed technical implementation details (optional)

Add an export keyword to the resource instance schema that takes an enumeration:

• passthru (default for non-exportable resources) - indicates that the instance will be added to the output document exactly as it's defined in the input document.
• current - indicates that the instance will be added to the output document using its full current state. In this case, the required properties for the instance are used to get the current state of the instance instead of being ignored.
• all (default for exportable resources) - indicates that the any defined properties for the instance will be ignored and every instance of the resource should be exported to the output document.

This would better support generative configuration with less work for the end user. This would also enable reliable deterministic behavior for including any instances in the input document, instead of throwing an error for resources that don't support the export operation.

For non-export operations, the keyword should be ignored.

[!NOTE] An optional future extension to this model could be supporting the export value as an object that has the kind and properties keywords, where kind maps to the enums above and properties is an array of properties to keep for the output document. I bring this up to write it down somewhere, not to include it in the initial scope for this feature.

Alternative implementation: group resources

Instead of extending the keywords for the configuration, the same functionality could be accomplished by one or more group resources:

• A single DSC/Export group resource with properties for each kind of export: passthru, current, and all. Possible later support for filtered.
• A collection of DSC.Export/* resources, like DSC.Export/PassThru, one per kind of export.

This implementation might be a good alternative that modularizes the implementation and functionality for exporting away from core DSC, so it can use its own release cadence and be modified without affecting the versioning of DSC itself. I'm not sure whether this ends up being more work to maintain or roughly equivalent, but it does seem like it might be more resilient. I think there could be tradeoffs for UX here, but I haven't considered them deeply.

[SteveL-MSFT]

I was thinking about something related to this for set scenario, but I think it could be used for export as well. Basically similar to your group resource idea, but instead it's simply a DSC/GetGroup. So similar to the DSC/AssertionGroup which always runs test, this group would always run get. In the set scenario, you could use this to set variable values in your config, for example. In export, you would use this to get specific file or registry values as part of your export.

[michaeltlombardi]

I think it's probably sensible to have both a DSC/GetGroup and DSC/ExportGroup resource - they have different-enough purposes and requirements. For ExportGroup, we could forbid defining the properties of the listed resource types, or ignore that keyword unless/until we support filtered exports.

For GetGroup, we could define the resource to say "If you don't specify the properties keyword for an instance, it retrieves every instance" or similar, but also allow users to retrieve information for a specific resource if needed.

I think another option is to have a DSC/Export resource that only takes a list of resource types - moves away from having to continuously define a name/type/empty propertyset.

[SteveL-MSFT]

We discussed this in the WG and we could potentially reuse the RetrieveGroup (https://github.com/PowerShell/DSC/issues/268) idea such that a config doc that is used for export would process the RetrieveGroup with get operations (the FileResource example above) and the resulting exported config should be valid to use with set on another system.