powershell - Powershell V2外部MAML帮助

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

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

我将模块保存在我的用户Modules目录〜\ Documents \ Modules \ ModTest中
接下来，我为MAML文件〜\ Documents \ Modules \ ModTest \ zh-CN创建了一个子目录
我用于测试的MAML文件位于here中。然后，我启动了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
#>

两个问题:

是否可以创建脚本
模块级别的外部MAML帮助或
您是否需要指定帮助链接
在每个功能？

虽然
文档声明和博客文章
指示特定于语言的文件夹
即en-US将自动
指定路径时搜索(〜/ ModTest \ ModTest.help.xml)我
无法将MAML文件获取到
解决，除非我包括
显式路径(〜/ ModTest / zh-CN / ModTest.help.xml)。这是一个错误吗？见以下
有关获得帮助和特定于语言的文档的链接
文件夹:

Writing Help for Windows PowerShell Modules
PowerShell V2 External MAML Help

最佳答案

关于＃1，在我看来您必须为每个命令(脚本或函数)指定ExternalHelp注释标签。 更新:我从PowerShell团队得到确认，您必须为每个命令指定注释标记。我提交了suggestion on MSConnect，如果您希望在PowerShell的 future 版本中看到它，可以对其进行投票。

关于＃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 wrote some time ago。我更新了它，还更改了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.