Поделиться через

Написание справки по модулям PowerShell

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

В этом документе объясняется формат и правильное размещение разделов справки по модулю, и он предлагает рекомендации по содержимому справки по модулю.

Справка по модулям

Модуль может включать следующие типы справки.

  • Справка на основе XML

    • Справка по командлетам. Разделы справки, описывающие командлеты в модуле, — это XML-файлы, использующие схему справки команды.
    • Справка поставщика. Разделы справки, описывающие поставщиков в модуле, — это XML-файлы, использующие схему справки поставщика.
    • Справка по функциям. Разделы справки, описывающие функции в модуле, могут быть XML-файлы, использующие схему справки или разделы справки на основе комментариев в функции, скрипт или модуль скрипта.
    • Справка по скрипту. Разделы справки, описывающие скрипты в модуле, могут быть XML-файлы, использующие схему справки команды или разделы справки на основе комментариев в модуле скрипта или скрипта.
    • Папка $PSHOME\Schemas\PSMaml содержит файлы схемы, определяющие формат XML.

  • Концептуальные ("О") справки по текстовым файлам

    Вы можете использовать концептуальный раздел справки (about) для описания модуля и его членов и объяснить, как члены могут использоваться вместе для выполнения задач. По умолчанию PowerShell включает более 100 этих концептуальных разделов справки. Имя файла должно использовать about_<name>.help.txt формат, например about_MyModule.help.txt.

    Замечание

    Заголовок TOPIC раздела должен начинаться в первом столбце первой строки файла. Содержимое раздела во второй строке должно соответствовать имени файла без .help.txt суффикса. Необходимо отступить содержимое ровно 4 пробела. Третья строка должна быть пустой. Заголовок SYNOPSIS раздела должен начинаться в первом столбце четвертой строки. Необходимо отступить содержимое в пятой строке ровно 4 пробела. Эти требования необходимы для правильного распознавания содержимого командлетом Get-Help .

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

    В качестве отправной точки можно использовать следующий пример шаблона для написания концептуальных разделов справки. За исключением первых двух разделов, структура концептуальных разделов справки является произвольной. Остальные заголовки разделов могут быть подходящими для вашего содержимого.

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

LONG DESCRIPTION

A detailed, full description of the subject or purpose of the module.

EXAMPLES

Examples of how to use the module or how the subject feature works in
practice.

TROUBLESHOOTING

Instructions for resolving common problems.

SEE ALSO

Text-only references for further reading. Hyperlinks can't work in the
PowerShell console.

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

    • Используйте UTF-8 с кодировкой BOM, чтобы обеспечить правильное отображение любых специальных (многобайтовых) символов.
    • Заголовки разделов подчеркивания или используйте все прописные буквы, чтобы они выделялись. Это упрощает сканирование содержимого.
    • Ограничить длину каждой строки до 80 символов.
    • Отступ блоков кода и пример выходных данных для разделения их от окружающего prose.

Справка по размещению модуля

Командлет Get-Help ищет файлы раздела справки модуля в подкаталогах для конкретного языка каталога модуля.

Например, на следующей схеме структуры каталогов показано расположение разделов справки для модуля SampleModule.

<ModulePath>
    \SampleModule
        \<en-US>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml
        \<fr-FR>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml

Замечание

В примере <ModulePath> заполнитель представляет один из путей в PSModulePath переменной среды, например $HOME\Documents\Modules$PSHOME\Modules, или пользовательский путь, заданный пользователем.

Получение справки по модулю

Когда пользователь импортирует модуль в сеанс, разделы справки для этого модуля импортируются в сеанс вместе с модулем. Вы можете перечислить файлы раздела справки в значении ключа FileList в манифесте модуля, но разделы справки не влияют на Export-ModuleMember командлет.

Вы можете предоставить разделы справки по модулю на разных языках. Командлет Get-Help автоматически отображает разделы справки по модулю на языке, указанном для текущего пользователя в элементе "Региональные и языковые параметры" на панели управления. В Windows Vista и более поздних версиях Windows Get-Help выполняет поиск разделов справки в подкаталогах для конкретного языка каталога модулей в соответствии со стандартами, установленными для Windows.

Начиная с PowerShell 3.0, выполнение Get-Help команды для командлета или функции активирует автоматический импорт модуля. Командлет Get-Help немедленно отображает содержимое разделов справки в модуле.

Если модуль не содержит разделы справки и нет разделов справки для команд в модуле на компьютере пользователя, Get-Help отобразится автоматическая справка. Автоматическая справка включает синтаксис команды, параметры и типы входных и выходных данных, но не содержит никаких описаний. Автоматическая справка содержит текст, который направляет пользователя, чтобы попытаться скачать Update-Help справку по команде из Интернета или общей папки. Он также рекомендует использовать параметр Online командлета Get-Help , чтобы получить веб-версию раздела справки.

Поддержка обновляемой справки

Пользователи PowerShell 3.0 и более поздних версий PowerShell могут скачать и установить обновленные файлы справки для модуля из Интернета или из локальной общей папки. Update-Help Командлеты Save-Help скрывают сведения об управлении от пользователя. Пользователи запускают Update-Help командлет, а затем используют Get-Help командлет для чтения новых файлов справки для модуля в командной строке PowerShell. Пользователям не нужно перезапускать Windows или PowerShell.

Пользователи за брандмауэрами и без доступа к Интернету также могут использовать обновляемую справку. Администраторы с доступом Save-Help к Интернету используют командлет для скачивания и установки новых файлов справки в общую папку. Затем пользователи используют параметр Path командлета Update-Help , чтобы получить самые новые файлы справки из общей папки.

Авторы модулей могут включать файлы справки в модуль и использовать обновляемую справку для обновления файлов справки, а также опустить файлы справки из модуля и использовать обновляемую справку как для установки, так и для обновления.

Дополнительные сведения о обновляемой справке см. в статье "Поддержка обновляемой справки".

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

Пользователи, которые не могут или не устанавливают обновленные файлы справки на своих компьютерах, часто полагаются на веб-версию справки модуля. Параметр Get-Help командлета открывает веб-версию командлета или раздел справки по расширенной функции для пользователя в браузере по умолчанию.

Командлет Get-Help использует значение свойства HelpUri командлета или функции для поиска веб-версии раздела справки.

Начиная с PowerShell 3.0, вы можете помочь пользователям найти онлайн-версию командлета и справки функций, определив атрибут HelpUri в классе командлета или свойстве HelpUri атрибута КомандлетBinding . Значение атрибута — это значение свойства HelpUri командлета или функции.

Дополнительные сведения см. в справке по интернету.

См. также

  • Last updated on