Дополнительные параметры функций

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

Объясняет, как добавлять параметры в расширенные функции.

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

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

Параметры, добавляемые в функцию, доступны пользователям в дополнение к общим параметрам, которые PowerShell автоматически добавляет ко всем командлетам и расширенным функциям. Дополнительные сведения об общих параметрах PowerShell см. в разделе about_CommonParameters.

Начиная с PowerShell 3.0, можно использовать splatting с @Args для представления параметров в команде. Сплаттинг допустим для простых и расширенных функций. Дополнительные сведения см. в разделе about_Functions и about_Splatting.

Статические параметры

Статические параметры — это параметры, которые всегда доступны в функции . Большинство параметров в командлетах и скриптах PowerShell являются статическими параметрами.

В следующем примере показано объявление параметра ComputerName со следующими характеристиками:

• Это обязательный (обязательный).
• Он принимает входные данные из конвейера.
• Он принимает массив строк в качестве входных данных.

Param(
    [Parameter(Mandatory=$true,
    ValueFromPipeline=$true)]
    [String[]]
    $ComputerName
)

Атрибуты параметров

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

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

В каждое объявление параметра можно добавить один или несколько атрибутов. Количество атрибутов, которые можно добавить в объявление параметра, не ограничено.

Атрибут параметра

Атрибут Parameter используется для объявления атрибутов параметров функции.

Атрибут Parameter является необязательным, и его можно опустить, если ни один из параметров функций не требует атрибутов. Но чтобы ее можно было распознать как расширенную, а не простую функцию, она должна иметь либо атрибут CmdletBinding , либо атрибут Parameter , либо и то, и другое.

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

Используйте следующий синтаксис для объявления атрибута Parameter , аргумента и значения аргумента. Круглые скобки, включающие аргумент и его значение, должны соответствовать параметру без промежуточного пробела.

Param(
    [Parameter(Argument=value)]
    $ParameterName
)

Используйте запятые для разделения аргументов в скобках. Используйте следующий синтаксис для объявления двух аргументов атрибута Parameter .

Param(
    [Parameter(Argument1=value1,
    Argument2=value2)]
)

Если вы используете атрибут Parameter без аргументов в качестве альтернативы атрибуту CmdletBinding , круглые скобки, следующие за именем атрибута, по-прежнему требуются.

Param(
    [Parameter()]
    $ParameterName
)

Обязательный аргумент

Аргумент Mandatory указывает, что параметр является обязательным. Если этот аргумент не указан, параметр является необязательным.

В следующем примере объявляется параметр ComputerName . Он использует аргумент , Mandatory чтобы сделать параметр обязательным.

Param(
    [Parameter(Mandatory=$true)]
    [String[]]
    $ComputerName
)

Аргумент Position

Аргумент Position определяет, является ли имя параметра обязательным при использовании параметра в команде. Если объявление параметра включает Position аргумент , имя параметра можно опустить, а PowerShell определяет значение неименованного параметра по его позиции или по порядку в списке неименованных значений параметров в команде.

Position Если аргумент не указан, имя параметра, псевдоним или сокращение имени параметра должно предшествовать значению параметра при каждом использовании параметра в команде.

По умолчанию все параметры функции являются позициональными. PowerShell назначает номера позиций параметрам в том порядке, в котором параметры объявляются в функции. Чтобы отключить эту функцию, задайте для аргумента атрибута $FalseCmdletBinding значение PositionalBinding . Аргумент Position имеет приоритет над значением аргумента PositionalBinding для параметров, в которых он объявлен. Дополнительные сведения см PositionalBinding . в разделе about_Functions_CmdletBindingAttribute.

Значение аргумента Position указывается в виде целого числа. Значение позиции 0 представляет первую позицию в команде, значение позиции 1 — вторую позицию в команде и т. д.

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

В следующем примере объявляется параметр ComputerName . Он использует Position аргумент со значением 0. В результате, если -ComputerName параметр опущен в команде, его значение должно быть первым или единственным значением неименованного параметра в команде.

Param(
    [Parameter(Position=0)]
    [String[]]
    $ComputerName
)

Примечание

Get-Help Когда командлет отображает соответствующий атрибут параметра Position, значение position увеличивается на единицу.

Например, параметр со значением Position аргумента 0 имеет атрибут параметра Position=1.

Аргумент ParameterSetName

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

Примечание

Для командлета или функции существует ограничение в 32 набора параметров.

В следующем примере объявляется параметр ComputerName в наборе Computer параметров, параметр UserName в наборе User параметров и параметр Summary в обоих наборах параметров.

Param(
    [Parameter(Mandatory=$true,
    ParameterSetName="Computer")]
    [String[]]
    $ComputerName,

    [Parameter(Mandatory=$true,
    ParameterSetName="User")]
    [String[]]
    $UserName,

    [Parameter(Mandatory=$false)]
    [Switch]
    $Summary
)

Можно указать только одно ParameterSetName значение в каждом аргументе и только один ParameterSetName аргумент в каждом атрибуте Parameter . Чтобы указать, что параметр отображается в нескольких наборах параметров, добавьте дополнительные атрибуты параметров .

В следующем примере явно добавляется параметр Summary в наборы Computer параметров и User . Параметр Summary является необязательным в наборе Computer параметров и обязательным в наборе User параметров.

Param(
    [Parameter(Mandatory=$true,
    ParameterSetName="Computer")]
    [String[]]
    $ComputerName,

    [Parameter(Mandatory=$true,
    ParameterSetName="User")]
    [String[]]
    $UserName,

    [Parameter(Mandatory=$false, ParameterSetName="Computer")]
    [Parameter(Mandatory=$true, ParameterSetName="User")]
    [Switch]
    $Summary
)

Дополнительные сведения о наборах параметров см. в разделе Наборы параметров командлета.

Аргумент 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
)

Примечание

Типизированный параметр, который принимает входные данные конвейера (by Value) или (by PropertyName), позволяет использовать в параметре блоки скриптов с задержкой привязки .

Блок скрипта delay-bind запускается автоматически во время ParameterBinding. Результат привязан к параметру . Привязка задержки не работает для параметров, определенных как тип ScriptBlock или System.Object, блок скрипта передается без вызова.

О блоках скриптов с задержкой привязки можно прочитать здесь about_Script_Blocks.md.

Аргумент ValueFromRemainingArguments

Аргумент ValueFromRemainingArguments указывает, что параметр принимает все значения параметра в команде, которые не назначены другим параметрам функции.

Существует известная проблема, связанная с использованием коллекций с ValueFromRemainingArguments , при которой переданная коллекция обрабатывается как один элемент.

В следующем примере показана эта известная проблема. Параметр Remaining должен содержать один в индексе 0 и два в индексе 1. Вместо этого оба элемента объединяются в одну сущность.

function Test-Remainder
{
     param(
         [string]
         [Parameter(Mandatory = $true, Position=0)]
         $Value,
         [string[]]
         [Parameter(Position=1, ValueFromRemainingArguments)]
         $Remaining)
     "Found $($Remaining.Count) elements"
     for ($i = 0; $i -lt $Remaining.Count; $i++)
     {
        "${i}: $($Remaining[$i])"
     }
}
Test-Remainder first one,two

Found 1 elements
0: one two

Примечание

Эта проблема устранена в PowerShell 6.2.

Аргумент HelpMessage

Аргумент HelpMessage указывает строку, содержащую краткое описание параметра или его значение. PowerShell отображает это сообщение в командной строке, которая появляется, когда в команде отсутствует обязательное значение параметра. Этот аргумент не влияет на необязательные параметры.

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

Param(
    [Parameter(Mandatory=$true,
    HelpMessage="Enter one or more computer names separated by commas.")]
    [String[]]
    $ComputerName
)

Alias - атрибут

Атрибут Alias задает альтернативное имя для параметра. Количество псевдонимов, которые можно назначить параметру, не ограничено.

В следующем примере показано объявление параметра, которое добавляет псевдонимы CN и MachineName к обязательному параметру ComputerName .

Param(
    [Parameter(Mandatory=$true)]
    [Alias("CN","MachineName")]
    [String[]]
    $ComputerName
)

Атрибуты проверки параметров и переменных

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

Атрибут проверки AllowNull

Атрибут AllowNull позволяет значению обязательного параметра иметь значение $null. В следующем примере объявляется параметр ComputerName , который может иметь значение NULL .

Param(
    [Parameter(Mandatory=$true)]
    [AllowNull()]
    [String]
    $ComputerName
)

Атрибут проверки AllowEmptyString

Атрибут AllowEmptyString позволяет значению обязательного параметра быть пустой строкой (""). В следующем примере объявляется параметр ComputerName , который может иметь пустое строковое значение.

Param(
    [Parameter(Mandatory=$true)]
    [AllowEmptyString()]
    [String]
    $ComputerName
)

Атрибут проверки AllowEmptyCollection

Атрибут AllowEmptyCollection позволяет значению обязательного параметра быть пустой коллекцией @(). В следующем примере объявляется параметр ComputerName , который может иметь пустое значение коллекции.

Param(
    [Parameter(Mandatory=$true)]
    [AllowEmptyCollection()]
    [String[]]
    $ComputerName
)

Атрибут проверки ValidateCount

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

Следующее объявление параметра создает параметр ComputerName , который принимает от одного до пяти значений параметра.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateCount(1,5)]
    [String[]]
    $ComputerName
)

Атрибут проверки ValidateLength

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

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

Param(
    [Parameter(Mandatory=$true)]
    [ValidateLength(1,10)]
    [String[]]
    $ComputerName
)

В следующем примере значение переменной $number должно быть не менее одного символа в длину и не более десяти символов.

[Int32][ValidateLength(1,10)]$number = 01

Атрибут проверки ValidatePattern

Атрибут ValidatePattern задает регулярное выражение, которое сравнивается со значением параметра или переменной. PowerShell создает ошибку, если значение не соответствует шаблону регулярного выражения.

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

Param(
    [Parameter(Mandatory=$true)]
    [ValidatePattern("[0-9][0-9][0-9][0-9]")]
    [String[]]
    $ComputerName
)

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

[Int32][ValidatePattern("^[0-9][0-9][0-9][0-9]$")]$number = 1111

Атрибут проверки ValidateRange

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

Param(
    [Parameter(Mandatory=$true)]
    [ValidateRange(0,10)]
    [Int]
    $Attempts
)

В следующем примере значение переменной $number должно находиться в диапазоне от нуля до десяти.

[Int32][ValidateRange(0,10)]$number = 5

Атрибут проверки ValidateScript

Атрибут ValidateScript указывает скрипт, который используется для проверки значения параметра или переменной. PowerShell передает значение в скрипт и создает ошибку, если скрипт возвращает $false или создает исключение.

При использовании атрибута ValidateScript проверяемое значение сопоставляется с переменной $_ . Переменную можно использовать $_ для ссылки на значение в скрипте.

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

Param(
    [Parameter(Mandatory=$true)]
    [ValidateScript({$_ -ge (Get-Date)})]
    [DateTime]
    $EventDate
)

В следующем примере значение переменной $date должно быть больше текущей даты и времени или равно ей.

[DateTime][ValidateScript({$_ -ge (Get-Date)})]$date = (Get-Date)

Атрибут ValidateSet

Атрибут ValidateSet задает набор допустимых значений для параметра или переменной. PowerShell создает ошибку, если значение параметра или переменной не соответствует значению в наборе. В следующем примере параметр Detail может иметь только значение Low, Average или High.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateSet("Low", "Average", "High")]
    [String[]]
    $Detail
)

В следующем примере переменная $flavor должна иметь значение Chocolate, Strawberry или Vanilla.

[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[String]$flavor = "Strawberry"

Проверка выполняется всякий раз, когда эта переменная назначается даже в скрипте. Например, следующее приводит к ошибке во время выполнения:

Param(
    [ValidateSet("hello", "world")]
    [String]$Message
)

$Message = "bye"

Атрибут проверки ValidateNotNull

Атрибут ValidateNotNull указывает, что значение параметра не может быть $nullравно . PowerShell создает ошибку, если параметр имеет $nullзначение .

Атрибут ValidateNotNull предназначен для использования, если тип значения параметра не указан или если указанный тип принимает значение $null. Если указать тип, который не принимает $null значение, например строку, $null значение отклоняется без атрибута ValidateNotNull , так как оно не соответствует указанному типу.

В следующем примере значение параметра ID не может быть $nullравно .

Param(
    [Parameter(Mandatory=$true)]
    [ValidateNotNull()]
    $ID
)

Атрибут проверки ValidateNotNullOrEmpty

Атрибут ValidateNotNullOrEmpty указывает, что значение параметра не может быть $null и не может быть пустой строкой (""). PowerShell создает ошибку, если параметр используется в вызове функции, но его значение равно $null, пустая строка ("") или пустой массив @().

Param(
    [Parameter(Mandatory=$true)]
    [ValidateNotNullOrEmpty()]
    [String[]]
    $UserName
)

Динамические параметры

Динамические параметры — это параметры командлета, функции или скрипта, которые доступны только при определенных условиях.

Например, несколько командлетов поставщика имеют параметры, доступные только при использовании командлета на диске поставщика или в определенном пути к диску поставщика. Например, параметр Encoding доступен в Add-Contentкомандлетах , Get-Contentи Set-Content только если он используется на диске файловой системы.

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

Динамические параметры могут быть полезны, но используйте их только при необходимости, так как их может быть трудно обнаружить пользователям. Чтобы найти динамический параметр, пользователь должен находиться в пути поставщика, использовать параметр ArgumentList командлета Get-Command или параметр Path объекта Get-Help.

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

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

DynamicParam {<statement-list>}

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

New-Object Используйте командлет , чтобы создать объект System.Management.Automation.RuntimeDefinedParameter для представления параметра и указать его имя.

С помощью New-Object команды можно создать объект System.Management.Automation.ParameterAttribute для представления атрибутов параметра, таких как Mandatory, Position, ValueFromPipeline или его набор параметров.

В следующем примере показан пример функции со стандартными параметрами с именами Name и Path и необязательным динамическим параметром с именем DP1. Параметр DP1 находится в наборе PSet1 параметров и имеет тип Int32. Параметр DP1 доступен в Get-Sample функции, только если значение параметра Path начинается с HKLM:, указывая, что он используется на HKEY_LOCAL_MACHINE диске реестра.

function Get-Sample {
  [CmdletBinding()]
  Param([String]$Name, [String]$Path)

  DynamicParam
  {
    if ($Path.StartsWith("HKLM:"))
    {
      $attributes = New-Object -Type `
        System.Management.Automation.ParameterAttribute
      $attributes.ParameterSetName = "PSet1"
      $attributes.Mandatory = $false
      $attributeCollection = New-Object `
        -Type System.Collections.ObjectModel.Collection[System.Attribute]
      $attributeCollection.Add($attributes)

      $dynParam1 = New-Object -Type `
        System.Management.Automation.RuntimeDefinedParameter("DP1", [Int32],
          $attributeCollection)

      $paramDictionary = New-Object `
        -Type System.Management.Automation.RuntimeDefinedParameterDictionary
      $paramDictionary.Add("DP1", $dynParam1)
      return $paramDictionary
    }
  }
}

Дополнительные сведения см. в разделе RuntimeDefinedParameter.

Параметры-переключатели

Параметры переключателя — это параметры без значения параметра. Они эффективны только при использовании и имеют только один эффект.

Например, параметр NoProfilepowershell.exe является параметром switch.

Чтобы создать параметр switch в функции, укажите Switch тип в определении параметра.

Пример:

Param([Switch]<ParameterName>)

Или можно использовать другой метод:

Param(
    [Parameter(Mandatory=$false)]
    [Switch]
    $<ParameterName>
)

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

Например, чтобы использовать параметр switch, пользователь вводит параметр в команде .

-IncludeAll

Чтобы использовать логический параметр, пользователь вводит параметр и логическое значение.

-IncludeAll:$true

При создании параметров коммутатора тщательно выберите имя параметра. Убедитесь, что имя параметра сообщает пользователю о действии параметра. Избегайте неоднозначных терминов, таких как Filter или Maximum , которые могут означать обязательное значение.

Атрибут ArgumentCompleter

Атрибут ArgumentCompleter позволяет добавлять значения завершения табуляции в определенный параметр. Как и DynamicParameters, доступные значения вычисляются во время выполнения, когда пользователь нажимает клавишу TAB после имени параметра.

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

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

Param(
    [Parameter(Mandatory)]
    [ArgumentCompleter({
        param ($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter)
        # Perform calculation of tab completed values here.
    })]
)

Блок скрипта ArgumentCompleter

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

• $commandName (Позиция 0) — для этого параметра задается имя команды, для которой блок скрипта обеспечивает завершение нажатия клавиши TAB.
• $parameterName (Позиция 1) — для этого параметра задается параметр , значение которого требует завершения нажатия клавиши TAB.
• $wordToComplete (Позиция 2) — этот параметр имеет значение, предоставленное пользователем до нажатия клавиши TAB. Блок скрипта должен использовать это значение для определения значений завершения табуляции.
• $commandAst (Позиция 3) — для этого параметра задано абстрактное синтаксический дерево (AST) для текущей входной строки. Дополнительные сведения см. в разделе Класс Ast.
• $fakeBoundParameter (Позиция 4) — для этого параметра задается хэш-таблицу, содержащую $PSBoundParameters для командлета, до нажатия пользователем клавиши TAB. Дополнительные сведения см. в разделе about_Automatic_Variables.

Блок скрипта ArgumentCompleter должен раскрутить значения с помощью конвейера, напримерForEach-Object , Where-Objectили другого подходящего метода. Возврат массива значений приводит к тому, что PowerShell обрабатывает весь массив как одно значение завершения табуляции.

В следующем примере к параметру Value добавляется завершение нажатия клавиши TAB . Если значение не $Type указано, возвращаются фрукты и овощи. $Type Если задано значение , указываются только значения для типа . Кроме того, оператор гарантирует, -like что если пользователь вводит следующую команду и использует завершение tab , возвращается только Apple .

Test-ArgumentCompleter -Type Fruits -Value A

function Test-ArgumentCompleter {
[CmdletBinding()]
 param (
        [Parameter(Mandatory)]
        [ValidateSet('Fruits', 'Vegetables')]
        $Type,
        [Parameter(Mandatory)]
        [ArgumentCompleter( {
            param ( $commandName,
                    $parameterName,
                    $wordToComplete,
                    $commandAst,
                    $fakeBoundParameters )

            $possibleValues = @{
                Fruits = @('Apple', 'Orange', 'Banana')
                Vegetables = @('Tomato', 'Squash', 'Corn')
            }
            if ($fakeBoundParameters.ContainsKey('Type'))
            {
                $possibleValues[$fakeBoundParameters.Type] | Where-Object {
                    $_ -like "$wordToComplete*"
                }
            }
            else
            {
                $possibleValues.Values | ForEach-Object {$_}
            }
        } )]
        $Value
      )
}

См. также раздел

about_Automatic_Variables

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute