Question

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

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

我将模块保存在用户模块目录〜\ Documents \ Modules \ ModTest中接下来，我为MAML文件〜\ Documents \ Modules \ ModTest \ en-US创建了一个子目录我用于测试的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帮助OR 你需要指定帮助链接吗？在每个功能？
虽然文档声明和博客文章表示语言特定文件夹即en-US将自动进行在指定路径时搜索（〜/ ModTest \ ModTest.help.xml）I 无法获取MAML文件解决，除非我包括显式路径（〜/ ModTest / en-US / ModTest.help.xml）。这是一个错误吗？请参阅以下内容有关get-help和特定语言的文档链接文件夹：

Writing Help for Windows PowerShell Modules PowerShell V2 External MAML Help

Answer 1

关于＃1，在我看来，您必须为每个命令（脚本或函数）指定ExternalHelp注释标记。 更新：我从PowerShell团队得到确认，您必须为每个命令指定注释标记。我提交了一个suggestion on 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的\模块\ BitsTransfer \ EN-US \ Microsoft.BackgroundIntelligentTransfer.Management.dll-Help.xml”

测试中最大的PITA是获取有效的MAML文件，所以我只是复制了一个已知的工作文件。 :-) BTW对于法语版我只是用“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.

Powershell V2外部MAML帮助

1 个答案: