Powershell V2 外部 MAML 帮助

Question

我正在尝试为脚本模块创建外部 MAML 帮助文件。作为测试，我创建了一个名为“ModTest”的简单模块，其中包含 2 个保存在 .psm1 文件中的函数：

function Test-SqlScript2 
{
}
function Out-SqlScript2
{
}

我将模块保存在我的用户模块目录 ~\Documents\Modules\ModTest 接下来我为 MAML 文件创建了一个子目录 ~\Documents\Modules\ModTest\en-US 我用于测试的 MAML 文件可在此处获得。然后我启动了 PowerShell 并使用 Import-Module 来导入模块。

与已编译的 cmdlet 不同，文件的位置本身不起作用

所以，接下来我尝试将帮助链接添加到脚本模块的顶部，这也不起作用：

<#
.ExternalHelp C:\Users\cmiller6\Documents\WindowsPowershell\Modules\ModTest\en-US\ModTest.help.xml 
#>


function Test-SqlScript2 
{
}
function Out-SqlScript2
{

然后我尝试将帮助信息添加到每个函数中，这确实有效：

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 
#>

两个问题：

1. 是否可以创建脚本模块级别的外部 MAML 帮助，或者您是否需要在每个函数中指定帮助链接？
2. 尽管文档声明和博客文章表明在指定路径 (~/ModTest\ModTest.help.xml) 时将自动搜索特定于语言的文件夹，即 en-US，但我无法解析 MAML 文件，除非我包含显式路径（~/ModTest/en-US/ModTest.help.xml）。这是一个错误吗？有关 get-help 和特定语言文件夹的文档，请参阅以下链接：

为 Windows PowerShell 模块编写帮助 PowerShell V2 外部 MAML 帮助

Answer 1

关于#1，在我看来，您必须为每个命令（脚本或函数）指定 ExternalHelp 注释标签。 更新：我从 PowerShell 团队那里得到确认，您必须为每个命令指定注释标签。我在 MSConnect 上提交了一个建议，如果您希望在未来版本的 PowerShell 中看到这一点，您可以对其进行投票。

关于#2，它确实有效，并且根据我的测试，您不必指定完整路径（这非常好）。以下是我创建的用于测试的模块目录的内容：

~\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

我的 ModTest.psm1 文件的内容是：

#  .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"
}

两个 ModTest.psm1-Help.xml 文件只是以下内容的副本：

“$pshome\Modules\BitsTransfer\en-US\Microsoft.BackgroundIntelligentTransfer.Management.dll-Help.xml”

测试这个最大的 PITA 是获得一个有效的 MAML 文件，所以我只是复制了一个已知的工作文件。:-) 顺便说一句，法语版我只是在概要前加上“Parlez vous”，这样我就可以测试它是否有效。

接下来，您需要一种快速的方法来更改线程 currentUICulture 以测试不同的本地化帮助文件。这是Jeffrey Snover 前段时间写的一个函数。我更新了它也改变了 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
    }    
}

现在让我们测试一下：

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.