about_Functions_Advanced_Parameters

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

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

Длинное описание

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

При использовании атрибута CmdletBinding PowerShell автоматически добавляет общие параметры. Невозможно создать какие-либо параметры, использующие те же имена, что и общие параметры. Дополнительные сведения см. в about_CommonParameters.

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

Объявление параметров

Параметры — это переменные, объявленные в param() инструкции функции или scriptblock. Можно использовать необязательный атрибут [Parameter()] отдельно или в сочетании с атрибутом [Alias()] или любым из атрибутов проверки параметров.

Имена параметров соответствуют правилам имен переменных. Имена параметров состоят из десятичных цифр, алфавитных символов и символов подчеркивания. Полный список правил именования см. в about_Variables.

Важный

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

Рассмотрим следующий пример:

function TestFunction {
    param (
        [switch] $100,
        [string] $200
    )

    "100: $100"
    "200: $200"
}

При попытке использовать параметры PowerShell интерпретирует их как строки, передаваемые как позиционный параметр.

PS> TestFunction -100 -200 Hello
100: False
200: -100
$args: -200 Hello

Выходные данные показывают, что PowerShell привязывает значение -100 к переменной параметра $200. Остальные позиционные значения привязаны к $args. Чтобы обойти проблему, можно использовать сплет для передачи значений параметров.

PS> $ht = @{100 = $true; 200 = 'Hello'}
PS> TestFunction @ht
100: True
200: Hello
$args:

Дополнительные сведения см. в about_Splatting.

Преобразование типов значений параметров

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

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

В этом примере мы создадим командлет и функцию скрипта, которая принимает параметр [datetime]. Текущий язык и региональные параметры изменены для использования немецких параметров. Дата, отформатированная немецким языком, передается параметру.

# Create a cmdlet that accepts a [datetime] argument.
Add-Type @'
  using System;
  using System.Management.Automation;
  [Cmdlet("Get", "Date_Cmdlet")]
  public class GetFooCmdlet : Cmdlet {

    [Parameter(Position=0)]
    public DateTime Date { get; set; }

    protected override void ProcessRecord() {
      WriteObject(Date);
    }
  }
'@ -PassThru | % Assembly | Import-Module

[cultureinfo]::CurrentCulture = 'de-DE'
$dateStr = '19-06-2018'

Get-Date_Cmdlet $dateStr

Dienstag, 19. Juni 2018 00:00:00

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

# Define an equivalent function.
function Get-Date_Func {
  param(
    [datetime] $Date
  )
  process {
    $Date
  }
}

[cultureinfo]::CurrentCulture = 'de-DE'

# This German-format date string doesn't work with the invariant culture.
# E.g., [datetime] '19-06-2018' breaks.
$dateStr = '19-06-2018'

Get-Date_Func $dateStr

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

Get-Date_Func: Cannot process argument transformation on parameter 'Date'.
Cannot convert value "19-06-2018" to type "System.DateTime". Error:
"String '19-06-2018' was not recognized as a valid DateTime."

Дополнительные сведения см. в about_Type_Conversion.

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

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

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

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

param(
    [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
    [string[]]$ComputerName
)

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

Параметры переключения — это параметры, которые не принимают значения параметров. Вместо этого они передают логическое значение true-или-false через их присутствие или отсутствие, чтобы при наличии параметра коммутатора он имеет значение true и при отсутствии значения false.

Например, параметр Recurse Get-ChildItem является параметром коммутатора.

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

param([switch]$AsByteArray)

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

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

-IncludeAll

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

-IncludeAll $true

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

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

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

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

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

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

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

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

dynamicparam {<statement-list>}

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

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

function Get-Sample {
  [CmdletBinding()]
  param([string]$Name, [string]$Path)

  dynamicparam
  {
    if ($Path.StartsWith("HKLM:"))
    {
      $parameterAttribute = [System.Management.Automation.ParameterAttribute]@{
          ParameterSetName = "ByRegistryPath"
          Mandatory = $false
      }

      $attributeCollection = [System.Collections.ObjectModel.Collection[System.Attribute]]::new()
      $attributeCollection.Add($parameterAttribute)

      $dynParam1 = [System.Management.Automation.RuntimeDefinedParameter]::new(
        'KeyCount', [int32], $attributeCollection
      )

      $paramDictionary = [System.Management.Automation.RuntimeDefinedParameterDictionary]::new()
      $paramDictionary.Add('KeyCount', $dynParam1)
      return $paramDictionary
    }
  }
}

Дополнительные сведения см. в документации по типу RuntimeDefinedParameter.

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

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

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

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

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

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

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

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

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

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

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

param(
    [Parameter(Argument1=value1, Argument2=value2)]
    $ParameterName
)

Логические типы аргументов атрибута параметра по умолчанию false при пропуске из атрибута параметра. Задайте значение аргумента для $true или просто перечислите аргумент по имени. Например, следующие атрибуты параметра эквивалентны.

param(
    [Parameter(Mandatory=$true)]
)

# Boolean arguments can be defined using this shorthand syntax

param(
    [Parameter(Mandatory)]
)

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

param(
    [Parameter()]
    $ParameterName
)

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

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

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

param(
    [Parameter(Mandatory)]
    [string[]]$ComputerName
)

Аргумент положения

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

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

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

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

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

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

param(
    [Parameter(Position=0)]
    [string[]]$ComputerName
)

Аргумент ParameterSetName

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

Заметка

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

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

param(
    [Parameter(Mandatory, ParameterSetName="Computer")]
    [string[]]$ComputerName,

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

    [Parameter()]
    [switch]$Summary
)

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

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

param(
    [Parameter(Mandatory, ParameterSetName="Computer")]
    [string[]]$ComputerName,

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

    [Parameter(ParameterSetName="Computer")]
    [Parameter(Mandatory, ParameterSetName="User")]
    [switch]$Summary
)

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

Аргумент ValueFromPipeline

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

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

param(
    [Parameter(Mandatory, ValueFromPipeline)]
    [string[]]$ComputerName
)

Аргумент ValueFromPipelineByPropertyName

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

Например, если функция имеет параметр ComputerName, а объект с конвейером имеет свойство ComputerName Computer Name, значение свойства ComputerName назначается параметру ComputerName функции.

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

param(
    [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
    [string[]]$ComputerName
)

Рассмотрим реализацию функции с помощью этого аргумента:

function Test-ValueFromPipelineByPropertyName{
  param(
      [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
      [string[]]$ComputerName
  )
  Write-Output -InputObject "Saw that ComputerName was '$ComputerName'"
}

Затем демонстрация размещения объекта с помощью свойства ComputerName будет:

[pscustomobject]@{ ComputerName = "HelloWorld" } |
    Test-ValueFromPipelineByPropertyName

Saw that ComputerName was 'HelloWorld'

Заметка

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

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

Аргумент ValueFromRemainingArguments

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

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

function Test-Remainder {
    param(
        [Parameter(Mandatory, Position=0)]
        [string]$Value,

        [Parameter(ValueFromRemainingArguments, Position=1)]
        [string[]]$Remaining
    )

    "Value = $Value"
    "Found $($Remaining.Count) remaining values"

    for ($i = 0; $i -lt $Remaining.Count; $i++) {
        "${i}: $($Remaining[$i])"
    }
}

PS> Test-Remainder first one two three

Value = first
Found 3 remaining values
0: one
1: two
2: three

Начиная с PowerShell 6.2 коллекции обрабатываются по-разному при передаче в ValueFromRemainingArguments. Если передать только коллекцию, каждое значение в коллекции рассматривается как отдельный элемент.

PS> Test-Remainder first one, two, three

Value = first
Found 3 remaining values
0: one
1: two
2: three

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

PS> Test-Remainder first one, two three four

Value = first
Found 3 remaining values
0: one two
1: three
2: four

Аргумент HelpMessage

Аргумент HelpMessage указывает строку, содержащую краткое описание параметра или его значения. Если вы выполняете команду без обязательного параметра, PowerShell запрашивает входные данные. Чтобы просмотреть сообщение справки, введите !? в запросе и нажмите ВВОД.

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

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

Пример выходных данных:

cmdlet  at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
ComputerName[0]: !?
Enter one or more computer names separated by commas.
ComputerName[0]: localhost
ComputerName[1]:

Если нет справки на основе комментариев для функции, это сообщение отображается в выходных данных Get-Help -Full.

Этот аргумент не влияет на необязательные параметры.

Аргумент DontShow

Значение DontShow обычно используется для обеспечения обратной совместимости для команды, в которой устаревший параметр не может быть удален. Параметр DontShow для True скрывает параметр от пользователя для расширения вкладок и IntelliSense.

PowerShell версии 7 (и выше) использует DontShow для скрытия следующих устаревших параметров:

Параметр NoTypeInformationConvertTo-Csv и Export-Csv
Параметр RawFormat-Hex
Параметр UseBasicParsingInvoke-RestMethod и Invoke-WebRequest

Аргумент DontShow имеет следующие побочные эффекты:

Влияет на все наборы параметров для связанного параметра, даже если есть набор параметров, в котором DontShow не используется.
Скрывает общие параметры от завершения вкладки и IntelliSense. DontShow не скрывает необязательные общие параметры: WhatIf, подтвердитьили UseTransaction.

Атрибут псевдонима

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

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

param(
    [Parameter(Mandatory)]
    [Alias("CN","MachineName")]
    [string[]]$ComputerName
)

Атрибут учетных данных

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

param(
    [Parameter()]
    [System.Management.Automation.Credential()]
    [PSCredential]$Credential
)

Экспериментальный атрибут

Используйте атрибут экспериментальной, чтобы объявить некоторый код экспериментальным. Полное описание атрибута см. в about_Experimental_Features.

Атрибут PSDefaultValue

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

<#
    .SYNOPSIS
     This is a test script that has a parameter with a default value.
#>
function TestDefaultValue {
    param(
        [PSDefaultValue(Help='Current directory')]
        [string]$Name = $PWD.Path
    )

    $Name
}

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

Get-Help TestDefaultValue -Parameter Name

-Name <String>

    Required?                    false
    Position?                    1
    Default value                Current directory
    Accept pipeline input?       false
    Accept wildcard characters?  false

Аргументы атрибутов PSDefaultValue

Атрибут PSDefaultValue имеет два аргумента:

справке — строка, описывающая значение по умолчанию. Эти сведения отображаются командлетом Get-Help.
значение — значение по умолчанию параметра.

Оба аргумента являются необязательными. Если аргументы не указаны, Get-Help отображает значение, назначенное параметру.

Атрибут PSTypeName

Имена расширенных типов нельзя использовать в объявлении типов. Атрибут PSTypeName* позволяет ограничить тип параметра расширенным типом.

В этом примере командлет Test-Connection возвращает расширенный тип. Атрибут psTypeName можно использовать, чтобы ограничить тип параметра расширенным типом.

function TestType {
    param(
        [PSTypeName('Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus')]
        [psobject]$MtuStatus
    )

    $MtuStatus
}

$mtu = Test-Connection -TargetName bing.com -MtuSize
TestType $mtu

Атрибут System.Obsolete

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

Например, рассмотрим функцию, которая имеет параметр переключателя NoType Information, который определяет, включены ли сведения о типе в выходные данные. Вы хотите сделать это поведение по умолчанию и удалить параметр из функции. Однако вы не хотите прерывать существующие скрипты, использующие функцию. Параметр можно пометить как устаревший и добавить сообщение, объясняющее изменение.

param(
    [System.Obsolete("The NoTypeInformation parameter is obsolete.")]
    [SwitchParameter]$NoTypeInformation
)

Атрибут SupportsWildcards

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

param(
    [Parameter(Mandatory)]
    [SupportsWildcards()]
    [string[]]$Path
)

Использование этого атрибута не включает автоматическую поддержку подстановочных знаков. Разработчик командлета должен реализовать код для обработки входных данных с подстановочными знаками. Поддерживаемые подстановочные знаки могут отличаться в зависимости от базового API или поставщика PowerShell. Дополнительные сведения см. в about_Wildcards.

Атрибуты завершения аргументов

Атрибут ArgumentCompletions

Атрибут ArgumentCompletions позволяет добавлять значения завершения вкладок в определенный параметр. Атрибут ArgumentCompletions должен быть определен для каждого параметра, которому требуется завершение вкладки. Атрибут аргументов похож на ValidateSet. Оба атрибута принимают список значений, которые будут представлены, когда пользователь нажимает tab после имени параметра. Однако в отличие от ValidateSet, значения не проверяются.

Этот атрибут появился в PowerShell 6.0.

Дополнительные сведения см. в about_Functions_Argument_Completion.

Атрибут ArgumentCompleter

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

Дополнительные сведения см. в about_Functions_Argument_Completion.

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

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

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

[AllowNull()] [int]$number = 7

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

Заметка

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

Если вы объявляете тип с разрывом строки перед именем атрибута и переменной, тип обрабатывается как собственная инструкция.

[string]
[ValidateLength(1,5)] $Text = 'Okay'

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     String                                   System.Object

Если вы объявляете атрибут проверки после типа, то назначенное значение проверяется перед преобразованием типов, что может привести к непредвиденным сбоям проверки.

[string] [ValidateLength(1,5)]$TicketIDFromInt        = 43
[string] [ValidateLength(1,5)]$TicketIDFromString     = '43'
[ValidateLength(1,5)] [string]$TicketIDAttributeFirst = 43

MetadataError: The attribute cannot be added because variable
TicketIDFromInt with value 43 would no longer be valid.

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

Атрибут allowNull позволяет $nullзначения обязательного параметра. В следующем примере объявляется хэш-параметр ComputerInfo, который может иметь значение null.

param(
    [Parameter(Mandatory)]
    [AllowNull()]
    [hashtable]$ComputerInfo
)

Заметка

Атрибут AllowNull не работает, если преобразователь типов имеет значение string, так как строковый тип не принимает значение NULL. Для этого сценария можно использовать атрибут AllowEmptyString.

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

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

param(
    [Parameter(Mandatory)]
    [AllowEmptyString()]
    [string]$ComputerName
)

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

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

param(
    [Parameter(Mandatory)]
    [AllowEmptyCollection()]
    [string[]]$ComputerName
)

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

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

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

param(
    [Parameter(Mandatory)]
    [ValidateCount(1,5)]
    [string[]]$ComputerName
)

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

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

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

param(
    [Parameter(Mandatory)]
    [ValidateLength(1,10)]
    [string[]]$ComputerName
)

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

[ValidateLength(1,10)] [string] $text = 'valid'

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

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

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

param(
    [Parameter(Mandatory)]
    [ValidatePattern("[0-9]{4}")]
    [string[]]$ComputerName
)

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

[ValidatePattern("^[0-9]{4}$")] [string]$ticketID = 1111

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

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

Перечисление ValidateRangeKind позволяет использовать следующие значения:

Positive — число больше нуля.
Negative — число меньше нуля.
NonPositive — число меньше нуля или равно нулю.
NonNegative — число больше или равно нулю.

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

param(
    [Parameter(Mandatory)]
    [ValidateRange(0,10)]
    [int]$Attempts
)

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

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

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

[ValidateRange("Positive")] [int]$number = 1

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

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

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

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

param(
    [Parameter(Mandatory)]
    [ValidateScript({$_ -ge (Get-Date)})]
    [datetime]$EventDate
)

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

[ValidateScript({$_ -le (Get-Date)})] [datetime]$date = (Get-Date)

Заметка

Если вы используете ValidateScript, вы не можете передать $null значение в параметр. При передаче значения NULL ValidateScript не удается проверить аргумент.

Переопределение сообщения об ошибке по умолчанию

Начиная с PowerShell 6, можно переопределить сообщение об ошибке по умолчанию, созданное при недопустимом значении с помощью аргумента ErrorMessage. Укажите строку составного формата. Компонент индекса 0 использует входное значение. Компонент индекса 1 использует ScriptBlock, используемый для проверки входного значения.

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

param(
    [Parameter(Mandatory)]
    [ValidateScript(
        {$_ -ge (Get-Date)},
        ErrorMessage = "{0} isn't a future date. Specify a later date."
    )]
    [datetime]$EventDate
)

Если указанное значение является последней датой, возвращается пользовательское сообщение об ошибке.

Cannot validate argument on parameter 'EventDate'. 1/1/1999 12:00:00 AM
isn't a future date. Specify a later date.

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

param(
    [Parameter(Mandatory)]
    [ValidateScript(
        {$_ -ge (Get-Date).Date},
        ErrorMessage = "{0:d} isn't a future date. Specify a later date."
    )]
    [datetime]$EventDate
)

Если указанное значение является последней датой, возвращается пользовательское сообщение об ошибке.

Cannot validate argument on parameter 'EventDate'. 1/1/1999 isn't a future
date. Specify a later date.

Атрибут ValidateSet

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

param(
    [Parameter(Mandatory)]
    [ValidateSet("Low", "Average", "High")]
    [string[]]$Detail
)

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

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

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

param(
    [ValidateSet("hello", "world")]
    [string]$Message
)

$Message = "bye"

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

MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.

Использование ValidateSet также включение расширения табуляции значений для этого параметра. Дополнительные сведения см. в разделе about_Tab_Expansion.

Значения Dynamic ValidateSet с помощью классов

Вы можете использовать class для динамического создания значений для ValidateSet во время выполнения. В следующем примере допустимые значения переменной $Sound создаются с помощью class с именем SoundNames, которая проверяет три пути файловой системы для доступных звуковых файлов:

class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
    [string[]] GetValidValues() {
        $SoundPaths = '/System/Library/Sounds/',
            '/Library/Sounds','~/Library/Sounds'
        $SoundNames = foreach ($SoundPath in $SoundPaths) {
            if (Test-Path $SoundPath) {
                (Get-ChildItem $SoundPath).BaseName
            }
        }
        return [string[]] $SoundNames
    }
}

Затем класс [SoundNames] реализуется как динамическое значение ValidateSet следующим образом:

param(
    [ValidateSet([SoundNames])]
    [string]$Sound
)

Заметка

Класс IValidateSetValuesGenerator появился в PowerShell 6.0

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

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

Атрибут ValidateNotNull предназначен для использования, если параметр необязателен, а тип не определен или имеет преобразователь типов, который не может неявно преобразовать значение NULL, например объект . Если указать тип, который неявно преобразует значение NULL, например строку , значение NULL преобразуется в пустую строку даже при использовании атрибута ValidateNotNull. Для этого сценария используйте атрибут ValidateNotNullOrEmpty.

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

param(
    [Parameter()]
    [ValidateNotNull()]
    $Id
)

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

Атрибут ValidateNotNullOrEmpty указывает, что назначенное значение не может быть любым из следующих значений:

$null
пустая строка ("")
пустой массив (@())

Если значение недопустимо, PowerShell вызывает исключение.

param(
    [Parameter(Mandatory)]
    [ValidateNotNullOrEmpty()]
    [string[]]$UserName
)

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

Атрибут ValidateNotNullOrWhiteSpace указывает, что назначенное значение не может быть любым из следующих значений:

$null
пустая строка ("")
пустой массив @()
Строка, содержащая только символы пробелов, например табуляции, пробелы, возвращаемые каретки и новые строки.
массив, содержащий все строки, которые являются пустыми или содержат только символы пробелов

Если значение недопустимо, PowerShell вызывает исключение.

param(
    [Parameter(Mandatory)]
    [ValidateNotNullOrWhiteSpace()]
    [string[]]$UserName
)

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

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

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

param(
    [ValidateDrive("C", "D", "Variable", "Function")]
    [string]$Path
)

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

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

Если используется относительный путь, текущий диск должен быть User.

function Test-UserDrivePath{
    [OutputType([bool])]
    param(
        [Parameter(Mandatory, Position=0)]
        [ValidateUserDrive()]
        [string]$Path
    )
    $true
}

Test-UserDrivePath -Path C:\

Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The path
argument drive C does not belong to the set of approved drives: User.
Supply a path argument with an approved drive.

Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'

Test-UserDrivePath: Cannot validate argument on parameter 'Path'. Cannot
find drive. A drive with the name 'User' does not exist.

Вы можете определить User диск в конфигурациях сеансов JA Just Enough Administration (JEA). В этом примере мы создадим диск User: drive.

New-PSDrive -Name 'User' -PSProvider FileSystem -Root $Env:HOMEPATH

Name           Used (GB)     Free (GB) Provider      Root
----           ---------     --------- --------      ----
User               75.76         24.24 FileSystem    C:\Users\ExampleUser

Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'

True

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

Этот атрибут используется внутри себя PowerShell и не предназначен для внешнего использования.

Этот атрибут был добавлен в PowerShell 6.1.1.

См. также

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-03-10

Поделиться через

about_Functions_Advanced_Parameters

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

Длинное описание

Объявление параметров

Преобразование типов значений параметров

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

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

Рекомендации по проектированию параметров коммутатора

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

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

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

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

Аргумент положения

Аргумент ParameterSetName

Аргумент ValueFromPipeline

Аргумент ValueFromPipelineByPropertyName

Аргумент ValueFromRemainingArguments

Аргумент HelpMessage

Аргумент DontShow

Атрибут псевдонима

Атрибут учетных данных

Экспериментальный атрибут

Атрибут PSDefaultValue

Аргументы атрибутов PSDefaultValue

Атрибут PSTypeName

Атрибут System.Obsolete

Атрибут SupportsWildcards

Атрибуты завершения аргументов

Атрибут ArgumentCompletions

Атрибут ArgumentCompleter

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

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

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

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

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

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

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

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

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

Переопределение сообщения об ошибке по умолчанию

Атрибут ValidateSet

Значения Dynamic ValidateSet с помощью классов

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

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

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

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

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

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

См. также

Обратная связь

Дополнительные ресурсы