about_Functions_Advanced_Parameters

Статья
05/09/2024

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

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

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

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

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

Начиная с PowerShell 3.0, вы можете использовать сплаттинг с @Args для представления параметров в команде. Сплаттинг действителен для простых и расширенных функций. Дополнительные сведения см. в разделе about_Functions и 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."

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

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

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

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

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

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

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

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

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

Например, функция может иметь возможность вывода данных в виде массива байтов:

param([switch]$AsByteArray)

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

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

-IncludeAll

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

-IncludeAll $true

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

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

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

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

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

Динамические параметры могут быть полезны, но используйте их только при необходимости, так как их может быть трудно обнаружить пользователям. Чтобы найти динамический параметр, пользователь должен находиться в пути поставщика, использовать параметр ArgumentList командлета Get-Command или параметр Path для Get-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 .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# Boolean arguments can be defined using this shorthand syntax

param(
    [Parameter(Mandatory)]
)

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

param(
    [Parameter()]
    $ParameterName
)

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

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

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

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

Аргумент position

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

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

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

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

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

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

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

Аргумент ParameterSetName

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

Примечание

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

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

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

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

    [Parameter()]
    [switch]$Summary
)

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

В следующем примере явно добавляется параметр Summary в наборы 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
)

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

Аргумент ValueFromPipeline

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

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

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

Аргумент ValueFromPipelineByPropertyName

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

Например, если функция имеет параметр ComputerName , а возвращаемый объект имеет свойство ComputerName , значение свойства 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), позволяет использовать в параметре блоки скриптов с задержкой привязки .

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

Аргумент ValueFromRemainingArguments

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

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

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

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

    "Found $($Remaining.Count) elements"

    for ($i = 0; $i -lt $Remaining.Count; $i++) {
        "${i}: $($Remaining[$i])"
    }
}
Test-Remainder first one,two

Found 2 elements
0: one
1: two

Аргумент 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 данных.

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

Alias - атрибут

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

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

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

Атрибут credential

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

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

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

Используйте атрибут Experimental , чтобы объявить некоторый код как экспериментальный. Полное описание атрибута см. в разделе 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 , чтобы пометить параметры, которые больше не поддерживаются. Это может быть полезно, если вы хотите удалить параметр из функции, но не хотите прерывать существующие скрипты, использующие функцию.

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

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 должен быть определен для каждого параметра, которому требуется заполнение tab. Атрибут ArgumentCompletions аналогичен ValidateSet. Оба атрибута принимают список значений, которые будут представлены, когда пользователь нажимает клавишу TAB после имени параметра. Однако, в отличие от ValidateSet, значения не проверяются.

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

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

Атрибут ArgumentCompleter

Атрибут ArgumentCompleter позволяет добавлять значения завершения табуляции в определенный параметр. Атрибут ArgumentCompleter должен быть определен для каждого параметра, которому требуется заполнение tab. Как и 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 с хэш-htable, который может иметь значение 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 допускает следующие значения:

Положительный — число больше нуля.
Отрицательное значение — число меньше нуля.
NonPositive — число меньше или равно нулю.
NonNegative — число больше или равно нулю.

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

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 , используемый для проверки входного значения.

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

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 задает набор допустимых значений для параметра или переменной и включает завершение нажатия клавиши TAB. PowerShell создает ошибку, если значение параметра или переменной не соответствует значению в наборе. В следующем примере параметр Detail может иметь только значение Low, Average или High.

param(
    [Parameter(Mandatory)]
    [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"

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

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

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

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

Класс можно использовать для динамического создания значений ValidateSet во время выполнения. В следующем примере допустимые значения для переменной $Sound создаются с помощью классас именем 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, например object. Если указать тип, который неявно преобразует значение NULL, например строку, значение NULL преобразуется в пустую строку даже при использовании атрибута ValidateNotNull . В этом сценарии используйте атрибут ValidateNotNullOrEmpty .

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

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

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

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

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

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

param(
    [Parameter(Mandatory)]
    [ValidateNotNullOrEmpty()]
    [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 в конфигурациях сеанса just Enough Administration (JEA). В этом примере мы создадим диск User: .

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

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

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

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

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

about_Functions_Advanced_Parameters

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

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

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

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

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

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

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

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

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

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

Аргумент position

Аргумент ParameterSetName

Аргумент ValueFromPipeline

Аргумент ValueFromPipelineByPropertyName

Аргумент ValueFromRemainingArguments

Аргумент HelpMessage

Alias - атрибут

Атрибут credential

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

Атрибут PSDefaultValue

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

Атрибут PSTypeName

Атрибут System.Obsolete

Атрибут SupportsWildcards

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

Атрибут ArgumentCompletions

Атрибут ArgumentCompleter

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

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

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

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

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

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

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

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

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

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

Атрибут ValidateSet

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

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

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

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

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

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

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

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