Author Posts

August 9, 2017 at 9:47 pm

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!

August 9, 2017 at 9:53 pm

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.

August 10, 2017 at 2:20 pm

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

August 10, 2017 at 2:20 pm

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

August 10, 2017 at 7:57 pm

Thanks for clarifying!

August 11, 2017 at 4:08 pm

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!

August 11, 2017 at 4:10 pm

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.