Добавление поддержки Get-Help в командлеты PowerShell

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

Проблемы, связанные с использованием пользовательских командлетов, заключаются в отсутствии справочных ресурсов . По умолчанию для этих инструментов существует только минимальная справка. Для базовых функций он не очень хорош, но с ним можно работать. Тем не менее, почти все функции будут иметь параметры, а несколько сценариев могут быстро привести к неоднозначности и риску для вашей системы. Ни одно правило не говорит, что вы не можете создать свою собственную справку.

В этой статье я хочу показать вам, как заставить командлет Get-Help работать с пользовательскими командлетами. Начнем сначала с понимания модулей PowerShell .

Модули PowerShell

Если вы хотите создать пользовательские командлеты в PowerShell, вы должны начать с создания модуля . Модуль — это, по сути, просто файл сценария, который может включать в себя одну или несколько функций.

Каждая функция представляет собой отдельный командлет PowerShell, который может иметь собственные параметры и справку. Мы обсудим это позже, но сначала давайте посмотрим, как сделать модуль.

Создание модуля

Чтобы создать модуль и пользовательский командлет PowerShell, выполните следующие действия:

1. Создайте одну или несколько функций PowerShell в Блокноте .
2. Добавьте в сценарий команду Export-ModuleMember для каждой функции. Например, ' Export-ModuleMember-Function 'My-Function'. Здесь My-Function — имя функции.
3. Сохраните файл под любым именем, но убедитесь, что он имеет расширение.PSM1 .
4. Создайте папку в C:WindowsSystem32WindowsPowerShellv1.0Modules . Имя создаваемой папки должно совпадать с именем файла модуля. Например, MyModule.PSM1b , тогда имя папки должно быть MyModule.
5. Теперь, когда вы создали модуль, вы можете импортировать его с помощью командлета Import-Module , за которым следует имя модуля.

Изображение выше иллюстрирует файл модуля. Этот файл содержит одну функцию Get-MyProcess .

Как только модуль появится в системе, PowerShell будет рассматривать Get-MyProcess как автономный командлет. Давайте теперь посмотрим, как вы можете добавить справку к вашему новому пользовательскому командлету.

Добавление справки к пользовательскому командлету

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

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

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

Добавление поддержки Get-Help также называется справкой на основе комментариев . Причина, по которой Microsoft использует фразу «справка на основе комментариев», заключается в том, что она помогает организации комментариев. Необходимо сгруппировать эти комментарии вместе в блоке, начинающемся с <# и заканчивающемся на #> . Элементы справки должны располагаться после строк заголовков, в которых используется точка и ключевое слово, написанное прописными буквами . Поддерживаемые ключевые слова:

• СИНТАКСИС
• ОПИСАНИЕ
• ПАРАМЕТР
• ВХОДЫ
• ВЫХОДЫ
• ПРИМЕР
• ССЫЛКА НА САЙТ
• ЗАМЕТКИ
• СОСТАВНАЯ ЧАСТЬ
• РОЛЬ
• ФУНКЦИОНАЛЬНОСТЬ
• FORWARDHELPTARGETNAME
• ВПЕРЕДПОМОЩЬКАТЕГОРИЯ
• УДАЛЕННАЯ ПОМОЩЬ
• ВНЕШНЯЯ ПОМОЩЬ

Эти разделы являются необязательными , и вы можете использовать любую комбинацию по своему усмотрению. Если, например, вы хотите включить входные данные в справку на основе комментариев, это будет выглядеть так:

<#

.ВХОДЫ

Здесь вы должны ввести справочную информацию, связанную с вводом.

#>

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

Что пошло не так?

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

• Проверьте написание ключевых слов и убедитесь, что они написаны заглавными буквами.
• Убедитесь, что вы не забыли точку перед ключевым словом.
• Убедитесь, что ключевое слово находится на отдельной строке и после него ничего нет.
• Убедитесь, что все ключевые слова и комментарии находятся между открывающим и закрывающим маркерами.
• Проверьте регистр ключевого слова. В документации Microsoft указано, что ключевые слова не чувствительны к регистру. Тем не менее, более старые версии PowerShell поддерживают только ключевые слова в верхнем регистре. Придерживайтесь использования ключевых слов в верхнем регистре, это может облегчить жизнь.
• Убедитесь, что отсутствуют недопустимые элементы справки на основе комментариев.
• Попробуйте закрыть и снова открыть командную оболочку, чтобы очистить все данные, оставшиеся в кеше.
• Введите командлет Update-Help, чтобы заставить оболочку обновить данные.

После проверки этих элементов откройте PowerShell, импортируйте модуль и снова попробуйте получить помощь . Вы должны увидеть вывод, как показано на изображении ниже, хотя фактический вывод будет зависеть от содержимого файла.

Последние мысли

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

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

Часто задаваемые вопросы

При каких обстоятельствах вам может понадобиться добавить справку на основе комментариев в пользовательский командлет PowerShell?

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

Если вы внесете изменения в справку на основе комментариев, сможете ли вы повторно импортировать модуль без необходимости останавливать и перезапускать PowerShell?

Нет, на самом деле вам нужно завершить сеанс , чтобы обновить модуль . Это выгружает содержимое из кеша. Это то, что вы должны помнить при создании содержимого вашего модуля.

Что бы вы включили в комментарий к примеру PowerShell?

Раздел примеров обычно используется для предоставления пользователям примеров команд. Например, вы можете ввести полную команду PowerShell вместе с любыми необходимыми параметрами. Это позволяет тем, кто ищет помощи, увидеть, как именно работает команда.

Может ли модуль PowerShell содержать более одного пользовательского командлета?

Да, модули PowerShell обычно содержат множество пользовательских командлетов . Как и во многих языках высокого уровня, вы можете запускать сценарии независимо или вместе для выполнения задачи. Это позволяет перерабатывать общие функции и процессы для разных задач.

Нужны ли вам отдельные команды PowerShell Export-ModuleMember для каждой функции?

Да, вы делаете. Если вы забудете команду PowerShell Export-ModuleMember, пользовательский командлет не будет отображаться. Сначала вы не увидите сообщения об ошибке, так как командная оболочка пропустит любой ошибочный код. PowerShell требует, чтобы этот объект и его библиотека выполнялись правильно.

Может ли текст справки PowerShell занимать несколько строк?

Согласно Microsoft , текст справки PowerShell может занимать несколько строк . Большинство языков высокого уровня позволяют размещать текст на нескольких строках. Это отлично подходит для объяснения пользовательских командлетов, параметров и всего остального, что вам нужно.