| Новые программы oszone.net |  |
RTFM — один из самых популярных акронимов в англоязычном ИТ-сообществе. Разными людьми он расшифровывается по-разному, но самая общепринятая расшифровка — «Read the Fabulous Manual», то есть «Читай замечательную документацию ». Обычно эту формулировку используют в ответ на вопрос, на который можно было бы ответить быстрее и полнее, если бы вопрошающий перед этим просто почитал документацию к продукту. Однако при работе с Windows PowerShell вам приходится самому создавать сценарии и функции, которым будут пользоваться другие. Не забываете ли вы предоставлять подробные инструкции по использованию своих сценариев? Иначе говоря, создаете ли вы ту самую «замечательную документацию»? «Без комментариев» — ответ неправильныйИмеющие опыт программирования или создания сценариев знакомы с комментариями, размещаемыми в исходном коде и информирующими о том, что делает тот или иной код. В Windows PowerShell есть стандартный механизм поддержки комментариев: оболочка игнорирует строки, начинающиеся с #, — в таких строках обычно и размещаются комментарии. К сожалению, чтобы увидеть эти комментарии, придется открыть сценарий в Блокноте Windows или любом другом текстовом редакторе, и это сильно отличается от поведения командлета, использующего встроенную систему справки в оболочке PowerShell. Одна из фундаментальных концепций Windows PowerShell — необходимость освоить единственный набор навыков и поведения для выполнения какой-то определенной задачи: если пользователи уже научились использовать для получения справки команду Get-Help, зачем усложнять вещи и требовать иного поведения в сценариях или функциях? В версии 2 оболочки PowerSh2ell поведение не должно меняться. В Windows PowerShell v2 введена новая форма документации, получившая название справки на основе комментариев. По существу это означает, что оболочка «знает», где искать особым образом отформатированные комментарии в сценарии или функции, анализирует такие комментарии и создает на их основе справку, которую мы привыкли использоваться при работе с командлетам. Справка командлетов по сути представляет собой информацию в формате XML; справку на основе комментариев не только проще создавать вручную, но она неотделима от сценария или функции, к которой относится, что делает сценарии или функции самодостаточными и упрощает их распространение. Давайте попытаемся создать сценарий или функцию, способную отображать свою справку средствами встроенной команды Get-Help, форматируя такую справку точно так же, как это делается в обычном командлете (рис.
Рис. Стандартная справка командлета в Windows PowerShell Хочешь писать документацию? Читай документацию!Windows PowerShell содержит полную встроенную справку по созданию справки, основанной на комментариях, — надо только выполнить команду help about_comment_based_help. В целом, правила создания справки на основе комментариев просты:
Разрешаются однострочные комментарии, в которых каждая строка начинается с #, или целые блоки комментариев. С последними работать проще, так как не приходится в начале каждой строки ставить символ #. Начало блока комментария отмечается последовательностью <#, а заканчивается последовательностью #>. Начало и конец блока должны располагаться на отдельных строках, не содержащих никакого другого кода. Весь текст, заключенный между этими строками, считается комментарием. Справку будем создавать как ряд блоков. Каждый блок начинается с ключевого слова раздела, например .SYNOPSIS или .DESCRIPTION. Перед ключевым словом ставится точка, причем это должен быть первый символ в строке, исключение делается только для пробела и символа #. В файле about_comment_based_help указаны все возможные ключевые слова, но мы перечислим лишь основные:
Каждое ключевое слово размещается на отдельной строке, за которой следует одна или несколько строк текста. Вот пример: <#.SYNOPSISRetrieves service pack and operating system information from one or more remote computers..DESCRIPTIONThe Get-Inventory function uses Windows Management Instrumentation (WMI) toretrieve service pack version, operating system build number, and BIOS serial number from one or more remote computers. Computer names or IP addresses are expected as pipeline input, or may bepassed to the –computerName parameter. Each computer is contacted sequentially, not in parallel..PARAMETER computerNameAccepts a single computer name or an array of computer names. You mayalso provide IP addresses..PARAMETER pathThe path and file name of a text file. Any computers that cannot be reached will be logged to this file. This is an optional parameter; if it is notincluded, no log file will be generated..EXAMPLERead computer names from Active Directory and retrieve their inventory information.Get-ADComputer –filter * | Select{Name="computerName";Expression={$_.Name}} | Get-Inventory.EXAMPLERead computer names from a file (one name per line) and retrieve their inventory informationGet-Content c:\names.txt | Get-Inventory.NOTESYou need to run this function as a member of the Domain Admins group; doing so is the only way to ensure you have permission to query WMI from the remote computers.#>На рис. 2 показано, что это выглядит в реальной функции.
Рис. Результат выполнения команды Help в функции Команда Help следует обычным правилами отображения различных частей справки. Например, вы увидите только раздел .EXAMPLE, если используете параметр –example, а параметр –full позволит увидеть все разделы. Но в любом случае вы увидите (см. рис. 3), что справка этой функции выглядит так же, как и у любого обычного командлета.
Рис. Справка функции, выглядящая как стандартная справка командлета Рекомендации по созданию справки, основанной на комментарияхЯ предпочитаю в каждый создаваемый сценарий или функцию включать как минимум разделы .SYNOPSIS и .DESCRIPTION. Если в сценарии или функции используется один или несколько параметров, я документирую их в разделе .PARAMETER. Таким образом, если кому-то понадобится воспользоваться сценарием или функцией, он легко сможет узнать, что она делает и как ее применять. И вообще — через полгодика я сам забуду, что написал, и справка на основе комментариев окажется мне самому как нельзя кстати. Чем сильнее структурирован и предназначен для повторного использования ваш код, тем детальнее должна быть справка. Например, я структурировал свою функцию-пример Get-Inventory как «расширенную функцию», что означает, что она в целом выглядит и работает как стандартный командлет. Это самая сложная форма жизни в мире PowerShell, поэтому я должен предоставить справку такого же уровня детализации, как из в «настоящем» командлете — примеры, примечания, перекрестные ссылки, входные и выходные параметры и другое. Все чаще разработчики сторонних утилит полагаются на справку. Например, созданные сторонними разработчиками интегрированные среды разработки сценариев часто анализируют справку, создавая на ее основе похожие на IntelliSense механизмы подсказок при создании кода и функции автозавершения. Предоставление должным образом отформатированной и полной справки на основе комментария сильно облегчает использование ваших сценариев и функций в сторонних инструментальных средствах. Ну и, наконец, это просто круто — создавать сценарии и функции, которые один в один похожи «на реальные» командлеты, включая изящный механизм отображения справки. Материалы на подобные темы
Теги:
Windows PowerShell.
Комментарии посетителей
Комментарии отключены. С вопросами по статьям обращайтесь в форум.
|
|
.png)
.png)
.png)
