Powershell V2 Внешняя справка по MAML

Question

Я пытаюсь создать внешний файл справки MAML для модуля скрипта. В качестве теста я создал простой модуль под названием «ModTest» с двумя функциями, сохраненными в файле .psm1:

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

Я сохранил модуль в моей пользовательской директории Modules ~ \ Documents \ Modules \ ModTest Затем я создал подкаталог для файла MAML ~ \ Documents \ Modules \ ModTest \ en-US Файл MAML, который я использую для тестирования, доступен здесь . Затем я запустил PowerShell и использовал Import-Module для импорта модуля.

В отличие от скомпилированных командлетов, размещение файла не работает само по себе

Итак, затем я попытался добавить ссылку помощи в начало модуля скрипта, которая также не работает:

<#
.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. Хотя документация претензии и сообщения в блоге указать, что папка для конкретного языка т.е. en-US будет автоматически искал при указании пути (~ / ModTest \ ModTest.help.xml) I не удалось получить файл MAML для решить, если я не включил явный путь (~ / ModTest / en-US / ModTest.help.xml). Это ошибка? Смотрите следующее ссылки на документацию по get-help и конкретному языку папки:

Написание справки для модулей Windows PowerShell Справка по MAML для PowerShell V2

Answer 1

Что касается # 1, мне кажется, что вы должны указать тег комментария ExternalHelp для каждой команды (сценария или функции). Обновление: Я получил подтверждение от команды PowerShell, что вы должны указать тег комментария для каждой команды. Я отправил предложение на MSConnect , по которому вы можете проголосовать, если хотите увидеть это в будущей версии PowerShell.

Что касается # 2, он работает, и из моего тестирования вам не нужно указывать полный путь (что очень хорошо). Вот содержимое модуля dir, который я создал, чтобы проверить это:

~\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, чтобы протестировать различные локализованные файлы справки. Это функция Джеффри Сновер написал некоторое время назад . Я обновил его, чтобы также изменить 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.