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