Поддержка справки в Интернете

Статья
2025-03-25

Примечание.

Создание справки на основе XML вручную очень сложно. Модуль PlatyPS позволяет написать справку в Markdown, а затем преобразовать ее в справку на основе XML. Это упрощает запись и обслуживание справки. PlatyPS также можно создать пакеты справки с возможностью обновления. Дополнительные сведения см. в статье Создание XML-справки с помощьюPlatyPS.

Начиная с PowerShell 3.0, существует два способа поддержки функции Get-Help Online для команд PowerShell. В этом разделе объясняется, как реализовать эту функцию для различных типов команд.

Сведения о справке по Сети

Веб-справка всегда была жизненно важной частью PowerShell. Несмотря на то, что командлет Get-Help отображает разделы справки в командной строке, многие пользователи предпочитают читать онлайн, включая цветовое кодирование, гиперссылки и совместное использование идей в документах на основе вики-сайтов и содержимого сообщества. Самое главное, прежде чем появление обновляемой справки, онлайн-справка предоставила самую up-to-date версию файлов справки.

С появлением обновляемой справки в PowerShell 3.0 веб-справка по-прежнему играет важную роль. Помимо гибкого взаимодействия с пользователем, онлайн-справка предоставляет помощь пользователям, которые не могут или не могут использовать обновляемую справку для скачивания тем справки.

Как работает Get-Help -Online

Чтобы помочь пользователям найти разделы справки по сети для команд, команда Get-Help имеет параметр Online, который открывает онлайн-версию раздела справки для команды в браузере по умолчанию пользователя.

Например, следующая команда открывает раздел справки по сети для командлета Invoke-Command.

Get-Help Invoke-Command -Online

Для реализации Get-Help -Onlineкомандлет Get-Help ищет универсальный код ресурса (URI) для справки по веб-версии в следующих расположениях.

Первая ссылка в разделе Связанных ссылок раздела справки для команды. Раздел справки должен быть установлен на компьютере пользователя. Эта функция появилась в PowerShell 2.0.
Свойство HelpUri любой команды. Свойство HelpUri доступно, даже если раздел справки для команды не установлен на компьютере пользователя. Эта функция появилась в PowerShell 3.0.

Get-Help ищет универсальный код ресурса (URI) в первой записи в разделе Связанных ссылок перед получением значения свойства HelpUri. Если значение свойства неверно или изменено, его можно переопределить, введя другое значение в первой связанной ссылке. Однако первая связанная ссылка работает только в том случае, если разделы справки установлены на компьютере пользователя.

Вы можете поддерживать Get-Help -Online для любой команды, добавив допустимый универсальный код ресурса (URI) в первую запись в разделе связанных ссылок раздела справки на основе XML для команды. Этот параметр действителен только в разделах справки на основе XML и работает только в том случае, если раздел справки установлен на компьютере пользователя. При установке раздела справки и заполнении URI это значение имеет приоритет над свойством HelpUri команды.

Для поддержки этой функции URI должен отображаться в элементе maml:uri в первом элементе maml:relatedLinks/maml:navigationLink в элементе maml:relatedLinks.

В следующем XML-коде показан правильный вариант размещения универсального кода ресурса (URI). Текст Online version: в элементе maml:linkText рекомендуется, но это не обязательно.

<maml:relatedLinks>
    <maml:navigationLink>
        <maml:linkText>Online version:</maml:linkText>
        <maml:uri>https://go.microsoft.com/fwlink/?LinkID=113279</maml:uri>
    </maml:navigationLink>
    <maml:navigationLink>
        <maml:linkText>about_History</maml:linkText>
        <maml:uri/>
    </maml:navigationLink>
</maml:relatedLinks>

Добавление свойства HelpUri в команду

В этом разделе показано, как добавить свойство helpUri в команды различных типов.

Добавление свойства HelpUri в командлет

Для командлетов, написанных на C#, добавьте атрибут HelpUri в класс Командлета. Значение атрибута должно быть универсальным кодом ресурса (URI), начинающимся с http или https.

В следующем коде показан атрибут HelpUri класса командлетов Get-History.

[Cmdlet(VerbsCommon.Get, "History", HelpUri = "https://go.microsoft.com/fwlink/?LinkID=001122")]

Добавление свойства HelpUri в расширенную функцию

Для расширенных функций добавьте свойство HelpUri в атрибут КомандлетBinding. Значение свойства должно быть универсальным кодом ресурса (URI), начинающимся с http или https.

В следующем коде показан атрибут HelpUri функции New-Calendar

function New-Calendar {
    [CmdletBinding(SupportsShouldProcess=$true,
    HelpUri="https://go.microsoft.com/fwlink/?LinkID=01122")]

Добавление атрибута HelpUri в команду cim

Для команд CIM добавьте атрибут HelpUri в элемент CommandMetadata в файле CDXML. Значение атрибута должно быть универсальным кодом ресурса (URI), начинающимся с http или https.

В следующем коде показан атрибут HelpUri команды Start-Debug CIM

<CmdletMetadata Verb="Debug" HelpUri="https://go.microsoft.com/fwlink/?LinkID=001122"/>

Добавление атрибута HelpUri в рабочий процесс

Для рабочих процессов, написанных на языке PowerShell, добавьте ключевое слово комментария .EXTERNALHELP в код рабочего процесса. Значение ключевого слова должно быть универсальным кодом ресурса (URI), начинающимся с http или https.

Примечание.

Свойство HelpUri не поддерживается для рабочих процессов на основе XAML в PowerShell.

В следующем коде показано ключевое слово .EXTERNALHELP в файле рабочего процесса.

# .EXTERNALHELP "https://go.microsoft.com/fwlink/?LinkID=138338"