about_Functions_Advanced_Parameters

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

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

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

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

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

Начиная с PowerShell 3.0, можно использовать splatting с @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-or-false через их присутствие или отсутствие, чтобы при наличии параметра switch у него было истинное значение, а при отсутствии — ложное значение.

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

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

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

Param([switch]$AsByteArray)

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

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

-IncludeAll

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

-IncludeAll $true

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

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

  • Параметры переключения не должны присваиваться значениям по умолчанию. По умолчанию всегда должно быть false.

  • Параметры switch исключаются из позиционных параметров по умолчанию. Даже если другие параметры являются неявно позициональными, параметры переключателя не являются. Вы можете переопределить его в атрибуте Parameter, но это смутит пользователей.

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

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

  • Явно задать переключатель из логического можно с помощью -MySwitch:$boolValue и в сплаттинге с $params = @{ MySwitch = $boolValue }помощью .

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

    if ($MySwitch) { ... }

    Нет необходимости писать if ($MySwitch.IsPresent) { ... }

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

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

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

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

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
)

Примечание

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

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

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

Аргумент ValueFromRemainingArguments

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

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

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

Примечание

До PowerShell 6.2 коллекция ValueFromRemainingArguments была присоединена как одна сущность в индексе 0.

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

Атрибут 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][0-9][0-9][0-9]")]
    [string[]]
    $ComputerName
)

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

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

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

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

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

  • Positive — число больше нуля.
  • Отрицательное значение — число меньше нуля.
  • 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.

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

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

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 может иметь только значение 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. PowerShell создает ошибку, если параметр имеет $nullзначение .

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

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

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

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

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

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

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

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

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

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