Share via

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

  • Статья

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

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

Типы справки по модулям

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

  • Справка по командлетам. Разделы справки, описывающие командлеты в модуле, — это XML-файлы, использующие схему справки по командам.

  • Справка поставщика. Разделы справки, в которых описываются поставщики в модуле, — это XML-файлы, использующие схему справки поставщика.

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

  • Справка по скрипту. Разделы справки, описывающие скрипты в модуле, могут быть XML-файлами, которые используют схему справки команды или разделы справки на основе комментариев в модуле script или script.

  • Концептуальная Справка ("о программе"). Концептуальный раздел справки ("About") можно использовать для описания модуля и его элементов, а также для объяснения того, как эти элементы можно использовать вместе для выполнения задач. Основные разделы справки — это текстовые файлы с кодировкой Юникод (UTF-8). Имя файла должно иметь about_<name>.help.txt Формат, например about_MyModule.help.txt . По умолчанию PowerShell включает более 100 этих концептуальных разделов справки и форматирует их, как показано в следующем примере.

    TOPIC
    about_<subject or module name>

SHORT DESCRIPTION
    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.

KEYWORDS
    Terms or titles on which you might expect your users to search for the information in this topic.

SEE ALSO
    Text-only references for further reading. Hyperlinks cannot work in the PowerShell console.

Все файлы схемы можно найти в $PSHOME\Schemas\PSMaml папке.

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

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

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

<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 командлета, чтобы получить самые новые файлы справки из общей папки.

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

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

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

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

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

Начиная с версии PowerShell 3,0 можно помочь пользователям найти онлайн-версию командлетов и разделов справки по функциям, определив атрибут HelpUri в классе командлета или свойство HelpUri атрибута CmdletBinding . Значением атрибута является значение свойства HelpUri командлета или функции.

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

См. также:

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

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

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