РАЗДЕЛ
about_Functions_Advanced_Parameters
КРАТКОЕ ОПИСАНИЕ
Описывает, как добавлять статические и динамические параметры в функции,
в которых объявлен атрибут CmdletBinding.
ПОЛНОЕ ОПИСАНИЕ
При написании функций можно объявлять собственные параметры, а
также можно писать функции, которые могут обращаться к общим
параметрам, которые доступны скомпилированными командлетам.
Дополнительные сведения об общих параметрах Windows PowerShell
см. в разделе about_CommonParameters.
Статические параметры
В следующем примере показано объявление параметра, в котором
определяется параметр ComputerName. Этот параметр обладает следующими
характеристиками:
- он является обязательным;
- он принимает входные данные из конвейера;
- в качестве входных данных он принимает массив строк;
Param
(
[parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[String[]]
$ComputerName
)
Единственным обязательным атрибутом, который необходимо
использовать при объявлении параметра, является атрибут
Parameter. Но можно также объявить атрибут Alias и несколько
аргументов проверки. Количество атрибутов, которые можно включить в
объявление параметра, не ограничено.
Атрибут Parameter
Атрибут Parameter служит для объявления параметра функции.
У этого атрибута есть следующие именованные аргументы, которые
служат для определения характеристик параметра, например
обязательности параметра.
Именованный аргумент Mandatory
Аргумент Mandatory указывает, что при запуске функции
параметр является обязательным. Если этот аргумент не указан,
параметр является необязательным. В следующем примере показано
объявление параметра, который обязательно указывать при запуске функции.
Param
(
[parameter(Mandatory=$true)]
[String[]]
$ComputerName
)
Именованный аргумент Position
Аргумент Position задает позицию параметра. Если этот аргумент не
указан, при задании параметра необходимо в явном виде указывать имя или
псевдоним параметра. Кроме того, если ни у одного из параметров
функции нет позиции, среда выполнения Windows PowerShell назначает
позиции для каждого из параметров на основании порядка, в котором
происходит получение параметров.
В следующем примере показано объявление параметра, значение
которого должно указываться в качестве первого аргумента при
вызове командлета. Обратите внимание, что эту функцию можно
запускать как с указанием имени параметра, так и без него.
Param
(
[parameter(Position=0)]
[String[]]
$ComputerName
)
Именованный аргумент ParameterSetName
Аргумент ParameterSetName задает набор параметров, к которому
принадлежит параметр. Если набор параметров не задан, параметр
принадлежит ко всем наборам параметров, которые определены функцией.
Это означает, что в каждом наборе параметров должен быть один уникальный
параметр, который не принадлежит ни к одному из других наборов
параметров. В следующем примере показано объявление одного из двух
параметров, которые относятся к различным наборам параметров.
Param
(
[parameter(Mandatory=$true,
ParameterSetName="Computer")] [String[]]
$ComputerName
)
Param
(
[parameter(Mandatory=$true,
ParameterSetName="User")] [String[]]
$UserName
)
Дополнительные сведения о наборах параметров см. в разделе
"Наборы параметров командлетов" библиотеки MSDN по адресу
https://go.microsoft.com/fwlink/?LinkId=142183.
Именованный аргумент ValueFromPipeline
Аргумент ValueFromPipeline определяет, что параметр принимает
входные данные из объекта конвейера. Этот аргумент следует
указывать, если командлет обращается ко всему объекту, а не
только к свойству объекта. В следующем примере показано объявление
обязательного параметра ComputerName, который принимает входной
объект, которые передается функции из конвейера.
Param
(
[parameter(Mandatory=$true,
ValueFromPipeline=$true)] [String[]]
$ComputerName
)
Именованный аргумент ValueFromPipelineByPropertyName
Аргумент valueFromPipelineByPropertyName определяет, что параметр
принимает входные данные из свойства объекта конвейера. Этот атрибут
следует указывать, если выполняются следующие условия:
- параметр используется для доступа к объекту конвейера;
- имя свойства совпадает с именем параметра или псевдоним
свойства совпадает с псевдонимом параметра.
Например, если у функции есть параметр ComputerName, а у объекта
конвейера есть свойство ComputerName, значение свойства ComputerName
будет присвоено параметру ComputerName функции.
В следующем примере показано объявление параметра
ComputerName, который принимает входные данные из свойства
ComputerName входного объекта, передаваемого командлету.
Param
(
[parameter(Mandatory=$true,
ValueFromPipelineByPropertyName=$true)] [String[]]
$ComputerName
)
Именованный аргумент ValueFromRemainingArguments
Аргумент ValueFromRemainingArguments определяет, что параметр
принимает все оставшиеся аргументы, которые не привязаны к
параметрам функции. В следующем примере показано объявление
параметра ComputerName, который принимает все оставшиеся аргументы
входного объекта, передаваемого функции.
Param
(
[parameter(Mandatory=$true,
ValueFromRemainingArguments=$true)] [String[]]
$ComputerName
)
Именованный аргумент HelpMessage
Аргумент HelpMessage задает сообщение, которое содержит
краткое описание параметра. В следующем примере показано
объявление параметра, в котором определяется описание параметра.
Param
(
[parameter(Mandatory=$true,
HelpMessage="An array of computer names.")]
[String[]]
$ComputerName
)
Атрибут Alias
Атрибут Alias задает другое имя параметра. Для параметра можно
определить произвольное число псевдонимов. В следующем примере
показано объявление обязательного параметра, в котором для параметра
ComputerName определен псевдоним CN.
Param
(
[parameter(Mandatory=$true)]
[alias("CN")]
[String[]]
$ComputerName
)
Атрибуты проверки параметров
Эти атрибуты определяют, каким образом среда выполнения Windows
PowerShell проверяет аргументы расширенных функций.
Атрибут проверки AllowNull
Атрибут AllowNull позволяет устанавливать аргумент обязательного
параметра командлета равным Null. В следующем примере параметр
ComputerName может содержать значение Null, даже если параметр
является обязательным.
Param
(
[parameter(Mandatory=$true)]
[String]
[AllowNull()]
$ComputerName
)
Атрибут проверки AllowEmptyString
Атрибут AllowEmptyString позволяет задавать в качестве аргумента
обязательного параметра командлета пустую строку. В следующем примере
параметр ComputerName может содержать пустую строку (""), даже если
параметр является обязательным.
Param
(
[parameter(Mandatory=$true)]
[String]
[AllowEmptyString()]
$ComputerName
)
Атрибут проверки AllowEmptyCollection
Атрибут AllowEmptyCollection позволяет задавать в качестве
аргумента обязательного параметра командлета пустую коллекцию.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[AllowEmptyCollection()]
$ComputerName
)
Атрибут проверки ValidateCount
Атрибут ValidateCount задает минимальное и максимальное число
аргументов, которые может принимать параметр. Среда выполнения Windows
PowerShell создает ошибку, если число аргументов выходит за эти пределы.
В следующем примере у параметра ComputerName может быть от одного до
пяти аргументов.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateCount(1,5)]
$ComputerName
)
Атрибут проверки ValidateLength
Атрибут ValidateLength задает минимальную и максимальную
длину аргумента параметра. Среда выполнения Windows
PowerShell создает ошибку, если длина аргумента параметра
выходит за эти пределы.
В следующем примере задаются имена компьютеров, длина которых
должна лежать в интервале от 1 до 10 знаков.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateLength(1,10)]
$ComputerName
)
Атрибут проверки ValidatePattern
Атрибут ValidatePattern задает регулярное выражение, которое
проверяет шаблон аргумента параметра. Среда выполнения Windows
PowerShell создает ошибку, если аргумент параметра не соответствует
этому шаблону. В следующем примере аргументом параметра должно быть
четырехзначное число, каждый разряд которого может содержать число от
0 до 9.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidatePattern("[0-9][0-9][0-9][0-9]")]
$ComputerName
)
Атрибут проверки ValidateRange
Атрибут ValidateRange задает минимальное и максимальное значение
аргумента параметра. Среда выполнения Windows PowerShell создает
ошибку, если аргумент параметра выходит за эти пределы. В следующем
примере аргумент параметра не может быть меньше 0 или больше 10.
Param
(
[parameter(Mandatory=$true)]
[Int[]]
[ValidateRange(0,10)]
$Count
)
Атрибут проверки ValidateScript
Атрибут ValidateScript задает скрипт, который используется
для проверки аргумента параметра. Среда выполнения Windows
PowerShell создает ошибку, если результатом выполнения
скрипта является значение false или если скрипт создает
исключение. В следующем примере значение параметра Count
должно быть менее 4.
Param
(
[parameter()]
[Int]
[ValidateScript({$_ -lt 4})]
$Count
)
Атрибут ValidateSet
Атрибут ValidateSet задает набор допустимых значений аргумента
параметра.. Среда выполнения Windows PowerShell создает ошибку, если
аргумент параметра не совпадает ни с одним из значений в наборе.
В следующем примере аргумент параметра может содержать только
имена Steve, Mary и Carl.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateRange("Steve", "Mary", "Carl")]
$UserName
)
Атрибут проверки ValidateNotNull
Атрибут ValidateNotNull определяет, что аргумент параметра не
может иметь значение Null. Среда выполнения Windows
PowerShell создает ошибку, если параметр имеет значение Null.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateNotNull()]
$UserName
)
Атрибут проверки ValidateNotNullOrEmpty
Атрибут ValidateNotNullOrEmpty определяет, что аргумент
параметра не может иметь значение Null и не может быть
пустым. Среда выполнения Windows PowerShell создает ошибку, если
параметр задан, но имеет значение Null, пустой строки или пустого
массива.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateNotNullOrEmpty()]
$UserName
)
Динамические параметры
Динамические параметры — это параметры командлета, функции или скрипта,
доступные только при определенных условиях.
Например, у некоторых командлетов поставщика могут быть параметры,
доступные только при использовании командлета в пути поставщика.
Одним из динамических параметров является параметр Encoding
командлета Set-Item, который доступен только при использовании командлета
Set-Item в пути поставщика FileSystem.
Для создания динамического параметра функции или скрипта
используйте ключевое слово DynamicParam.
Синтаксис выглядит следующим образом/
DynamicParam {<список_инструкций>}
В списке инструкций используйте инструкцию If для указания условий,
при которых параметр будет доступен в функции.
Используйте командлет New-Object для создания объекта
System.Management.Automation.RuntimeDefinedParameter, представляющего
параметр и задающего его имя.
Также можно использовать команду New-Object для создания объекта
System.Management.Automation.ParameterAttribute, представляющего атрибуты
параметра (например, Mandatory, Position или ValueFromPipeline)
или его набор параметров.
В следующем примере показана функция со стандартными параметрами Name и
Path, а также с дополнительным динамическим параметром DP1. Параметр DP1
находится в наборе параметров PSet1 и принадлежит к типу Int32.
Параметр DP1 доступен в функции Sample только в том случае, если
в значении параметра Path содержится строка "HKLM:", указывающая
на использование командлета на диске реестра HKEY_LOCAL_MACHINE.
function Sample {
Param ([String]$Name, [String]$Path)
DynamicParam
{
if ($path -match "*HKLM*:")
{
$dynParam1 = new-object
System.Management.Automation.RuntimeDefinedParameter("dp1",
[Int32], $attributeCollection)
$attributes = new-object System.Management.Automation.ParameterAttribute
$attributes.ParameterSetName = 'pset1'
$attributes.Mandatory = $false
$attributeCollection = new-object
-Type System.Collections.ObjectModel.Collection``1[System.Attribute]
$attributeCollection.Add($attributes)
$paramDictionary = new-object
System.Management.Automation.RuntimeDefinedParameterDictionary
$paramDictionary.Add("dp1", $dynParam1)
return $paramDictionary
} End if
}
}
Дополнительные сведения см. в разделе "Класс RuntimeDefinedParameter"
библиотеки MSDN (Microsoft Developer Network)
по адресу https://go.microsoft.com/fwlink/?LinkID=145130.
СМ. ТАКЖЕ
about_Advanced Functions
about_Functions_Advanced_Methods
about_Functions_CmdletBindingAttribute