代码之家 › 专栏 › 技术社区 › Chad Miller

PowerShell v2外部MAML帮助

powershell

Chad Miller · 技术社区 · 15 年前

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

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

我将模块保存在用户模块目录~\documents\modules\modtest中接下来,我为maml文件创建了一个子目录~\documents\modules\modtest\en-us 我用于测试的MAML文件可用 here . 然后我启动了PowerShell并使用导入模块导入模块。

与编译的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帮助或是否需要指定帮助链接在每个功能中?
虽然文档声明和博客文章指示特定于语言的文件夹也就是说,我们会自动指定路径(~/modtest\modtest.help.xml)时搜索i 无法将MAML文件获取到解决除非我包括显式路径(~/modtest/en-us/modtest.help.xml)。这是虫子吗?请参阅以下内容获取帮助和特定语言文档的链接文件夹:

Writing Help for Windows PowerShell Modules PowerShell V2 External MAML Help

1 回复 | 直到 15 年前

Keith Hill 15 年前

关于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\modules\bitstransfer\en US\microsoft.backgroundintelligentttransfer.management.dll帮助.xml”

测试这个过程中最大的Pita是获取一个有效的maml文件,所以我只是复制了一个已知的工作文件。:-)顺便说一句,对于法语版本,我只是在概要前面加上了“parlez vous”,这样我就可以测试它是否有效。

接下来,您需要一种快速的方法来更改线程currentuiculture,以测试不同的本地化帮助文件。这是一个函数 Jeffrey Snover wrote some time ago . 我更新了它以改变当前的文化:

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.