Adding a parameter to a Powershell MAML help file.

Recently I've been trying to learn a little bit of C#, and I decided that the best way for me to start is to include something that I'm familiar with, PowerShell.
I decided that I would try to wrap Slack.Webhooks in a PowerShell cmdlet, this should've been easy seeing as all of the hard C# work was already done, and I just needed to stuff it into a module. That's what I thought anyway. After four weeks spending about two hours on it a day and a couple of Saturdays, it's finally done; and I learned some pretty neat things along the way!

One of these things was that writing help for a compiled cmdlet is a lot harder than a native cmdlet as the only way to create the help is to make an XML file filled with MAML, probably the most difficult to read XML schema I've ever seen. I think that reading trying to understand MAML is what it must feel like to have dyslexia. It seems like a wall of text in a language you can't understand! Luckily the guys at Red-Gate have created this fantastic little tool that creates the help file for you if you add some special XML comments to your code. The only issue is that its support for Dynamic Parameters is relatively limited; and fair enough, Dynamic parameters are pretty crazy. In my case though, it meant my dynamic parameter wasn't displayed at all. Meaning that to the user, it didn't exist. I needed a way to fix this in a simple, repeatable manner and after a brief, informative exchange with Chris Lambrou, I figured that a PowerShell function included in my build script would do it. So I created Add-MAMLHelpParameter. I cheated with this one.

This cmdlet relies on the fact that you already have a fully formatted Help file with at least one parameter inside your cmdlet help. The reason being that it clones the first parameter node it finds, updates the text within it and appends it to the bottom of the list of parameters.

It works for me, and I hope it can help someone out there who is having a similar problem. Even if it just saves a little bit of time.

comments powered by Disqus