about_Functions_Advanced_Parameters

Stručný popis

Vysvětluje, jak přidat parametry do pokročilých funkcí.

Dlouhý popis

Můžete přidat parametry do pokročilých funkcí, které napíšete, a pomocí atributů a argumentů parametrů omezit hodnoty parametrů, které uživatelé funkce odesílají pomocí parametru .

Parametry, které přidáte do funkce, jsou uživatelům k dispozici společně s běžnými parametry, které PowerShell přidává automaticky do všech rutin a pokročilých funkcí. Další informace o běžných parametrech PowerShellu najdete v tématu about_CommonParameters.

Od PowerShellu 3.0 můžete použít splatting s @Args k reprezentaci parametrů v příkazu. Splatting je platný u jednoduchých a pokročilých funkcí. Další informace najdete v tématu about_Functions a about_Splatting.

Převod typů hodnot parametrů

Když zadáte řetězce jako argumenty parametrům, které očekávají jiný typ, PowerShell řetězce implicitně převede na cílový typ parametru. Pokročilé funkce provádějí invariantní analýzu hodnot parametrů.

Naproti tomu převod citlivý na jazykovou verzi se provádí během vazby parametrů pro zkompilované rutiny.

V tomto příkladu vytvoříme rutinu a funkci skriptu, která převezme [datetime] parametr. Aktuální jazyková verze se změní tak, aby používala nastavení němčiny. Do parametru se předá datum v němčině.

# 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

Jak je znázorněno výše, rutiny používají k převodu řetězce analýzu citlivou na jazykovou verzi.

# 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

Pokročilé funkce používají analýzu invariantní jazykové verze, což vede k následující chybě.

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."

Statické parametry

Statické parametry jsou parametry, které jsou ve funkci vždy dostupné. Většina parametrů v rutinách a skriptech PowerShellu jsou statické parametry.

Následující příklad ukazuje deklaraci parametru ComputerName , který má následující vlastnosti:

  • Je povinný (povinný).
  • Přijímá vstup z kanálu.
  • Jako vstup přijímá pole řetězců.
Param(
    [Parameter(Mandatory=$true,
    ValueFromPipeline=$true)]
    [string[]]
    $ComputerName
)

Přepnutí parametrů

Parametry přepínače jsou parametry, které nemají žádnou hodnotu parametru. Místo toho vyjadřují logickou hodnotu pravda nebo nepravda prostřednictvím přítomnosti nebo nepřítomnosti, takže když je parametr přepínače k dispozici, má hodnotu true a v případě nepřítomnosti má hodnotu false .

Například recurse parametr je Get-ChildItem parametr přepínače.

Pokud chcete ve funkci vytvořit parametr přepínače, zadejte switch typ v definici parametru.

Funkce může mít například možnost výstupu dat jako pole bajtů:

Param([switch]$AsByteArray)

Přepínací parametry se snadno používají a jsou upřednostňovány před logickými parametry, které mají méně přirozenou syntaxi powershellu.

Pokud například chcete použít parametr přepínače, uživatel zadá parametr do příkazu .

-IncludeAll

Pokud chcete použít logický parametr, uživatel zadá parametr a logickou hodnotu.

-IncludeAll $true

Při vytváření parametrů přepínače pečlivě zvolte název parametru. Ujistěte se, že název parametru informuje uživatele o účinku parametru. Vyhněte se nejednoznačným termínům, jako je filtr nebo maximum , které by mohly znamenat, že hodnota je povinná.

Aspekty návrhu přepnutí parametrů

  • Parametry přepínače by neměly mít nastavené výchozí hodnoty. Ve výchozím nastavení by měly být vždy false.

  • Parametry přepínače jsou ve výchozím nastavení z pozičních parametrů vyloučené. I když jsou ostatní parametry implicitně umístěné, parametry přepínače nejsou. Můžete to přepsat v atributu Parameter, ale uživatele to zmátne.

  • Parametry přepínače by měly být navrženy tak, aby jejich nastavení přesunulo příkaz z jeho výchozího chování do méně běžného nebo složitějšího režimu. Nejjednodušším chováním příkazu by mělo být výchozí chování, které nevyžaduje použití parametrů přepínače.

  • Parametry přepínače by neměly být povinné. Jediný případ, kdy je nutné nastavit parametr přepínače jako povinný, je potřeba rozlišovat sadu parametrů.

  • Explicitní nastavení přepínače z logické hodnoty je možné provést pomocí -MySwitch:$boolValue a při splattingu pomocí $params = @{ MySwitch = $boolValue }.

  • Parametry přepínače jsou typu SwitchParameter, který se implicitně převádí na logickou hodnotu. Proměnnou parametru je možné použít přímo v podmíněném výrazu. Příklad:

    if ($MySwitch) { ... }

    Není potřeba psát if ($MySwitch.IsPresent) { ... }

Dynamické parametry

Dynamické parametry jsou parametry rutiny, funkce nebo skriptu, které jsou k dispozici pouze za určitých podmínek.

Například několik rutin zprostředkovatele má parametry, které jsou k dispozici pouze v případě, že se rutina používá v jednotce zprostředkovatele nebo v konkrétní cestě k jednotce zprostředkovatele. Například parametr Encoding je k dispozici v Add-Contentrutinách , Get-Contenta Set-Content pouze v případě, že se používá na jednotce systému souborů.

Můžete také vytvořit parametr, který se zobrazí pouze v případě, že se v příkazu funkce použije jiný parametr nebo když má jiný parametr určitou hodnotu.

Dynamické parametry můžou být užitečné, ale používejte je jenom v případě potřeby, protože je pro uživatele může být obtížné zjistit. Pokud chcete najít dynamický parametr, musí být uživatel v cestě zprostředkovatele, použít parametr ArgumentList rutiny Get-Command nebo použít parametr Path pro Get-Help.

K vytvoření dynamického parametru pro funkci nebo skript použijte DynamicParam klíčové slovo .

Syntaxe je následující:

dynamicparam {<statement-list>}

V seznamu příkazů použijte příkaz if k určení podmínek, za kterých je parametr ve funkci dostupný.

Následující příklad ukazuje funkci se standardními parametry s názvy Name a Path a volitelný dynamický parametr s názvem KeyCount. Parametr KeyCount je v ByRegistryPath sadě parametrů a má typ Int32. Parametr KeyCount je ve funkci k dispozici pouze v Get-Sample případě, že hodnota parametru Path začíná HKLM:na , což znamená, že se používá na HKEY_LOCAL_MACHINE jednotce registru.

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
    }
  }
}

Další informace najdete v dokumentaci k typu RuntimeDefinedParameter .

Atributy parametrů

Tato část popisuje atributy, které můžete přidat do parametrů funkce.

Všechny atributy jsou volitelné. Pokud však vynecháte atribut CmdletBinding , musí funkce obsahovat atribut Parameter , aby byla rozpoznána jako pokročilá funkce.

Do každé deklarace parametru můžete přidat jeden nebo více atributů. Počet atributů, které můžete přidat do deklarace parametru, není nijak omezený.

Atribut parametru

Atribut Parameter slouží k deklaraci atributů parametrů funkce.

Atribut Parameter je volitelný a můžete ho vynechat, pokud žádný z parametrů vašich funkcí nepotřebuje atributy. Chcete-li ji však rozpoznat jako pokročilou funkci, nikoli jako jednoduchou funkci, musí mít buď atribut CmdletBinding , atribut Parameter , nebo obojí.

Atribut Parameter obsahuje argumenty, které definují vlastnosti parametru, například jestli je parametr povinný nebo volitelný.

Pomocí následující syntaxe deklarujte atribut parametru , argument a hodnotu argumentu. Závorky, které ohraničují argument a jeho hodnotu, musí následovat za parametrem bez mezery.

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

K oddělení argumentů v závorkách používejte čárky. Pomocí následující syntaxe deklarujte dva argumenty atributu Parameter .

Param(
    [Parameter(Argument1=value1,
    Argument2=value2)]
)

Logické typy argumentů atributu Parameter mají výchozí hodnotu False při vynechání z atributu Parameter . Nastavte hodnotu argumentu na $true hodnotu argumentu nebo ho vypište podle názvu. Například následující atributy parametru jsou ekvivalentní.

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

# Boolean arguments can be defined using this shorthand syntax

Param(
    [Parameter(Mandatory)]
)

Pokud použijete atribut Parameter bez argumentů, jako alternativu k použití atributu CmdletBinding , jsou stále vyžadovány závorky, které následují za názvem atributu.

Param(
    [Parameter()]
    $ParameterName
)

Povinný argument

Argument Mandatory označuje, že parametr je povinný. Pokud tento argument není zadaný, je parametr volitelný.

Následující příklad deklaruje parametr ComputerName . Pomocí argumentu Mandatory nastaví parametr jako povinný.

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

Argument pozice

Argument Position určuje, jestli se při použití parametru v příkazu vyžaduje název parametru. Pokud deklarace parametru Position obsahuje argument, je možné název parametru vynechat a PowerShell identifikuje nepojmenovanou hodnotu parametru podle jejího umístění nebo pořadí v seznamu hodnot nepojmenovaných parametrů v příkazu.

Position Pokud argument není zadaný, musí název parametru nebo alias nebo zkratka názvu parametru předcházet hodnotě parametru pokaždé, když se parametr použije v příkazu.

Ve výchozím nastavení jsou všechny parametry funkce poziční. PowerShell přiřazuje parametrům čísla pozic v pořadí, v jakém jsou parametry deklarovány ve funkci. Pokud chcete tuto funkci zakázat, nastavte hodnotu argumentu PositionalBinding atributu CmdletBinding na $False. Argument Position má přednost před hodnotou argumentu PositionalBindingatributu CmdletBinding . Další informace najdete v about_Functions_CmdletBindingAttributePositionalBinding.

Hodnota argumentu Position je zadána jako celé číslo. Hodnota pozice 0 představuje první pozici v příkazu, hodnota pozice 1 představuje druhou pozici v příkazu atd.

Pokud funkce nemá žádné poziční parametry, PowerShell přiřadí pozice každému parametru na základě pořadí, ve které jsou parametry deklarovány. Jako osvědčený postup se ale na toto přiřazení nespoléhejte. Pokud chcete, aby parametry byly poziční, použijte Position argument .

Následující příklad deklaruje parametr ComputerName . Používá Position argument s hodnotou 0. V důsledku toho, pokud -ComputerName je vynechán z příkazu, musí být jeho hodnota první nebo pouze nepojmenovaná hodnota parametru v příkazu.

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

Argument ParameterSetName

Argument ParameterSetName určuje sadu parametrů, do které parametr patří. Pokud není zadána žádná sada parametrů, patří parametr do všech sad parametrů definovaných funkcí. Aby byla každá sada parametrů jedinečná, musí mít alespoň jeden parametr, který není členem žádné jiné sady parametrů.

Poznámka

Pro rutinu nebo funkci platí limit 32 sad parametrů.

Následující příklad deklaruje parametr ComputerName v Computer sadě parametrů, parametr UserName v User sadě parametrů a parametr Summary v obou sadách parametrů.

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

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

    [Parameter()]
    [switch]
    $Summary
)

Můžete zadat pouze jednu ParameterSetName hodnotu v každém argumentu a pouze jeden ParameterSetName argument v každém atributu Parametr . Chcete-li zahrnout parametr do více než jedné sady parametrů, přidejte další atributy parametru .

Následující příklad explicitně přidá parametr Summary do Computer sad parametrů a User . Parametr Summary je v Computer sadě parametrů volitelný a v User sadě parametrů povinný.

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

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

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

Další informace o sadách parametrů najdete v tématu O sadách parametrů.

Argument ValueFromPipeline

Argument ValueFromPipeline označuje, že parametr přijímá vstup z objektu kanálu. Tento argument zadejte, pokud funkce přijímá celý objekt, nikoli pouze vlastnost objektu.

Následující příklad deklaruje parametr ComputerName , který je povinný a přijímá objekt, který je předán funkci z kanálu.

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

Argument ValueFromPipelineByPropertyName

Argument ValueFromPipelineByPropertyName označuje, že parametr přijímá vstup z vlastnosti objektu kanálu. Vlastnost objektu musí mít stejný název nebo alias jako parametr.

Pokud má například funkce parametr ComputerName a objekt piped má vlastnost ComputerName , hodnota vlastnosti ComputerName je přiřazena k parametru ComputerName funkce.

Následující příklad deklaruje parametr ComputerName , který je povinný a přijímá vstup z vlastnosti ComputerName objektu, která je předána funkci prostřednictvím kanálu.

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

Poznámka

Zadaný parametr, který přijímá vstup kanálu (by Value) nebo (by PropertyName), umožňuje použití bloků skriptů se zpožděním vazby v parametru.

Blok skriptu se zpožděním vazby se spouští automaticky během parametru ParameterBinding. Výsledek je vázán na parametr . Zpoždění vazby nefunguje u parametrů definovaných jako typ ScriptBlock nebo System.Object. Blok skriptu se předává bez vyvolání.

O blocích skriptů se zpožděním a vazbou si můžete přečíst tady about_Script_Blocks.md.

Argument ValueFromRemainingArguments

Argument ValueFromRemainingArguments označuje, že parametr přijímá všechny hodnoty parametru v příkazu, které nejsou přiřazené k jiným parametrům funkce.

Následující příklad deklaruje parametr Value , který je povinný, a Zbývající parametr, který přijímá všechny zbývající hodnoty parametrů, které jsou odeslány do funkce.

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

Poznámka

Před PowerShellem 6.2 se kolekce ValueFromRemainingArguments připojila jako jedna entita v rámci indexu 0.

Argument HelpMessage

Argument HelpMessage určuje řetězec, který obsahuje stručný popis parametru nebo jeho hodnoty. Pokud příkaz spustíte bez povinného parametru, PowerShell vás vyzve k zadání vstupu. Pokud chcete zobrazit zprávu nápovědy, zadejte !? na výzvu a stiskněte Enter.

Následující příklad deklaruje povinný parametr ComputerName a zprávu nápovědy, která vysvětluje očekávanou hodnotu parametru.

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

Příklad výstupu:

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

Pokud pro funkci není žádná nápověda založená na komentářích , zobrazí se tato zpráva ve výstupu Get-Help -Full .

Tento argument nemá žádný vliv na volitelné parametry.

Atribut aliasu

Atribut Alias vytvoří alternativní název parametru. Počet aliasů, které můžete přiřadit k parametru, není nijak omezený.

Následující příklad ukazuje deklaraci parametru, která přidá aliasy CN a MachineName do povinného parametru ComputerName .

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

Atribut SupportsWildcards

Atribut SupportsWildcards slouží k označení, že parametr přijímá hodnoty se zástupnými znamény. Následující příklad ukazuje deklaraci parametru pro povinný parametr Path , který podporuje zástupné hodnoty.

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

Použití tohoto atributu automaticky nepovoluje podporu zástupných znaků. Vývojář rutin musí implementovat kód pro zpracování vstupu se zástupným znakem. Podporované zástupné cardy se můžou lišit v závislosti na příslušném rozhraní API nebo poskytovateli PowerShellu. Další informace najdete v tématu about_Wildcards.

Atributy dokončování argumentů

Atribut ArgumentCompletions

Atribut ArgumentCompletions umožňuje přidat hodnoty dokončování tabulátoru do konkrétního parametru. Atribut ArgumentCompletions musí být definován pro každý parametr, který vyžaduje dokončení tabulátoru. Atribut ArgumentCompletions je podobný atributu ValidateSet. Oba atributy přebírají seznam hodnot, které se zobrazí, když uživatel stiskne klávesu Tab za názvem parametru. Na rozdíl od ValidateSet se ale hodnoty neověřují.

Tento atribut byl zaveden v PowerShellu 6.0.

Další informace najdete v tématu about_Functions_Argument_Completion.

Atribut ArgumentCompleter

Atribut ArgumentCompleter umožňuje přidat hodnoty dokončování tabulátoru do konkrétního parametru. Atribut ArgumentCompleter musí být definován pro každý parametr, který vyžaduje dokončení tabulátoru. Stejně jako DynamicParameters se dostupné hodnoty počítají za běhu, když uživatel stiskne klávesu Tab za názvem parametru.

Další informace najdete v tématu about_Functions_Argument_Completion.

Atributy ověřování parametrů a proměnných

Ověřovací atributy směrují PowerShell k otestování hodnot parametrů, které uživatelé odesílají při volání pokročilé funkce. Pokud hodnoty parametrů v testu selžou, vygeneruje se chyba a funkce se nevolá. Ověření parametru se použije jenom na zadaný vstup a žádné další hodnoty, jako jsou výchozí hodnoty, se neověří.

Můžete také použít ověřovací atributy k omezení hodnot, které mohou uživatelé zadat pro proměnné.

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

Ověřovací atributy se dají použít na libovolnou proměnnou, ne jenom na parametry. Ověřování můžete definovat pro libovolnou proměnnou v rámci skriptu.

Poznámka

Při použití libovolných atributů s proměnnou typu je osvědčeným postupem deklarovat atribut před typem.

Pokud deklarujete typ s koncem řádku před názvem atributu a proměnné, bude typ považován za vlastní příkaz.

[string]
[ValidateLength(1,5)] $Text = 'Okay'
IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     String                                   System.Object

Pokud deklarujete ověřovací atribut za typem, přiřazovaná hodnota se ověří před převodem typu, což může vést k neočekávaným chybám ověření.

[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.

Ověřovací atribut AllowNull

Atribut AllowNull umožňuje, aby hodnota povinného parametru byla $null. Následující příklad deklaruje hashtable ComputerInfo parametr, který může mít hodnotu null .

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

Poznámka

Atribut AllowNull nefunguje, pokud je převaděč typů nastavený na řetězec, protože typ řetězce nepřijímá hodnotu null. Pro tento scénář můžete použít atribut AllowEmptyString .

Atribut ověření AllowEmptyString

Atribut AllowEmptyString umožňuje, aby hodnota povinného parametru byla prázdný řetězec (""). Následující příklad deklaruje parametr ComputerName , který může mít prázdnou řetězcovou hodnotu.

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

Ověřovací atribut AllowEmptyCollection

Atribut AllowEmptyCollection umožňuje, aby hodnota povinného parametru byla prázdná kolekce @(). Následující příklad deklaruje parametr ComputerName , který může mít prázdnou hodnotu kolekce.

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

Ověřovací atribut ValidateCount

Atribut ValidateCount určuje minimální a maximální počet hodnot parametrů, které parametr přijímá. PowerShell vygeneruje chybu, pokud je počet hodnot parametrů v příkazu, který funkci volá, mimo tento rozsah.

Následující deklarace parametru vytvoří parametr ComputerName , který přijímá jednu až pět hodnot parametru.

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

Ověřovací atribut ValidateLength

Atribut ValidateLength určuje minimální a maximální počet znaků v parametru nebo hodnotě proměnné. PowerShell vygeneruje chybu, pokud je délka hodnoty zadané pro parametr nebo proměnnou mimo rozsah.

V následujícím příkladu musí mít každý název počítače jeden až deset znaků.

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

V následujícím příkladu musí být hodnota proměnné $text minimálně jeden znak a maximálně deset znaků.

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

Ověřovací atribut ValidatePattern

Atribut ValidatePattern určuje regulární výraz, který se porovná s hodnotou parametru nebo proměnné. PowerShell vygeneruje chybu, pokud hodnota neodpovídá vzoru regulárního výrazu.

V následujícím příkladu musí hodnota parametru obsahovat čtyřmístné číslo a každá číslice musí být číslo od nuly do devíti.

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

V následujícím příkladu musí být hodnota proměnné $ticketID přesně čtyřmístné číslo a každá číslice musí být číslo od nuly do devíti.

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

Ověřovací atribut ValidateRange

Atribut ValidateRange určuje číselný rozsah nebo hodnotu výčtu ValidateRangeKind pro každý parametr nebo hodnotu proměnné. PowerShell vygeneruje chybu, pokud je nějaká hodnota mimo tento rozsah.

Výčet ValidateRangeKind umožňuje následující hodnoty:

  • Kladné – číslo větší než nula.
  • Záporné – číslo menší než nula.
  • NonPositive – číslo menší nebo rovno nule.
  • NonNegative – číslo větší nebo rovno nule.

V následujícím příkladu musí být hodnota parametru Attempts mezi nulou a deseti.

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

V následujícím příkladu musí být hodnota proměnné $number mezi nulou a deseti.

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

V následujícím příkladu musí být hodnota proměnné $number větší než nula.

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

Ověřovací atribut ValidateScript

Atribut ValidateScript určuje skript, který se používá k ověření hodnoty parametru nebo proměnné. PowerShell předá hodnotu do skriptu a vygeneruje chybu, pokud skript vrátí $false nebo pokud vyvolá výjimku.

Když použijete atribut ValidateScript , hodnota, která se ověřuje, se mapuje na proměnnou $_ . Proměnnou $_ můžete použít k odkazování na hodnotu ve skriptu.

V následujícím příkladu musí být hodnota parametru EventDate větší než nebo rovna aktuálnímu datu.

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

V následujícím příkladu musí být hodnota proměnné $date menší nebo rovna aktuálnímu datu a času.

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

Poznámka

Pokud použijete ValidateScript, nemůžete parametru $null předat hodnotu. Když předáte hodnotu null , ValidateScript nemůže argument ověřit.

Přepsání výchozí chybové zprávy

Od PowerShellu 6 můžete přepsat výchozí chybovou zprávu vygenerovanou v případě, že je zadaná hodnota neplatná s argumentem ErrorMessage . Zadejte řetězec složeného formátu. Komponenta 0 indexu používá vstupní hodnotu. Součást 1 indexu používá ScriptBlock použitý k ověření vstupní hodnoty.

V následujícím příkladu musí být hodnota parametru EventDate větší nebo rovna aktuálnímu datu a času. Pokud je hodnota neplatná, chybová zpráva hlásí, že zadané datum a čas jsou příliš staré.

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

Pokud je zadaná hodnota minulé datum, vrátí se vlastní chybová zpráva.

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

V řetězci můžete použít další formátování s volitelnými komponentami řetězce formátu.

V následujícím příkladu musí být hodnota parametru EventDate větší nebo rovna aktuálnímu datu a času. Pokud je hodnota neplatná, chybová zpráva hlásí, že zadané datum je příliš staré.

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

Pokud je zadaná hodnota minulé datum, vrátí se vlastní chybová zpráva.

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

Atribut ValidateSet

Atribut ValidateSet určuje sadu platných hodnot pro parametr nebo proměnnou a umožňuje dokončování tabulátoru. PowerShell vygeneruje chybu, pokud hodnota parametru nebo proměnné neodpovídá hodnotě v sadě. V následujícím příkladu může být hodnota parametru Detail pouze Nízká, Průměr nebo Vysoká.

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

V následujícím příkladu musí být hodnota proměnné $flavor Chocolate, Strawberry nebo Vanilla.

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

K ověření dojde vždy, když je tato proměnná přiřazena i v rámci skriptu. Například následující výsledkem je chyba za běhu:

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

$Message = "bye"

Tento příklad vrátí za běhu následující chybu:

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

Použití ValidateSet také umožňuje rozbalení hodnot pro daný parametr tabulátorem. Další informace najdete v tématu about_Tab_Expansion.

Dynamické hodnoty ValidateSet pomocí tříd

Pomocí třídy můžete dynamicky generovat hodnoty ValidateSet za běhu. V následujícím příkladu jsou platné hodnoty pro proměnnou $Sound generovány prostřednictvím třídys názvem SoundNames , která kontroluje dostupnost zvukových souborů ve třech cestách systému souborů:

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
    }
}

Třída [SoundNames] se pak implementuje jako dynamická hodnota ValidateSet následujícím způsobem:

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

Poznámka

Třída IValidateSetValuesGenerator byla představena v PowerShellu 6.0.

Ověřovací atribut ValidateNotNull

Atribut ValidateNotNull určuje, že hodnota parametru nemůže být $null. PowerShell vygeneruje chybu, pokud je $nullhodnota parametru .

Atribut ValidateNotNull je navržený tak, aby se použil, když je parametr volitelný a typ není definovaný nebo má převaděč typů, který nemůže implicitně převést hodnotu null, jako je objekt. Pokud zadáte typ, který implicitně převede hodnotu null, například řetězec, hodnota null se převede na prázdný řetězec i při použití atributu ValidateNotNull . Pro tento scénář použijte ValidateNotNullOrEmpty.

V následujícím příkladu nemůže být $nullhodnota parametru ID .

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

Ověřovací atribut ValidateNotNullOrEmpty

Atribut ValidateNotNullOrEmpty určuje, že hodnota parametru nemůže být $null a nemůže být prázdným řetězcem (""). PowerShell vygeneruje chybu, pokud se parametr používá ve volání funkce, ale jeho hodnota je $null, prázdný řetězec ("") nebo prázdné pole @().

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

Ověřovací atribut ValidateDrive

Atribut ValidateDrive určuje, že hodnota parametru musí představovat cestu, která odkazuje pouze na povolené jednotky. Pokud hodnota parametru odkazuje na jiné jednotky, než je povolená, PowerShell vygeneruje chybu. Existence cesty s výjimkou samotné jednotky není ověřená.

Pokud použijete relativní cestu, musí být aktuální jednotka v seznamu povolených jednotek.

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

Ověřovací atribut ValidateUserDrive

Atribut ValidateUserDrive určuje, že hodnota parametru musí představovat na jednotce User . PowerShell vygeneruje chybu, pokud cesta odkazuje na jinou jednotku. Ověřovací atribut pouze testuje existenci předpony jednotky cesty.

Pokud použijete relativní cestu, aktuální jednotka musí být 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.

Jednotku můžete definovat User v konfiguracích relace JEA (Just Enough Administration). V tomto příkladu vytvoříme jednotku 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

Ověřovací atribut ValidateTrustedData

Tento atribut byl přidán v PowerShellu 6.1.1.

V tuto chvíli atribut interně používá samotný PowerShell a není určený pro externí použití.

Viz také