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

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

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

Пример 1. Comment-Based справки по функции

Следующий пример функции включает в себя справку на основе комментариев.

В следующем выводе показаны результаты Get-Help команды, которая отображает справку для Add-Extension функции.

Пример 2. Comment-Based справки по сценарию

Следующий пример функции включает в себя справку на основе комментариев.

Обратите внимание на пустые строки между закрывающим #> и Param оператором. В скрипте, не имеющем Param оператора, в разделе справки и первом объявлении функции должно быть по крайней мере две пустые строки между последним комментарием. Без этих пустых строк Get-Help связывает раздел справки с функцией, а не со сценарием.

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

Пример 3. описания параметров в операторе param

В этом примере показано, как вставлять описания параметров в Param операторе функции или скрипта. Этот формат наиболее удобен, если описания параметров являются краткими.

Пример 4. перенаправление в XML-файл

Пример 5. перенаправление на другой раздел справки

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

Источник

about_Comment_Based_Help

Краткое описание

Описание процесса написания разделов справки на основе комментариев для функций и скриптов.

Подробное описание

Разделы справки на основе комментариев можно писать для функций и скриптов с помощью специальных ключевых слов комментария справки.

В этом разделе объясняется, как создавать разделы справки для функций и скриптов. Сведения о том, как отображать разделы справки для функций и скриптов, см. в разделе Get-Help.

Командлеты Update-Help и Save-Help работают только с файлами XML. Обновляемая Справка не поддерживает разделы справки на основе комментариев.

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

Синтаксис для справки на основе комментариев выглядит следующим образом:

или диспетчер конфигурации служб

Справка на основе комментариев записывается в виде набора комментариев. Символ комментария можно ввести # перед каждой строкой комментариев или использовать #> символы и для создания блока комментариев. Все строки внутри блока комментариев обрабатываются как комментарии.

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

Синтаксис для справки на основе комментариев в функциях

Справка на основе комментариев для функции может находиться в одном из трех расположений:

или диспетчер конфигурации служб

Синтаксис для справки на основе комментариев в скриптах

Справка на основе комментариев для сценария может находиться в одном из двух расположений в скрипте.

В начале файла скрипта. Справка по скрипту может предшествоваться в сценарии только по комментариям и пустым строкам.

Если первый элемент в теле скрипта (после справки) является объявлением функции, то между концом справки скрипта и объявлением функции должно быть по крайней мере две пустые строки. В противном случае Справка интерпретируется как Справка по функции, а не справку по сценарию.

В конце файла скрипта. Однако если сценарий подписан, поместите справку на основе комментариев в начало файла скрипта. Конец скрипта занят блоком сигнатур.

или диспетчер конфигурации служб

Синтаксис для справки на основе комментариев в модулях скриптов

Ключевые слова справки на основе комментариев

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

. Краткий обзор

Краткое описание функции или скрипта. Это ключевое слово может использоваться только один раз в каждом разделе.

. NОПИСАНИЕ

Подробное описание функции или скрипта. Это ключевое слово может использоваться только один раз в каждом разделе.

. ПАРАМЕТР

Ключевые слова параметров могут использоваться в любом порядке в блоке комментариев, но синтаксис функции или скрипта определяет порядок, в котором параметры (и их описания) отображаются в разделе справки. Чтобы изменить порядок, измените синтаксис.

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

. Например

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

. ВХОДА

. ВЫХОДНЫЕ

. Заметки О

Дополнительные сведения о функции или скрипте.

. ССЫЛКУ

Имя связанного раздела. Значение отображается в строке под запятыми. LINK «и должен предшествовать символом комментария # или включаться в блок комментариев.

Это содержимое отображается в разделе «связанные ссылки» раздела справки.

. ВОЗМОЖНОСТИ

. форвардхелптаржетнаме

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

. форвардхелпкатегори

. ремотехелпрунспаце

. екстерналхелп

Указывает файл справки на основе XML для скрипта или функции.

.ExternalHelp Ключевое слово требуется при документировании функции или скрипта в XML-файлах. Без этого ключевого слова Get-Help не удается найти файл справки на основе XML для функции или скрипта.

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

Дополнительные сведения о формате файла справки на основе XML см. в статье Создание справки по командлетам.

Автоматически созданное содержимое

Раздел имени раздела справки по функции берется из имени функции в синтаксисе функции. Имя раздела справки по скрипту берется из имени файла скрипта. Чтобы изменить имя или его регистр букв, измените синтаксис функции или имя файла скрипта.

Синтаксис

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

Общие параметры

Общие параметры добавляются к синтаксису и списку параметров раздела справки, даже если они не оказывают никакого влияния. Дополнительные сведения об общих параметрах см. в разделе about_CommonParameters.

Таблица атрибутов параметра

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

Remarks

Раздел «Примечания » раздела справки автоматически создается на основе имени функции или скрипта. Нельзя изменить или повлиять на его содержимое.

Примеры

Справка на основе комментариев для функции

Следующий пример функции включает в себя справку на основе комментариев:

Будут получены следующие результаты.

Описания параметров в синтаксисе функции

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

Справка на основе комментариев для сценария

Следующий пример скрипта включает в себя справку на основе комментариев. Обратите внимание на пустые строки между закрывающим #> и Param оператором. В скрипте, не имеющем Param оператора, в разделе справки и первом объявлении функции должно быть по крайней мере две пустые строки между последним комментарием. Без этих пустых строк Get-Help связывает раздел справки с функцией, а не со сценарием.

Перенаправление в XML-файл

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

Перенаправление на другой раздел справки

Эта функция используется в следующей команде:

Источник

A. Comment-Based Help

PowerShell provides a mechanism for programmers to document their scripts using special comment directives. Comments using such syntax are called help comments. The cmdlet Get-Help generates documentation from these directives.

A.1 Introduction

All of the lines in a help topic must be contiguous. If a help topic follows a comment that is not part of that topic, there must be at least one blank line between the two.

The directives can appear in any order, and some of the directives may appear multiple times.

Directive names are not case-sensitive.

When documenting a function, help topics may appear in one of three locations:

When documenting a script file, help topics may appear in one of two locations:

A.2 Help directives

This directive allows an example of command usage to be shown.

If this directive occurs multiple times, each associated help content block is displayed as a separate example.

This directive specifies the path to an XML-based help file for the script or function.

Although comment-based help is easier to implement, XML-based Help is required if more precise control is needed over help content or if help topics are to be translated into multiple languages. The details of XML-based help are not defined by this specification.

Specifies the help category of the item in ForwardHelpTargetName (§A.2.5). Valid values are Alias, All, Cmdlet, ExternalScript, FAQ, Filter, Function, General, Glossary, HelpFile, Provider, and ScriptCommand. Use this directive to avoid conflicts when there are commands with the same name.

The command Get-Help help is treated as if it were Get-Help Get-Help instead.

The pipeline can be used to pipe one or more objects to a script or function. This directive is used to describe such objects and their types.

If this directive occurs multiple times, each associated help content block is collected in the one documentation entry, in the directives’ lexical order.

This directive specifies the name of a related topic.

If this directive occurs multiple times, each associated help content block is collected in the one documentation entry, in the directives’ lexical order.

The Link directive content can also include a URI to an online version of the same help topic. The online version is opens when Get-Help is invoked with the Online parameter. The URI must begin with «http» or «https».

This directive allows additional information about the function or script to be provided. This directive can be used only once in each topic.

This directive is used to describe the objects output by a command.

If this directive occurs multiple times, each associated help content block is collected in the one documentation entry, in the directives’ lexical order.

This directive allows for a detailed description of the given parameter. This directive can be used once for each parameter. Parameter directives can appear in any order in the comment block; however, the order in which their corresponding parameters are actually defined in the source determines the order in which the parameters and their descriptions appear in the resulting documentation.

An alternate format involves placing a parameter description comment immediately before the declaration of the corresponding parameter variable’s name. If the source contains both a parameter description comment and a Parameter directive, the description associated with the Parameter directive is used.

Источник

Jump Start в PowerShell (часть I)

Только автоматизация. Только PowerShell.

Предисловие

В качестве хобби и при наличии времени преподаю студентам в УКИТ (бывший Московский государственный колледж информационных технологий). На данный момент у меня мало времени, чтобы уделить его группе студентов, зато вполне достаточно, чтобы подготовить пост здесь, на Хабре.

Я работаю системным администратором в крупной не ИТ-компании с большой завязкой на ИТ ресурсы. По роду деятельности представляется решать большое количество однотипных задач по обслуживанию пользователей.

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

Внимание: PowerShell вызывает привыкание.

Введение

Windows PowerShell — расширяемое средство автоматизации от Microsoft, состоящее из оболочки с интерфейсом командной строки и сопутствующего языка сценариев.

Выглядеть среда PowerShell может так, как командная строка:

powershell.exe

Или в виде приложения:

powershell_ise.exe

Powershell_ise.exe называется интегрированной средой сценариев — Windows PowerShell ISE. Позволяет работать с языком в удобной среде с подсветкой синтаксиса, конструктором команд, автозаполнением команд по нажатию TAB и прочими прелестями. Идеальна для создания и тестирования сценариев.

Для запуска среды powershell.exe или powershell_ise.exe достаточно набрать аналогичное название в строке выполнить.

Файл сценария PowerShell имеет расширение .ps1.

Сценарий не получится запустить двойным ЛКМ. Это сделано специально для того, чтобы не нанести вред системе случайно запущенным скриптом.

Для запуска, по клику ПКМ следует выбрать «Выполнить с помощью PowerShell»:

Помимо того, что существует ограничение по запуску сценариев ЛКМ, по умолчанию выполнение сценариев в системе запрещено, опять же, по описанной выше причине — не нанести вред системе. Для проверки текущей политики выполнения выполним команду:

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

Для выполнения и тестирования понизим политику до RemoteSigned выполнив команду:

Приступаем к работе

Командлет

Например, для получения текущих процессов, мы выполним команду:

И получим результат:

Попробуйте самостоятельно выполнить:

Не обязательно знать наизусть все командлеты. Get-Help спасёт ситуацию.
Информацию о всех доступных командлетах можно получить, введя следующую команду:

Если мы используем PowerShell ISE, мы облегчаем процесс разработки.
Достаточно ввести знак тире «—» после того, как ввели командлет, и мы получим все возможные варианты параметров и их типы:

Если, всё же, мы забудем какие свойства есть у того или иного командлета, прогоним его через Get-Member:

Недостаточно информации? Обратимся к справке с параметром -Examples:

Получаем описание Get-Process, да ещё и с примерами использования:

Что аналогично записи:

А теперь остановим процесс:

Немногим ранее мы сказали, что командлеты именуются по правилу Глагол-Существительное. Уточню, что глагол не обязательно должен быть Get. Помимо того, что мы можем получать, мы можем задавать Set (помните, Set-ExecutionPolicy), запускать Start, останавливать Stop, выводить Out, создавать New и многие другие. Название командлета ни чем не ограничивается и, когда мы будем с вами создавать свой собственный, сможем назвать его так, как душе угодно.

Попробуем выполнить вывод в файл:

Кстати, аналогично можно записать так:

Комментарии

Мы все знаем, использовать комментарии является хорошим тоном.

Комментарии в PowerShell бывают строчные — # и блочные — :

Обратим внимание, на код из примера:

Для тех, кто знаком с WMI, кто делает это на старом добром VBScript, помните, сколько кода надо написать?

Конвейер

Конвейер (|) — передаёт выходные данные одной команды во входные данные на обработку другой команде. Мы использовали конвейер ранее, получая все свойства объекта или, в предыдущем примере, выбирая из набора данных только поле Caption.

Чтобы понять принцип конвейера, давайте выполним код:

Что произойдёт: получаем все службы (Get-Service), передаём все полученные службы на сортировку в командлет Sort-Object и указываем, что хотим отсортировать их по параметру Status. На выводе мы получим сначала все службы со статусом Stop, а потом все службы со статусом Running.

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

В примере мы используем $_. Данная запись означает текущий элемент в конвейере.

Послесловие

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

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

Источник

Powershell скрипты

Доброго времени суток дорогие читатели. В данной статье мы познакомимся с основами Powershell. Данный язык программирования используется во всех ОС Microsoft начиная с Windows XP SP3. Писать Powershell скрипты должен уметь каждый уважающий себя системный администратор windows.

Все команды в Powershell как правило используются в форме командлетов. Все командлеты это специализированные классы .NET Framework и .NET Core (используется в PowerShell Core 6 и выше).

Запуск Powershell

На примере Windows 10 Powershell можно запустить просто нажав правой кнопкой мыши на меню пуск.

Также нижняя строчка позволяет запустить Powershell с повышенными правами администратора.

Еще можно воспользоваться поиском в WIndows 10 и ввести название powershell

Как видно на картинке выше нашелся не только Powershell но и Powershell ISE. Консоль powershell удобна если требуется запустить последовательно не больше одной команды. Либо несколько команд в конвейере. Однако в случае написания полноценных скриптов лучше использовать Powershell ISE. Это бесплатная среда разработки сценариев на языке Powershell поставляется вместе с ОС Windows.

Сразу после запуска консоли рекомендую запустить командлет Get-Help – встроенная справка по всем командлетам, аналог man в Linux.

Видим что консоль предлагает обновить встроенную помощь. Нажимаем Y и соглашаемся.

Командлеты

Командлеты не чувствительны к регистру. Написать Get или get не важно, powershell воспримет эти команды одинаково.

Чтобы получить список всех доступных командлетов необходимо использовать Get-Command

Для получения справки по любому командлету напишите Get-Help имя-комндлета. Например

Давайте представим что нам необходимо вывести список командлетов для управления процессами. Воспользуемся Get-Command и укажем ему параметры для более точного поиска.

И вот мы видим список командлетов позволяющих управлять процессами: Get-Process – список всех запущенных процессов, Start-Process – запустить указанный процесс, Stop-Process– остановить указанный процесс, Wait-Process – ожидать указанный процесс. Как видно из названий командлетов можно легко понять для чего каждый служит.

Используя командлет Get-Help можно получить справку по любому командлету.

Давайте выведем список процессов с именем WhatsApp

Мы вывели все процессы с именем WhatsApp и добавили в вывод дополнительный параметр -IncludeUserName, что позволило нам увидеть кем запущен процесс.

Алиасы

Алиасы в Powershell это по сути более короткие названия командлетов. Т.е. любому командлету можно присвоить свое короткое имя (alias). Например алиасом для командлета Get-Process является gps. Согласитесь куда проще и быстрее написать gps чем Get-Process.

Список всех alias можно получить используя командлет Get-Alias

Как видно из списка для alias использованы аналогичные по значению команды из Linux: ls, man, mount, md, kill и т.п. Видимо чтобы линуксоиду было по привычнее 🙂 Можно создать свой alias используя командлет New-Alias

Конвейер

Конвейер используется для передачи выходных данных командлета идущего вначале во входные данные командлета следующего за ним. Ничего непонятно? 🙂 Давайте на примерах, так всегда яснее.

Возьмем уже известный нам командлет Get-Process, посмотрим на его вывод

Как по мне многовато лишних столбцов. Мне эта информация не нужна, поэтому я выберу только нужные данные. Для таких целей служит командлет Select-Object. Давайте используем его в конвейере.

Как вы уже наверно догадались конвейер обозначается знаком | и идет сразу следом за командлетом. И так данные по конвейеру можно передавать и дальше другим командлетам. Итак я передал выходные данные (список запущенных процессов) на вход командлета Select-Object. Который в свою очередь выбрал данные по 3 столбцам ID, CPU, ProcessName. Теперь можно передать эти данные дальше. Например выгрузить в текстовый файл

Просто не правда ли? У нас конвейер из трех командлетов, на выходе которого получаем текстовый файл со списком запущенных процессов и необходимой информацией по ним.

Структура объектов

В Powershell объекты играют самую важную роль. От типа объекта зависит что именно с ним можно сделать. Узнать тип объекта и вывести список всех его элементов позволяет команда Get-Member

Вот далеко не полный список элементов командлета Get-Process. В данному случае тип данных это System.Diagnostics.Process

Давайте посмотрим тип данных у новой переменной

В данном случае тип данных System.String т.е. строка. Что вполне логично. А теперь посмотрите что можно сделать с этой строкой с учетом указанных выше параметров.

Как видно на картинке выше мы заключаем нашу тестовую переменную $new в скобки и после них пишем точку и указываем метод. В примере я использовал три метода:

Это всего лишь небольшой пример что можно сделать с параметрами объекта. Чаще используйте Get-Member и вы откроете для себя безграничные возможности манипуляции над объектами.

Скрипты Powershell

В самом начале статьи указал на встроенный инструмент Powershell ISE. Давайте запустим его и создадим свой первый скрипт. Кстати скрипты сохраняются в файлах с расширением ps1

Скрипт будет запускать блокнот, далее выполняется проверка если блокнот запущен выводится сообщение об этом и после блокнот закрывается. Если блокнот не запущен то выводится соответствующее сообщение об этом. На самом деле блокнот будет всегда запущен, т.к. мы вначале скрипта написали Start-Process notepad

В этом скрипте я использовал цикл if else. О циклах будет подробнее в следующей статье. Итак давайте сохраним скрипт и выполним его.

В ответ мы получим такую ошибку:

Все верно, изначально в WIndows запрещено выполнять скрипты Powershell. Это сделано для повышения безопасности системы. Для включения возможности запуска скриптов Powershell необходимо запустить Powershell от Администратора и ввести командлет Set-ExecutionPolicy с одним из параметров:

Если вы полностью уверены в запускаемых скриптах можете поставить Unrestricted. Давайте так и сделаем

Будет предупреждение по безопасности, соглашаемся нажав Y

Можем посмотреть текущую настройку политики безопасности при помощи командлета Get-ExecutionPolicy

В данной статье мы рассмотрели основы чтобы подготовиться писать скрипты Powershell. В следующих статьях мы более подробно изучим циклы, массивы, функции, работу со строками и много другое. Кстати вот раздел посвященный Powershell. Там много всего интересного 😉

Источник