about_Functions_Advanced_Parameters

Назначение: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

РАЗДЕЛ

Вставьте сюда основной текст раздела.

КРАТКОЕ ОПИСАНИЕ

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

ПОДРОБНОЕ ОПИСАНИЕ

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

Параметры, добавленные к функции, доступны пользователям вместе с общими параметрами, которые Windows PowerShell® автоматически добавляет ко всем командлетам и расширенным функциям. Подробнее об общих параметрах Windows PowerShell см. в разделе about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).

Начиная с версии Windows PowerShell 3.0, можно использовать сплаттинг с @Args для представления параметров в команде. Этот метод допустим в отношении простых и расширенных функций. Подробнее см. в разделах about_Functions (https://go.microsoft.com/fwlink/?LinkID=113231) и about_Splatting (https://go.microsoft.com/fwlink/?LinkID=262720).

СТАТИЧЕСКИЕ ПАРАМЕТРЫ

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

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

он является обязательным;

он принимает входные данные из конвейера;

в качестве входных данных он принимает массив строк.

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

АТРИБУТЫ ПАРАМЕТРОВ

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

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

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

АТРИБУТ ПАРАМЕТРА

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

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

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

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

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

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

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

          )

При использовании атрибута Parameter без аргументов (в качестве альтернативы атрибуту CmdletBinding) скобки после имени атрибута все равно требуются.

        Param
          (
            [parameter()]
            $ParameterName
          )

Аргумент Mandatory

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

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

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

Аргумент Position

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

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

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

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

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

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

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

ПРИМЕЧАНИЕ.

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

Аргумент ParameterSetName

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

В примере ниже объявляется параметр 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. Чтобы указать, что параметр относится к нескольким наборам параметров, добавьте дополнительные атрибуты Parameter.

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

        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
          )
        

Подробнее о наборах параметров см. в разделе «Наборы параметров командлетов» в библиотеке 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 определяет строку, содержащую краткое описание параметра или его значения. Windows 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
          )

АТРИБУТЫ ПРОВЕРКИ ПАРАМЕТРОВ И ПЕРЕМЕННЫХ

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

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

Атрибут AllowNull позволяет обязательному параметру иметь значение null ($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 указывает минимальное и максимальное количество значений, которые принимает параметр. Windows PowerShell выдает ошибку, если количество значений параметра в команде, которая вызывает функцию, выходит за пределы этого диапазона.

Приведенное ниже объявление параметра создает параметр ComputerName, принимающий от 1 до 5 значений.

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

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

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

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

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

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

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

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

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

В примере ниже значение параметра должно быть числом из четырех цифр от 0 до 9.

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

В примере ниже значение переменной $number должно быть числом из четырех цифр от 0 до 9.

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

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

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

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

В примере ниже значение переменной $number должно быть от 0 до 10.

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

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

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

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

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

        Param
          (
            [parameter()]
            [ValidateScript({$_ -ge (get-date)})]
            [DateTime]
            $EventDate
          )

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

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

Атрибут ValidateSet

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

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

В примере ниже значение переменной $flavor должно быть Chocolate, Strawberry или Vanilla.

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

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

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

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

В примере ниже значение параметра идентификатора не может быть null.

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

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

Атрибут ValidateNotNullOrEmpty указывает, что значение параметра не может быть null ($null) или пустой строкой («»). Windows 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 доступен в функции Sample только в том случае, если в значении параметра Path содержится строка «HKLM:», указывающая на использование командлета на диске реестра HKEY_LOCAL_MACHINE.

    function Get-Sample {
        [CmdletBinding()]
        Param ([String]$Name, [String]$Path)
 
        DynamicParam
        {
            if ($path -match ".*HKLM.*:")
            {
                $attributes = new-object System.Management.Automation.ParameterAttribute
                $attributes.ParameterSetName = "__AllParameterSets"
                $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» в библиотеке MSDN по адресу https://go.microsoft.com/fwlink/?LinkID=145130.

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

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

Например, параметр -NoProfile файла PowerShell.exe является параметром-переключателем.

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

    For example:
        Param ([Switch]<ParameterName>)
    -or- 
        Param
          (
             [parameter(Mandatory=$false)]
             [Switch]
             $<ParameterName>
          )

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

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

        -IncludeAll

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

        -IncludeAll:$true

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

СМ. ТАКЖЕ

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute