Writing comment-based help for class based custom DSC resources

This topic contains 6 replies, has 2 voices, and was last updated by  Don Jones 2 months, 1 week ago.

  • Author
    Posts
  • #77052

    Sameer Kumar
    Participant

    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!

  • #77056

    Don Jones
    Keymaster

    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.

    • #77115

      Sameer Kumar
      Participant

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

  • #77116

    Don Jones
    Keymaster

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

    • #77172

      Sameer Kumar
      Participant

      Thanks for clarifying!

    • #77220

      Sameer Kumar
      Participant

      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!

  • #77223

    Don Jones
    Keymaster

    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.

You must be logged in to reply to this topic.