about_Functions_Advanced
Краткое описание
Предоставляет расширенные функции, которые позволяют создавать командлеты с помощью скриптов.
Подробное описание
Командлет — это одна команда, которая участвует в семантике конвейера PowerShell. Сюда входят двоичные командлеты, расширенные функции скриптов, CDXML и рабочие процессы.
Дополнительные функции используют CmdletBinding атрибут, чтобы обозначить их как функции, которые действуют как командлеты. CmdletBinding Атрибут аналогичен атрибуту командлета, который используется в скомпилированных классах командлетов для задания класса в качестве командлета. Дополнительные сведения об этом атрибуте см. в разделе about_Functions_CmdletBindingAttribute.
В следующем примере показана функция, которая принимает имя, а затем выводит приветствие с использованием заданного имени. Также обратите внимание, что эта функция определяет имя, которое включает пару глагол (Send) и существительное (приветствие), например пару глагол-существительное скомпилированного командлета. Однако функции не обязательно должны иметь имя существительное.
Параметры функции объявляются с помощью атрибута Parameter. Этот атрибут можно использовать отдельно или в сочетании с атрибутом Alias или с несколькими другими атрибутами проверки параметров. Дополнительные сведения об объявлении параметров (включая динамические параметры, добавляемые во время выполнения) см. в разделе about_Functions_Advanced_Parameters.
Дополнительные функции отличаются от скомпилированных командлетов следующими способами.
about_Functions_CmdletBindingAttribute
Short description
Describes the attribute that makes a function work like a compiled cmdlet.
Long description
The CmdletBinding attribute is an attribute of functions that makes them operate like compiled cmdlets written in C#. It provides access to the features of cmdlets.
In functions that have the CmdletBinding attribute, unknown parameters and positional arguments that have no matching positional parameters cause parameter binding to fail.
Compiled cmdlets use the required Cmdlet attribute, which is similar to the CmdletBinding attribute that is described in this topic.
Syntax
The following example shows the format of a function that specifies all the optional arguments of the CmdletBinding attribute. A brief description of each argument follows this example.
ConfirmImpact
For more information about confirmation requests, see Requesting Confirmation.
DefaultParameterSetName
The DefaultParameterSetName argument specifies the name of the parameter set that PowerShell will attempt to use when it cannot determine which parameter set to use. You can avoid this issue by making the unique parameter of each parameter set a mandatory parameter.
HelpURI
The HelpURI argument specifies the internet address of the online version of the help topic that describes the function. The value of the HelpURI argument must begin with «http» or «https».
The HelpURI argument value is used for the value of the HelpURI property of the CommandInfo object that Get-Command returns for the function.
The Get-Help cmdlet uses the value of the HelpURI property to locate the online version of the function help topic when the Online parameter of Get-Help is specified in a command.
SupportsPaging
The SupportsPaging argument adds the First, Skip, and IncludeTotalCount parameters to the function. These parameters allow users to select output from a very large result set. This argument is designed for cmdlets and functions that return data from large data stores that support data selection, such as an SQL database.
This argument was introduced in Windows PowerShell 3.0.
PowerShell includes NewTotalCount, a helper method that gets the total count value to return and includes an estimate of the accuracy of the total count value.
The following sample function shows how to add support for the paging parameters to an advanced function.
SupportsShouldProcess
The SupportsShouldProcess argument adds Confirm and WhatIf parameters to the function. The Confirm parameter prompts the user before it runs the command on each object in the pipeline. The WhatIf parameter lists the changes that the command would make, instead of running the command.
PositionalBinding
The PositionalBinding argument is introduced in Windows PowerShell 3.0.
When parameters are positional, the parameter name is optional. PowerShell associates unnamed parameter values with the function parameters according to the order or position of the unnamed parameter values in the function command.
When parameters are not positional (they are «named»), the parameter name (or an abbreviation or alias of the name) is required in the command.
The Position argument of the Parameter attribute takes precedence over the PositionalBinding default value. You can use the Position argument to specify a position value for a parameter. For more information about the Position argument, see about_Functions_Advanced_Parameters.
Notes
The SupportsTransactions argument is not supported in advanced functions.
about_Functions_CmdletBindingAttribute
Краткое описание
Описывает атрибут, который делает функцию функционировать как скомпилированный командлет.
Подробное описание
CmdletBinding Атрибут является атрибутом функций, которые делают их работать как скомпилированные командлеты, написанные на языке C#. Он предоставляет доступ к функциям командлетов.
В функциях, имеющих CmdletBinding атрибут, неизвестные параметры и аргументы, которые не имеют соответствующих параметров позиционирования, приводят к сбою привязки параметра.
Скомпилированные командлеты используют Cmdlet атрибут Required, который аналогичен CmdletBinding атрибуту, описанному в этом разделе.
Синтаксис
В следующем примере показан формат функции, указывающей все необязательные аргументы CmdletBinding атрибута. Ниже приведено краткое описание каждого аргумента.
ConfirmImpact
Дополнительные сведения о запросах на подтверждение см. в разделе запрос подтверждения.
DefaultParameterSetName
Аргумент дефаултпараметерсетнаме указывает имя набора параметров, который PowerShell будет пытаться использовать, если не сможет определить, какой набор параметров использовать. Эту ошибку можно избежать, сделав уникальный параметр для каждого параметра, устанавливая обязательный параметр.
HelpURI
Аргумент HelpURI указывает Интернет-адрес интерактивной версии раздела справки, описывающего функцию. Значение аргумента HelpURI должно начинаться с «http» или «HTTPS».
суппортспагинг
этот аргумент появился в Windows PowerShell 3,0.
PowerShell включает невтоталкаунт— вспомогательный метод, который получает значение общего числа для возврата и включает оценку точности значения общего числа.
В следующем примере функции показано, как добавить поддержку параметров разбиения по страницам в расширенную функцию.
SupportsShouldProcess
PositionalBinding
аргумент поситионалбиндинг вводится в Windows PowerShell 3,0.
Если параметры являются позиционированными, имя параметра является необязательным. PowerShell связывает безымянные значения параметров с параметрами функции в соответствии с порядком или позицией неименованных значений параметров в команде Function.
Если параметры не являются позиционированными (они называются «именованными»), в команде требуется имя параметра (или аббревиатура или псевдоним имени).
Примечания
Аргумент SupportsTransactions не поддерживается в расширенных функциях.
Что такое Windows PowerShell и с чем его едят? Часть 3: передача параметров в скрипты и функции, создание командлетов
Во второй части цикла рассматривались основы языка программирования PowerShell, а сейчас стоит разобраться с использованием написанного на нем кода для задач администрирования. Самый очевидный способ это сделать — запустить сценарий. Кроме него существует возможность создания собственных командлетов.
Оглавление:
Позиционные параметры
Блок Param()
Дополнительные атрибуты параметров
Передача параметров через конвейер
Структура тела функции
Атрибут [CmdletBinding()] и расширенные функции
Модули сценариев и создание командлетов
Позиционные параметры
В функциях позиционные параметры используются аналогично:
Print-Args «Ноль» «Один»
Описанный выше способ позволяет передать в сценарий или функцию любое количество параметров, но при вызове необходимо соблюдать порядок их следования, а обращаться к ним можно только по индексу массива — это не всегда удобно.
Блок Param()
В сценариях и функциях намного удобнее использовать именованные параметры. В предыдущей статье мы рассказывали об одном способе их описания:
Корпорация Microsoft рекомендует использовать блок Param() — этот синтаксис более универсален и позволяет задавать не только аргументы функций, но и параметры сценариев:
В теле функции это выглядит так:
Если список аргументов функции невелик, блок Param() только загромоздит конструкцию, но во многих случаях он делает код более читаемым и является помимо прочего элементом хорошего стиля программирования.
Дополнительные атрибуты параметров
При описании аргументов функции или параметров скрипта можно задать их дополнительные атрибуты. Самый простой пример — принудительная установка типа:
Помимо приведения типов можно использовать атрибут [parameter()]:
С его помощью нетрудно сделать параметр обязательным. Обратите внимание на одновременное использование нескольких атрибутов — в этом случае они идут друг за другом:
Position позволяет указать порядок следования параметра (по умолчанию он соответствует порядку объявления):
У атрибута [Parameter()] есть и другие аргументы, полный список которых доступен на сайте Microsoft. Там же описаны прочие атрибуты, с помощью которых можно провести валидацию переданных значений, проверить их с использованием регулярных выражений и т.д. Перечислим некоторые:
[Alias()] устанавливает псевдоним для параметра:
Оператор приведения типов [string[]] означает, что значение параметра — строковый массив.
[AllowEmptyString()] разрешает пустую строку в качестве обязательного параметра:
[AllowEmptyCollection()] разрешает пустой массив в качестве обязательного параметра:
[ValidatePattern()] проверка с использованием регулярного выражения:
[ValidateLength()] проверяет длину строкового параметра:
Передача параметров через конвейер
В первой статье цикла мы рассказывали о возможности передачи данных в командлеты через конвейер (pipeline). В PowerShell командлеты и функции возвращают объекты или массивы объектов (результаты стейтментов), а также получают их на входе. По сути конвейер сам является объектом, для работы с которым программисту придется приложить определенные усилия. Чтобы это увидеть, препарируем один из командлетов при помощи Get-Help:
ValueFromPipelineByPropertyName обычно используют при необходимости передать несколько параметров, чтобы не возникало путаницы, при этом аргумент можно применять одновременно с ValueFromPipeline:
Как видите, получать параметры через конвейер могут и скрипты, но все же практическое применение описанных выше атрибутов характерно скорее для расширенных функций, которые будут рассмотрены ниже.
Структура тела функции
В языке PowerShell функция может включать три необязательных блока заключенного в операторные скобки кода — Begin, Process и End. Выглядит она примерно так:
Атрибут [CmdletBinding()] и расширенные функции
Параметр -Force применяется для подавления запросов на проведение различных операций;
-WhatIf нужен для эмуляции запуска и отображения информации о последствиях выполнения функции (команды) без этого параметра. Обычно используется, если функция может выполнить деструктивные действия.
-Confirm требует подтверждения и также используется, если функция может выполнить деструктивные действия.
Low — функция незначительно воздействует на систему и не создает существенных рисков потери данных.
Medium — среднее воздействие с незначительным риском потери данных в результате деструктивных действий.
High — код создает высокий риск потери данных в результате деструктивных действий.
Модули сценариев и создание командлетов
Стандартный набор выглядит примерно так:
C:\Users\%UserName%\Documents\WindowsPowerShell\Modules
C:\Program Files\WindowsPowerShell\Modules
C:\Windows\System32\WindowsPowerShell\v1.0\Modules
В этой статье мы достаточно подробно разобрали передачу параметров в функции и скрипты. Следующая часть цикла будет посвящена объектно-ориентированному программированию.
Часть 1: основные возможности Windows PowerShell
Часть 2: введение в язык программирования Windows PowerShell
Используем параметры в функциях Powershell с param и Parameter
При создании функции Powershell мы можем передать в нее разные параметры использую атрибут Parameters() и блок param(). Эти параметры могут быть использованы при работе в конвейере, валидации типов данных, определении обязательности их использования, значений по умолчанию и многого другого. В этой статье мы разберем как использовать Powershell Parameters() и param() на примерах.
Навигация по посту
Где и как использовать param и Parameters
Ситуация меняется, например, когда вам нужно пинговать разные хосты. Самым плохим вариантом будет дублирование предыдущего кода:
Для соблюдения принципа DRY есть несколько вариантов.
Переменная args
В Powershell, так же как и во многих других языках, существует переменная ‘args’. Смысл в этой переменной хранить все переданные значения в коллекции (так же называются списки, листы или просто массив).
Эта переменная создается автоматически при вызове команды:
Что бы получать доступ к каждому значение мы должны обращаться к нему по индексу:
Одна из проблем, которая появляется при использовании ‘$args’, неочевидность использования. Спустя время вы, или другой человек, можете не вспомнить про порядок передаваемых значений, их типы данных и т.д. Нужно будет открывать код и читать его что бы разобраться в этом.
Именованные параметры
Использование ключей выглядит так:
Вряд ли у вас возникнут сомнения в том, что должно находится в параметре «ComputerName» или «Hops». Это нельзя гарантировать при использовании «$args».
Что бы реализовать параметры в вашей функции существует 2 подхода.
Первый способ похож на реализацию параметров в большинстве языков, мы просто помещаем их в круглые скобки:
Второй способ реализуется через блок param() в котором мы объявляем параметры:
Блок ‘param’ более предпочтительный способ. Он принят сообществом как стандарт передачи параметров. Кроме этого он позволяет использовать расширенный функционал.
Расширенные функции с CmdletBinding и Parameter
В Powershell есть понятие расширенных функций. Эти функции создаются при наличии одного или двух атрибутов: ‘CmdletBinding ‘ и ‘Parameter’. Благодаря им у вашей команды автоматически появляется следующий список ключей (указан ключ и алиас):
Атрибут ‘Parameter’ используется внутри ‘param’. Он используется для проверки (валидации) определенных параметров. Эти проверки могут быть разными: может ли ключ принимать данные с конвейера, какова его максимальна длина, является ли он обязательным и т.д. Блок ‘Parameter’ можно дублировать.
Пример использования (только для демонстрации синтаксиса):
Так как я сам легко путаюсь в понятии параметр, аргумент и атрибут, ниже скриншот с небольшим объяснением:
Использование param в файлах
Эта статья рассматривает использования ‘param()’ в функциях т.к. это наиболее популярный способ использования. Тем не менее вы можете поместить этот блок в файл:
Далее мы можем вызвать этот файл и передать в него значения:
Если до блока ‘param()’ будет какой-то код (кроме комментариев), произойдет ошибка:
Обязательные Mandatory аргументы
Работая с другими командами Powershell вы замечали, что какие-то параметры являются обязательными к заполнению, а какие-то нет. По умолчанию все параметры опциональны. Что бы сделать их обязательными к заполнению используется аргумент ‘Mandatory’. Обязательность использования параметра указывается в ‘Parameter()’:
Если вы не используете параметр явно, то он у вас будет запрошен. Это правило, в случае выше, касается только одного параметра так как он является обязательным.
Обратите внимание, что объявление ‘Mandatory’ не снимает с вас обязанности проверки на корректность переданных данных. Это дает лишь возможность остановить работу функции еще на первоначальном этапе.
Проверка типов и значение по умолчанию
Эта проверка выполняется до объявления переменной.
У некоторых типов вы можете добавить скобки ‘[]’. Такой прием говорит, что вы ожидаете получить массив определенных типов. В случае строк ‘[string]’ массив строк будет выглядеть ‘[string[]]’ (ниже пример на числах):
Объявить значение по умолчанию мы можем только у аргумента, который не является ‘Mandatory’. Это делается следующим образом:
switch
Аналогичным образом мы можем объявить переменную типа switch. Если параметр будет указан, то такая переменна будет иметь значение ‘True’:
Такой подход уменьшает риск ошибок и сокращает время на написание команды. Использование switch похоже на bool, но у них есть разница. В случае ‘[bool]’ нужно будет указывать значение параметра.
Разделение параметров на группы с ParameterSetName
В ситуациях, когда в функцию нужно передать разный набор обязательных параметров, мы можем использовать атрибут ParameterSetName. Для примера можно посмотреть на описание синтаксиса команды ‘Get-EventLog’:
У нас выводится 2 возможных варианта использования команды. Для каждого из варианта использования команды могут быть определены свои индивидуальные ключи. Именно для этого используется ParameterSetName.
Создадим команду с 2-умя группами. Первая группа ‘Group1’ работает с именами пользователей, а ‘Group2’ только с идентификаторами и требует дополнительно параметра:
Группу, которую вы планируете использовать по умолчанию, можно определить в ‘CmdletBinding’ используя атрибут ‘DefaultParameterSetName’:
Один ключ может находится в нескольких группах. Для этого, группу, нужно указать в разных ‘Parameter()’. Каждый аргумент, указанный в Parameter, будет действовать для определенной группы. Так, в случае ниже, в одной группе «$Message» является обязательным, а в другой опциональным параметром:
Позиционные параметры с Position
При создании команды каждый параметр имеет свою позицию. Эти позиции соответствуют порядку их объявления внутри функции:
Такой подход часто используется в обычных командах Powershell. Параметры типа ‘Name’ или ‘ComputerName’ могут работать позиционно, а остальные нет.
Параметры конвейера
Для использования конвейера можно определить несколько аргументов:
Создадим функцию, которая будет принимать оба параметра:
Единственный момент, который не оговорен в той статье, ‘ValueFromPipeline’ можно использовать несколько раз, но в определенном случае. Если у вы используете группировку (разделяете параметры на группы) и указываете один из параметров явно:
Включаем значения вне параметров с ValueFromRemainingArguments
У вас может быть ситуация, когда вы не можете предусмотреть параметр для конкретного значения. Это так же может быть проблема с ограничением Powershell на 32 параметра. В этом случае вы можете использовать ‘ValueFromRemainingArguments’, который включает все значения не привязанных к каким-то параметрам.
Атрибут ‘ValueFromRemainingArguments’ объявляется следующим образом:
Обратите внимание, что порядок в этом случае не важен.
Атрибуты валидации параметров
Значения у параметров могут проходить разные проверки. Для этих проверок существуют разные атрибуты:
Рассмотрим некоторые из этих атрибутов.
Ошибки при этом могут быть разными:
‘AllowNull()’ работает для типов ‘[array]’ и других типов данных, кроме строк и коллекций. Для них нужно использовать ‘[AllowEmptyString()]’ и ‘[AllowEmptyCollection()]’.
Перед указанием таких атрибутов стоит проверить во что будет преобразован ваш тип данных, например:
Подсчет значений
Проверка по скрипту
Вы можете создать свою проверку параметров с помощью «ValidateScript». Так вы создадите параметр, который запретит указывать прошедшие даты:
Ошибка происходит из-за того, что команда отправляет данные, допустим в 11.1 секунд, а валидация в 11.2. Во втором примере мы добавляем 1 секунду что бы ошибки не было.
Вместо «$PSItem» можно использовать «$_».
Проверка по шаблонам регулярных выражений
Мы можем привязать к параметру проверку на простые регулярные выражения (SupportsWildcards) и расширенные (ValidatePattern). Так мы убедимся, что в параметр передают валидный IP адрес:
Ограничение выбора значений с ValidateSet
В некоторых командах есть возможность выбора значений у параметров. Такой выбор осуществляется через кнопку ‘tab’. Вы можете проверить это нажав ‘tab’ в следующей команде:
У вас будет выполняться переключение между значениями: Continue, Ignore, Inquire и т.д.
Подобный выбор задается в атрибуте ValidateSet:
Если вы укажете значение не прописанное в ‘ValidateSet’, то получите ошибку:
Передача ключей и значений в одной переменной (Splatting)
Обычный вызов команды выглядит следующим образом:
Мы можем взять все ключи и значения из этой команды, поместить в hashtable и передать в команду как набор параметров:
Что бы Powershell понял, что мы передаем не одну переменную, а набор ключей и значений, мы должны ее пометить знаком ‘@’:
Такой подход называется ‘Splatting’ (брызги) и немного повышает читаемость кода.
Если в hashtable будет находиться дополнительный параметр, который не реализован в команде, то выйдет ошибка:
Обычные массивы так тоже можно передавать, но вы должны знать позиции под которыми должны располагаться значения:
Используя splatting, в Powershell 7+, вы можете перезаписывать значения из метода splatting:
Алиасы
К параметрам можно привязать алиасы (короткие имена/псевдонимы). Это делается через атрибут ‘Alias()’. Ограничений в количестве атрибутов нет:
