WIP: DSC Configuration Migration Tool module

[Gijsreyn]

PR Summary

This is a helper module to transform DSC v1/v2 configuration documents to DSC v3 YAML or JSON using two commands: ConvertTo-DscJson or ConvertTo-DscYaml

The module itself has a dependency on the powershell-yaml module from the PowerShellGallery when users use the ConvertTo-DscYaml command.

[Gijsreyn]

@microsoft-github-policy-service agree

[Gijsreyn]

@SteveL-MSFT Just tagging someone to have a review and am curious about your thoughts.

[SteveL-MSFT]

@Gijsreyn thanks for this contribution! @michaeltlombardi and @michaeltlombardi would be better suited to review this

[Gijsreyn]

@SteveL-MSFT Thanks for the quick response. It was also my pleasure. I created a couple of issues which Andrew solved quite quickly. It's not only taking but also giving, which came from Mikey's repro.ps1 script in one of the issues here on GitHub as inspiration.

I can imagine that the initial module state is in it's basic form. I only wanted to pitch this idea to you guys to see if it is something for this repository, or if it can be a separate module on the gallery for users to install and adopt from v1/v2 to v3, as I can recognize many folks aren't familiar with executable syntax when they come from the PowerShell world (even though it is a learning curve in itself).

If it is something totally not desired, I can remove it as well if the vision is different. I don't want to push users to something that isn't somewhat "supported" or steered towards in the documentation @michaeltlombardi is working on. That might confuse users only more.

On the other hand, if it is helpful for users for adaptation purposes, the work is not lost and can be built upon further. Ideas that I still have in mind to include when desired are:

• When configurations resources are dot-sourced, it might be possible to use the Include keyword and somehow grab the upper layer of the dot-sourced script, if you know what I mean
• Expand on test scenarios. I know it's skimpy at the moment, but I didn't want to fully create a class or script-based module that could be imported with the Import-DscResource command.
• Build functions that execute the dsc.exe in itself. Thinking of Set-DscConfigResource that in essence calls Invoke-DscExe with the required arguments. When just writing it down, I have to keep in mind the noun and verb already used with PSDesiredStateConfiguration module and PSDSCResources.

[michaeltlombardi]

I've been thinking about this sort of thing a lot over the last few months. In my spare time, I've been prototyping some PowerShell code focused on the DevX for DSC resources and configurations. I think being able to convert a PSDSC config to a DSCv3 configuration document is extremely neat, but also very edge-case prone.

I think there's a lot of fertile ground in this area to help users and resource authors migrate from classic PSDSC to DSC.

I would recommend taking a dependency on yayaml instead of powershell-yaml - it uses an ALC if you're on PowerShell, and normal assembly loading for Windows PowerShell. This is primarily important because users can experience conflicts when using PlatyPS and powershell-yaml together, depending on their installed versions.

I'll do a proper review shortly. I'm not sure that this repository is the best place for a module designed to improve the DevX/UX for DSC in PowerShell in the long term, but I can't think of a better place for now.

[Gijsreyn]

I've been thinking about this sort of thing a lot over the last few months. In my spare time, I've been prototyping some PowerShell code focused on the DevX for DSC resources and configurations. I think being able to convert a PSDSC config to a DSCv3 configuration document is extremely neat, but also very edge-case prone.

I think there's a lot of fertile ground in this area to help users and resource authors migrate from classic PSDSC to DSC.

I would recommend taking a dependency on yayaml instead of powershell-yaml - it uses an ALC if you're on PowerShell, and normal assembly loading for Windows PowerShell. This is primarily important because users can experience conflicts when using PlatyPS and powershell-yaml together, depending on their installed versions.

I'll do a proper review shortly. I'm not sure that this repository is the best place for a module designed to improve the DevX/UX for DSC in PowerShell in the long term, but I can't think of a better place for now.

Thanks Mikey for the response. Is Microsoft.PowerShell.PlatyPS going to rely on powershell-yaml?

[Gijsreyn]

@anmenaga I accidentally also pushed changes for the psDscAdapter to discover operations methods for class-based DSC resources. This allows for a future more user-friendly error message whenever a method is getting called, it can return that the operation is not supported, instead of you cannot call a null value method. I yet have to figure out that last part do.

[anmenaga]

@anmenaga I accidentally also pushed changes for the psDscAdapter to discover operations methods for class-based DSC resources. This allows for a future more user-friendly error message whenever a method is getting called, it can return that the operation is not supported, instead of you cannot call a null value method. I yet have to figure out that last part do.

Please put these changes into a separate PR. Thank you.

[SteveL-MSFT]

@Gijsreyn I think we can experiment with migration tooling in this repo. Publishing it will be a different discussion.

[Gijsreyn]

@anmenaga I accidentally also pushed changes for the psDscAdapter to discover operations methods for class-based DSC resources. This allows for a future more user-friendly error message whenever a method is getting called, it can return that the operation is not supported, instead of you cannot call a null value method. I yet have to figure out that last part do.

Please put these changes into a separate PR. Thank you.

I'll push the changes after this one has finished up. Struggling to find the git commands... :(

[Gijsreyn]

@Gijsreyn I think we can experiment with migration tooling in this repo. Publishing it will be a different discussion.

All right, just let me know what road I can take. If you want me to enhance the current changes or expand on it, then give me a heads-up as well. I can see if I have some spare time to work on it :)

[michaeltlombardi]

Is Microsoft.PowerShell.PlatyPS going to rely on powershell-yaml?

If I remember correctly, the next major version of PlatyPS will use an ALC to load the YAML assembly for PowerShell users. There's not really a way around the conflicting version problem for Windows PowerShell, but I think that's okay.

[Gijsreyn]

I had some time to fiddle around and prototype this idea.

I have coined the PowerShell module Microsoft.PowerShell.DSC, but I believe it might be too ambitious. I have another name in the head if it requires to be changed.

In the recording, you find a new function called Invoke-DscResourceConfigurationDocument. I was able to get some argument completion on the available resources participating in DSC.

invoke-dscresourceconfigurationdocument.mp4

I'm adding data to the module itself and my further ideas are to expand on the dsc resource cache to get argument completion for adapter resources from PowerShell. There might also be a possibility of generating PowerShell objects that can instantly be sent to DSC if the input is at least known.

Let me know what you think.