Describing a Cmdlet type

You need to describe your Cmdlet classes with information that PoshBuild can use to create the Cmdlet help file. All of this isn't mandatory. If PoshBuild can't find some information, it will leave that section empty in the help file.
  • Add a DescriptionAttribute (from the .NET framework) and SynopsisAttribute (from PoshBuild) to your Cmdlet.
  • Add a DescriptionAttribute (from the .NET framework) on your Cmdlet properties.
  • Add a GlobbingAttribute (from PoshBuild) on the Cmdlet properties that accept wildcards.
  • Use the "HelpMessage" parameter of the ParameterAttribute (from Powershell) on your Cmdlet properties.

Using ICmdletHelpDescriptors

The problem with the above solution is that you will soon end up with a dependency on PoshBuild.dll, which is not desirable. To decouple this, you can create Cmdlet help descriptors, which will provide those attributes (Globbing, Synospis, etc.) on behalf of your Cmdlet type. Think of them as a simple, specific version of custom type descriptors.

Those descriptor types can actually be in the same assembly as the Cmdlet, because the CLR loads dependencies only on demand. You can imagine nobody except PoshBuild will load those descriptor types, so you can distribute your assembly without PoshBuild. However, you can of course defined the descriptor types in a separate assembly to be sure.

To define a Cmdlet help descriptor, just create a class that implements the ICmdletHelpDescriptor interface, and apply the CmdletHelpDescriptorAttribute on it, specifying what type this descriptor describes. The rest should be straightforward.

Last edited Jul 17, 2008 at 3:56 AM by ludovic_chabant, version 3


No comments yet.