Help.xml and the PSModuleManifest

This forum can be browsed by the general public. Posting is limited to current SAPIEN license holders with active maintenance and does not offer a response time guarantee.
Forum rules
DO NOT POST LICENSE NUMBERS, ACTIVATION KEYS OR ANY OTHER LICENSING INFORMATION IN THIS FORUM.
Only the original author and our tech personnel can reply to a topic that is created in this forum. If you find a topic that relates to an issue you are having, please create a new topic and reference the other in your post.

Any code longer than three lines should be added as code using the 'Select Code' dropdown menu or attached as a file.
This topic is 8 years and 9 months old and has exceeded the time allowed for comments. Please begin a new topic or use the search feature to find a similar but newer topic.
User avatar
roswald72@hotmail.com
Posts: 1
Last visit: Thu May 26, 2022 8:35 pm

Help.xml and the PSModuleManifest

Post by roswald72@hotmail.com »

Hello Help-Writers,

PowerShell Help-Writer is the only fantastically cool product for the code that I'm currently working on! I started trying to write the .xml by hand and it was taking forever. I did learn a few xml tricks along the way, but this product certainly writes and validates xml the right way. Easily, so far.

So, I'm currently converting PowerShell script modules to PowerShell binary modules in C#, basically learning through examples in the PowerShell 3.0 SDK, where there is little to find about get-help and binary modules.

My old modules have the full comment-based help with many, many examples. Like 15 to 20.

I have already utilized the Sapien Help-Writer demo to it's full term, to successfully convert the comment based help files to xml files. Everything worked out very nicely in Visual Studio 2012 using C# as it usually does.

For Example: I have the following files in my User PSModule folder (I am using the well-formed naming of files and folders)

\Modules\MyBinaryPSModule\MyBinaryPSModule.psm1
\Modules\MyBinaryPSModule\MyBinaryPSModule.dll
\Modules\MyBinaryPSModule\MyBinaryPSModule.dll-Help.xml

This works well, but it's not quite finished without adding the manifest file named...

\WindowsPowerShell\Modules\MyBinaryPSModule\MyBinaryPSModule.psd1

What would be the best way to include the Help.xml in the module manifest?

Here is the basic content of the manifest that I have so far, but I can't get the Get-Help to work for the cmdlets written in the C# assembly that are the "Get-FirstBinaryCommand" etc.

@{

# Script module or binary module file associated with this manifest
ModuleToProcess = 'MyBinaryPSModule.psm1'

# Modules that must be imported into the global environment prior to importing
# this module
RequiredModules = @()

# Assemblies that must be loaded prior to importing this module
RequiredAssemblies = @()

# Modules to import as nested modules of the module specified in
# ModuleToProcess
NestedModules = @('MyBinaryPSModule.dll')

# Cmdlets to export from this module
CmdletsToExport = @("Get-FirstBinaryCommand",
"Get-SecondBinaryCommand",
"Get-ThirdBinaryCommand")

# Variables to export from this module
VariablesToExport = '*'

# Aliases to export from this module
AliasesToExport = '*'

# List of all modules packaged with this module
ModuleList = @()

# List of all files packaged with this module
FileList = @()

# Private data to pass to the module specified in ModuleToProcess
PrivateData = ''

}

Actually, when I got this to work before, I had the 'MyBinaryPSModule.dll' as the ModuleToProcess, and I have continued to add a few non-binary cmdlets in the 'MyBinaryPSModule.psm1' which is now my ModuleToProcess.

Can you shed some light on this type of implementation using both script and binary cmdlets?

And how it add them to the module manifest?

Sincerly Yours,

roswald72
User avatar
SAPIEN Support Forums
Posts: 945
Last visit: Thu Oct 22, 2015 1:10 pm

Help.xml and the PSModuleManifest

Post by SAPIEN Support Forums »

This is an automated post. A real person will respond soon.

Thank you for posting, roswald72@hotmail.com.

Did you remember to include the following?
  • 1. Product, version and build (e.g. Product: PowerShell Help Writer 2015, Version & Build: 1.0.9. Version and build information can be found in the product's About box accessed by clicking the blue icon with the 'i' in the upper right hand corner of the ribbon.)
    2. Specify if you are running a 32 or 64 bit version
    3. Specify your operating system and if it is 32 or 64 bit.
    4. Attach a screenshot if your issue can be seen on the screen
    5. Attach a zip file if you have multiple files (crash reports, log entries, etc.) related to your issue.
If not, please take a moment to edit your original post or reply to this one.

*** Make sure you do not post any licensing information ***
User avatar
juneblender
Posts: 93
Last visit: Thu Mar 30, 2017 8:54 am

Re: Help.xml and the PSModuleManifest

Post by juneblender »

Hi, Roswald. Thanks for the nice comments about HelpWriter. I'm pretty jazzed about this tool, too.

There are no keys in the module manifest to indicate the existence or location of a help file for any module type.

To write help for cmdlets defined a .dll, just put the help file (named for the dll: MyBinaryPSModule.dll-Help.xml) in a language-specific subdirectory of the module directory (e.g. <ModuleBase>\en-US). (You can also put it in ModuleBase, but that's not a best practice.)

Because there's no predetermined help file name for functions, you can also put help for the functions that your .psm1 file exports in the same help file. Remember to add a .ExternalHelp comment keyword to each of the functions. The value of the keyword is the name (no need for a path) of the help file.

e.g.
# .ExternalHelp MyBinaryPSModule.dll-Help.xml
function MyFunction
{
...
}

For more info, see Writing XML Help for Advanced Functions

Interestingly, the module type is determined not just by the files in the module, but also by the ModuleToProcess or RootModule key in the manifest. If there is no ModuleToProcess/RootModule key (list the .dll and .psm1 files in the NestedModules key), it's a manifest module. If the ModuleToProcess is your .dll, it's a binary module, and if the ModuleToProcess is your .psm1, it's a script module.

Hope that helps.
This topic is 8 years and 9 months old and has exceeded the time allowed for comments. Please begin a new topic or use the search feature to find a similar but newer topic.