Writing comment-based help for class based custom DSC resources

DSC
1

Hi,
I have started writing class-based custom DSC resources for my organization. However, I couldn’t find any internet article or post that gives any guidance on writing help for my resources. When I try below command in the console I get HelpNotFoundException:

Get-Help -Name RESOURCENAME

However, I can see MS article on writing help for DSC configurations. But nothing on resources.

Any pointers are appreciated.
Thanks!

2

Yyyyyeah. Resources don’t have a help function along those lines. Nor do classes. You have to document the module, not the command, basically in an about_*.txt help file.

Big reason to not use classes: no help.

3

Ah, bummer!
Any guidance around that .txt file regarding the structure or semantics?
Thanks!

4

No, it’s just a giant text file. It doesn’t have any structure. Like the about_ files.

5

Thanks for clarifying!

6

I was thinking to add -whatIf support to my custom DSC resource which will kind of dynamic help. Do you think it’s a good practice? How can I achieve that? Thanks!

7

Resources don’t support a -whatif, really. A function-based resource can obviously declare it, but the LCM never will use it.

The right way to structure the code, as we outline in “The DSC Book,” is to put ALL of your actual functionality into normal script modules, and then just CALL that from the Get/Test/Set resource functions/classes. That way, the actual useful code gets help, gets -whatif, gets everything - and the resource itself just becomes a thin, meaningless wrapper around it.