Writing comment-based help for class based custom DSC resources

Welcome Forums DSC (Desired State Configuration) Writing comment-based help for class based custom DSC resources

This topic contains 6 replies, has 2 voices, and was last updated by

 
Keymaster
2 years, 1 month ago.

  • Author
    Posts
  • #77052

    Participant
    Topics: 9
    Replies: 20
    Points: 0
    Rank: Member

    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

    Keymaster
    Topics: 13
    Replies: 4872
    Points: 1,843
    Helping HandTeam Member
    Rank: Community Hero

    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

      Participant
      Topics: 9
      Replies: 20
      Points: 0
      Rank: Member

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

  • #77116

    Keymaster
    Topics: 13
    Replies: 4872
    Points: 1,843
    Helping HandTeam Member
    Rank: Community Hero

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

    • #77172

      Participant
      Topics: 9
      Replies: 20
      Points: 0
      Rank: Member

      Thanks for clarifying!

    • #77220

      Participant
      Topics: 9
      Replies: 20
      Points: 0
      Rank: Member

      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

    Keymaster
    Topics: 13
    Replies: 4872
    Points: 1,843
    Helping HandTeam Member
    Rank: Community Hero

    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.

The topic ‘Writing comment-based help for class based custom DSC resources’ is closed to new replies.