Powershell V2 外部 MAML 帮助 [英] Powershell V2 External MAML Help

问题描述

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

function Test-SqlScript2{}函数 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#>函数 Test-SqlScript2{}函数 Out-SqlScript2{

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

function Test-SqlScript2{<#.ExternalHelp C:\Users\cmiller6\Documents\WindowsPowershell\Modules\ModTest\en-US\ModTest.help.xml#>}函数 Out-SqlScript2{<#.ExternalHelp C:\Users\cmiller6\Documents\WindowsPowershell\Modules\ModTest\en-US\ModTest.help.xml#>

两个问题:

1. 是否可以创建脚本模块级外部 MAML 帮助或你需要指定帮助链接吗在每个功能?
2. 虽然文档声明和博客文章指示语言特定文件夹即 en-US 将自动指定路径时搜索 (~/ModTest\ModTest.help.xml) 我无法获取 MAML 文件解决，除非我包括显式路径 (~/ModTest/en-US/ModTest.help.xml).这是一个错误吗?请参阅以下内容有关获取帮助和特定语言的文档的链接文件夹:

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

解决方案

关于#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.xmlfunction Add-BitsFile([object[]]$BitsJob, [string[]]$Destination,[字符串[]]$来源){写主机添加位文件"}# .ExternalHelp ModTest.psm1-Help.xmlfunction Complete-BitsTransfer([object[]]$BitsJob){写主机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 = `(抛出USAGE: Using-Culture -Cultureculture -Script {scriptblock}")，[ScriptBlock]$script= `(抛出用法:Usage-Culture -Cultureculture -Script {scriptblock}")){$OldCulture = [System.Threading.Thread]::CurrentThread.CurrentCulture$OldUICulture = [System.Threading.Thread]::CurrentThread.CurrentUICulture尝试 {[System.Threading.Thread]::CurrentThread.CurrentCulture = $culture[System.Threading.Thread]::CurrentThread.CurrentUICulture = $culture调用命令 $script}最后 {[System.Threading.Thread]::CurrentThread.CurrentCulture = $OldCulture[System.Threading.Thread]::CurrentThread.CurrentUICulture = $OldUICulture}}

现在让我们测试一下:

PS>转基因|rmoPS>ipmo 模组测试PS>添加位文件 -?名称添加位文件概要将一个或多个文件添加到现有的后台智能传输服务 (BITS) 传输作业.<剪断>PS>使用文化 fr-FR {gmo|rmo;ipmo 模组测试；添加位文件 -?}名称添加位文件概要Parlez vous 将一个或多个文件添加到现有背景智能传输服务 (BITS) 传输作业.

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:

1. Is it possible to create a script module level external MAML help OR do you need to specify the help link in each function?
2. 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.

这篇关于Powershell V2 外部 MAML 帮助的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！