about_Functions_Advanced_Parameters

Статья
07/02/2024

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

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

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

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

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

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

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

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

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

param([switch]$AsByteArray)

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

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

-IncludeAll

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

-IncludeAll $true

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

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

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

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

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

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

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

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

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

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

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

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

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

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)]
)

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

param(
    [Parameter()]
    $ParameterName
)

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

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

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

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

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

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

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

По умолчанию все параметры функции позициональные. PowerShell назначает номера позиций параметрам в порядке объявления параметров в функции. Чтобы отключить эту функцию, задайте для PositionalBinding аргумента атрибута КомандлетBinding значение $False. Аргумент Position имеет приоритет над значением PositionalBinding аргумента атрибута КомандлетBinding . Дополнительные сведения см 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 аргумент в каждом атрибуте параметра . Чтобы включить параметр в несколько наборов параметров, добавьте дополнительные атрибуты параметров .

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

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

Аргумент ValueFromRemainingArguments

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

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

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

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

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

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

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

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

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

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

Атрибут ArgumentCompleter

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

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

Класс можно использовать для динамического создания значений для 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, например объект. Если указать тип, который неявно преобразует значение 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 (JA). В этом примере мы создадим диск 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 6.1.1.

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

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

about_Functions_Advanced_Parameters

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

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

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

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

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

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

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

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

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

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

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

Аргумент ParameterSetName

Аргумент ValueFromPipeline

Аргумент ValueFromPipelineByPropertyName

Аргумент ValueFromRemainingArguments

Аргумент HelpMessage

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

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

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

Атрибут 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

См. также

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