I'm trying to create an external MAML help file for a script Module. As a test I created a simple module called "ModTest" with 2 functions saved in a .psm1 file:
function Test-SqlScript2 { } function Out-SqlScript2 { }
I saved the module in my user Modules directory ~\Documents\Modules\ModTest Next I created a subdirectory for a MAML file ~\Documents\Modules\ModTest\en-US The MAML file I'm using for testing is available here. I then started PowerShell and used Import-Module to import the module.
Unlike compiled cmdlets the placement of the file does not work by itself
So, next I tried adding the help link to the top of the script module, which also doesn't work:
<# .ExternalHelp C:\Users\cmiller6\Documents\WindowsPowershell\Modules\ModTest\en-US\ModTest.help.xml #> function Test-SqlScript2 { } function Out-SqlScript2 {
Then I tried adding the help info to each function, which does work:
function Test-SqlScript2 { <# .ExternalHelp C:\Users\cmiller6\Documents\WindowsPowershell\Modules\ModTest\en-US\ModTest.help.xml #> } function Out-SqlScript2 { <# .ExternalHelp C:\Users\cmiller6\Documents\WindowsPowershell\Modules\ModTest\en-US\ModTest.help.xml #>
Two questions:
- Is it possible to create a script module level external MAML help OR do you need to specify the help link in each function?
- Although the documentation claims and blog posts indicate that the language specific folder i.e. en-US will be automatically searched when specifying a path (~/ModTest\ModTest.help.xml) I could not get the MAML file to resolve unless I included the explicit path (~/ModTest/en-US/ModTest.help.xml). Is this a bug? See the following links for documentation on get-help and language specific folders:
Writing Help for Windows PowerShell Modules PowerShell V2 External MAML Help
Regarding #1, it appears to me that you have to specify the ExternalHelp comment tag for each command (script or function). Update: I got confirmation from the PowerShell team that you have to specify the comment tag for each command. I submitted a suggestion on MSConnect that you can vote on if you would like to see this in a future version of PowerShell.
Regarding #2, it does work and from my testing you don't have to specify the full path (which is very nice). Here are the contents of the module dir I created to test this:
~\Documents\WindowsPowerShell\Modules\ModTest\ModTest.psm1 ~\Documents\WindowsPowerShell\Modules\ModTest\en-US\ModTest.psm1-Help.xml ~\Documents\WindowsPowerShell\Modules\ModTest\fr-FR\ModTest.psm1-Help.xml
The contents of my ModTest.psm1 file is:
# .ExternalHelp ModTest.psm1-Help.xml function Add-BitsFile([object[]]$BitsJob, [string[]]$Destination, [string[]]$Source) { Write-Host "Add-BitsFile" } # .ExternalHelp ModTest.psm1-Help.xml function Complete-BitsTransfer([object[]]$BitsJob) { Write-Host "Complete-BitsTransfer" }
The two ModTest.psm1-Help.xml files are just a copy of:
"$pshome\Modules\BitsTransfer\en-US\Microsoft.BackgroundIntelligentTransfer.Management.dll-Help.xml"
The biggest PITA in testing this out was to get a valid MAML file so I just copied a known working file. :-) BTW for the French version I just prefixed the synopsis with "Parlez vous" so I could test that it worked.
Next up, you need a quick way to change the thread currentUICulture to test the different, localized help files. This is a function Jeffrey Snover wrote some time ago. I updated it to also change the CurrentUICulture:
function Using-Culture ( [System.Globalization.CultureInfo]$culture = ` (throw "USAGE: Using-Culture -Culture culture -Script {scriptblock}"), [ScriptBlock]$script= ` (throw "USAGE: Using-Culture -Culture culture -Script {scriptblock}")) { $OldCulture = [System.Threading.Thread]::CurrentThread.CurrentCulture $OldUICulture = [System.Threading.Thread]::CurrentThread.CurrentUICulture try { [System.Threading.Thread]::CurrentThread.CurrentCulture = $culture [System.Threading.Thread]::CurrentThread.CurrentUICulture = $culture Invoke-Command $script } finally { [System.Threading.Thread]::CurrentThread.CurrentCulture = $OldCulture [System.Threading.Thread]::CurrentThread.CurrentUICulture = $OldUICulture } }
Now let's test it:
PS> gmo|rmo PS> ipmo ModTest PS> Add-BitsFile -? NAME Add-BitsFile SYNOPSIS Adds one or more files to an existing Background Intelligent Transfer Service (BITS) transfer job. <snip> PS> using-culture fr-FR {gmo|rmo; ipmo ModTest; Add-BitsFile -?} NAME Add-BitsFile SYNOPSIS Parlez vous adds one or more files to an existing Background Intelligent Transfer Service (BITS) transfer job.
