about_Functions_Advanced_Parameters

Статья
06/21/2023

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

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

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

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

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

Типы логических аргументов атрибута 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
)

Примечание

Типизированный параметр, который принимает входные данные конвейера (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 и сообщение справки, объясняющее ожидаемое значение параметра.

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

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

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

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

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

Примечание

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

Атрибут проверки 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
)

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

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

Примечание

В этом примере значение заключено 01 в одинарные кавычки. Атрибут ValidateLength не принимает число без упаковки в кавычки.

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

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

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

Param(
    [Parameter(Mandatory)]
    [ValidatePattern("[0-9][0-9][0-9][0-9]")]
    [string[]]
    $ComputerName
)

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

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

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

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

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

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

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

Param(
    [Parameter(Mandatory)]
    [ValidateRange(0,10)]
    [Int]
    $Attempts
)

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

Атрибут 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 и не предназначен для внешнего использования.

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

about_Functions_Advanced_Parameters

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

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

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

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

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

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

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

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

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

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

Аргумент position

Аргумент ParameterSetName

Аргумент ValueFromPipeline

Аргумент ValueFromPipelineByPropertyName

Аргумент ValueFromRemainingArguments

Аргумент HelpMessage

Alias - атрибут

Атрибут SupportsWildcards

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

Атрибут ArgumentCompletions

Атрибут ArgumentCompleter

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

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

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

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

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

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

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

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

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

Атрибут ValidateSet

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

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

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

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

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

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

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

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