Один из самых эффективных инструментов, которые помогают пользователям изучать механизмы оболочки PowerShell, — ее справочная система, и в первую очередь — команда Get-Help. Для изучающих среду PowerShell это одна из трех ключевых команд (остальные две — команды Get-Command и Get-Member). Если вам когда-либо доводилось работать с технологией PowerShell, вы, скорее всего, использовали команду Get-Help (или один из ее псевдонимов — help и man).
Справочная система загружается автоматически в ходе установки оболочки PowerShell, но если вы работаете с третьей или более новой версией этого продукта, не забудьте выполнить команду Update-Help при первом запуске PowerShell и регулярно запускать ее в дальнейшем. Дело в том, что Microsoft постоянно добавляет в справочную систему новые темы и исправляет ошибки в существующих темах, обнаруженные сотрудниками компании, а также другими пользователями. Предоставляя возможность выполнять команду Update-Help на вашей системе, Microsoft позволяет вам экономить значительную часть дискового пространства: ведь на вашу машину загружаются средства поддержки лишь того языка, который вы определили для своей системы, а не для всех языков, которые, возможно, указала система.
Сценарий PowerShell Get-Help
Однако помощь, получаемая вами от PowerShell, — это еще не все. Взяв за основу справочную функцию на базе комментариев, реализованную разработчиками во второй версии PowerShell, вы можете предоставить такую же помощь будущим пользователям написанных вами функций и сценариев. В этой версии добавлена возможность включения в сценарии многострочных комментариев. В качестве разделителей этих комментариев применяются пары символов '<#' и '#>'. Используются они следующим образом:
# Любой однострочный комментарий
<#
Сюда может быть включено любое число комментариев.
#>
Как применять справочную информацию
И как же использовать справочные данные в соответствии с вашим замыслом? В сущности все довольно просто. Достаточно определить в комментарии несколько ключевых слов и поместить комментарий в начало вашего сценария или в начало функции, и тогда каждый, кто будет пользоваться этим сценарием или функцией, сможет получить помощь точно таким же образом, каким вы получали нужные сведения с помощью команды Get-Help.
Ключевые слова, которые вы будете использовать, называются тегами. Я применяю такие базовые теги:. SYNOPSIS,. DESCRIPTION и. EXAMPLE. Тег. SYNOPSIS позволяет дать краткое определение задачи, выполняемой сценарием или функцией. Тег. DESCRIPTION дает возможность представить более детальные сведения, а тег. EXAMPLE позволяет привести примеры применения вашего сценария или функции с тем, чтобы пользователь понял, как следует должным образом их вызывать. Ниже помещается раздел комментариев из сценария, который я использую для того, чтобы присвоить владельцам всех баз данных имя 'sa'.
<# . Synopsis . ..Изменяет имя владельца базы данных на SA для всех баз данных данного экземпляра. . DESCRIPTION . ..Этот сценарий проверяет каждую базу данных на указанном экземпляре, и если . ..свойство «владелец» имеет значение, отличное от SA, это значение изменяется на SA. . EXAMPLE . /Set-DatabaseOwnerToSA.ps1 WS12SQL . EXAMPLE . /Set-DatabaseOwnerToSA.ps1 WS12SQL\SQL01 #>
Вы также можете применять такие теги, как. PARAMETER для описания параметров, используемых в вашем коде,. INPUTS для описания типов объектов, которые могут быть переданы в ваш код по конвейеру, или. OUTPUTS для описания объектов, передаваемых на конвейер,. NOTES для передачи дополнительной информации,. LINK для передачи ссылок на дополнительные источники и т.д.
Сценарий PowerShell get-Help Set-Database
Включая подобного рода справочные данные в сценарии или функции, вы облегчите для тех, кто будет запускать их в дальнейшем, понимание того, какую задачу выполняет ваш код и как его следует использовать. Я обнаружил, что и мне самому эти данные помогают вспомнить, как пользоваться сценариями, которые я написал некоторое время назад.