about_Functions_Advanced_Parameters
Krátký popis
Vysvětluje, jak přidat parametry do pokročilých funkcí.
Dlouhý popis
Do pokročilých funkcí, které napíšete, můžete přidat parametry a pomocí atributů parametrů a argumentů omezit hodnoty parametrů, které uživatelé funkce odesílali s tímto parametrem.
Kromě běžných parametrů, které PowerShell přidá do všech rutin a pokročilých funkcí, jsou k dispozici i parametry, které do funkce přidáte automaticky. Další informace o běžných parametrech PowerShellu najdete v tématu about_CommonParameters.
Počínaje PowerShellem 3.0 můžete pomocí splattingu @Args znázorňovat parametry v příkazu. Splatting je platný pro jednoduché a pokročilé funkce. Další informace najdete v tématu about_Functions a about_Splatting.
Převod hodnot parametrů typu
Když zadáte řetězce jako argumenty parametrům, které očekávají jiný typ, PowerShell implicitně převede řetězce na cílový typ parametru. Pokročilé funkce provádějí invariantní analýzu hodnot parametrů jazykové verze.
Naproti tomu převod citlivý na jazykovou verzi se provádí během vazby parametrů pro kompilované 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 německé nastavení.
Parametru se předá datum ve formátu němčiny.
# 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 k převodu řetězce používají 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í invariantní parsování 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í charakteristiky:
- Je povinný (povinný).
- Přebírá vstup z kanálu.
- Jako vstup přebírá pole řetězců.
param(
[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
[string[]]$ComputerName
)
Parametry přepínače
Parametry přepínače jsou parametry, které nemají žádnou hodnotu parametru. Místo toho vyjadřují logickou hodnotu true nebo false prostřednictvím jejich přítomnosti nebo nepřítomnosti, takže když je parametr přepínače k dispozici, má skutečnou hodnotu a když chybí, má hodnotu false .
Parametr RecurseGet-ChildItem je například 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)
Parametry přepínače se dají snadno používat a preferují se před logickými parametry, které mají méně přirozenou syntaxi pro PowerShell.
Pokud například chcete použít parametr switch, 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 komunikuje s uživatelem. Vyhněte se nejednoznačným termínům, jako je filtr nebo maximum , které by mohly znamenat, že je hodnota povinná.
Aspekty návrhu přepínače parametrů
Parametry přepínače by neměly mít výchozí hodnoty. Vždy by měly mít výchozí hodnotu false.
Parametry přepínače jsou ve výchozím nastavení vyloučené z pozičních parametrů. I když jsou ostatní parametry implicitně poziční, parametry přepínače nejsou. Můžete to přepsat v atributu Parametr, ale bude matoucí uživatele.
Parametry přepínače by měly být navrženy tak, aby jejich nastavení přesunulo příkaz z výchozího chování do méně časté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, když je potřeba odlišit sadu parametrů.
Explicitní nastavení přepínače z logické hodnoty lze provést s
-MySwitch:$boolValuea v splattingu s$params = @{ MySwitch = $boolValue }.Parametry přepínače jsou typu
SwitchParameter, které implicitně převádí na logickou hodnotu. Proměnnou parametru lze použít přímo v podmíněném výrazu. Příklad:if ($MySwitch) { ... }Nemusíte 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á na jednotce poskytovatele nebo v konkrétní cestě jednotky zprostředkovatele. Například parametr Encoding je k dispozici na Get-ContentAdd-Content, a Set-Content rutiny pouze v případě, že se používá v jednotce systému souborů.
Můžete také vytvořit parametr, který se zobrazí pouze v případech, kdy se v příkazu funkce používá jiný parametr nebo pokud má jiný parametr určitou hodnotu.
Dynamické parametry můžou být užitečné, ale v případě potřeby je používejte, protože mohou být pro uživatele obtížné zjistit. K vyhledání dynamického parametru musí být uživatel v cestě zprostředkovatele, použijte parametr ArgumentList rutiny Get-Command nebo použijte parametr Path parametru 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 k dispozici ve funkci.
Následující příklad ukazuje funkci se standardními parametry s názvem 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 k dispozici ve Get-Sample funkci pouze v případě, že hodnota parametru Path začíná HKLM:, což znamená, že se používá v 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, bude funkce rozpoznána jako pokročilá funkce, musí obsahovat atribut Parameter.
V každé deklaraci 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 nepovinný a můžete ho vynechat, pokud žádný z parametrů vašich funkcí nepotřebuje atributy. Aby se ale funkce nerozpoznala jako pokročilá funkce, a ne jako jednoduchá funkce, musí mít buď atribut CmdletBinding , nebo atribut Parameter , nebo obojí.
Atribut Parameter obsahuje argumenty, které definují charakteristiky parametru, například zda je parametr povinný nebo volitelný.
Pomocí následující syntaxe deklarujte atribut Parametr , 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žijte čárky. Pomocí následující syntaxe deklarujte dva argumenty atributu Parameter .
param(
[Parameter(Argument1=value1, Argument2=value2)]
$ParameterName
)
Logické typy argumentů atributu Parameter výchozí na False , pokud je vynecháno z atributu Parameter . Nastavte hodnotu argumentu na $true argument nebo ho uveď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 je parametr povinný. Pokud tento argument není zadaný, je parametr volitelný.
Následující příklad deklaruje parametr ComputerName . Tento argument používá Mandatory k povinnému parametru.
param(
[Parameter(Mandatory)]
[string[]]$ComputerName
)
Argument pozice
Argument Position určuje, zda je název parametru vyžadován při použití parametru v příkazu. Pokud deklarace parametru obsahuje argument, název parametru Position může být vynechán a PowerShell identifikuje nepojmenovanou hodnotu parametru podle pozice nebo pořadí v seznamu nepojmenovaných hodnot parametrů v příkazu.
Position Pokud argument není zadaný, název parametru nebo alias nebo zkratka názvu parametru musí předcházet hodnotě parametru při každém použití parametru v příkazu.
Ve výchozím nastavení jsou všechny parametry funkce poziční. PowerShell přiřadí k parametrům čísla pozic v pořadí, v jakém jsou parametry deklarovány ve funkci.
Chcete-li tuto funkci zakázat, nastavte hodnotu PositionalBinding argumentu atributu CmdletBinding na $Falsehodnotu . Argument Position má přednost před hodnotou PositionalBinding argumentu atributu 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, když -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ů, parametr patří 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:
U rutiny nebo funkce platí limit 32 sad parametrů.
Následující příklad deklaruje parametr ComputerName v Computer sadě parametrů, Parametr UserName v User sadě parametrů a Summary parametr v obou sadách parametrů.
param(
[Parameter(Mandatory, ParameterSetName="Computer")]
[string[]]$ComputerName,
[Parameter(Mandatory, ParameterSetName="User")]
[string[]]$UserName,
[Parameter()]
[switch]$Summary
)
V každém argumentu můžete zadat pouze jednu ParameterSetName hodnotu a v každém atributu parametru pouze jeden ParameterSetName argument. Pokud chcete 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 sady parametrů. Parametr Summary je volitelný v Computer sadě parametrů a povinný v User sadě parametrů.
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ů naleznete 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, nejen 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 piped objekt 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
)
Zvažte implementaci funkce pomocí tohoto argumentu:
function Test-ValueFromPipelineByPropertyName{
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
Write-Output -InputObject "Saw that ComputerName was '$ComputerName'"
}
Pak by ukázka propojení objektu s Vlastností ComputerName byla:
[pscustomobject]@{ ComputerName = "HelloWorld" } |
Test-ValueFromPipelineByPropertyName
Saw that ComputerName was 'HelloWorld'
Poznámka:
Zadaný parametr, který přijímá vstup kanálu (by Value) nebo (by PropertyName) umožňuje použití bloků skriptu vazby zpoždění u parametru.
Blok skriptu s vazbou zpoždění se spustí automaticky během parametruBinding. Výsledek je vázán na parametr. Vazba delay nefunguje u parametrů definovaných jako typ ScriptBlock nebo System.Object. Blok skriptu se předává bez vyvolání. Další informace o blocích skriptu s vazbou zpoždění najdete v tématu about_Script_Blocks.
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ů odeslané do funkce.
function Test-Remainder {
param(
[Parameter(Mandatory, Position=0)]
[string]$Value,
[Parameter(Position=1, ValueFromRemainingArguments)]
[string[]]$Remaining
)
"Found $($Remaining.Count) elements"
for ($i = 0; $i -lt $Remaining.Count; $i++) {
"${i}: $($Remaining[$i])"
}
}
Test-Remainder first one,two
Found 2 elements
0: one
1: two
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, napište !? na příkazový řádek 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 neexistuje žá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 k povinnému parametru ComputerName .
param(
[Parameter(Mandatory)]
[Alias("CN","MachineName")]
[string[]]$ComputerName
)
Atribut přihlašovacích údajů
Atribut Credential se používá k označení, že parametr přijímá přihlašovací údaje. Následující příklad ukazuje deklaraci parametru , která používá atribut Credential .
param(
[Parameter()]
[System.Management.Automation.Credential()]
[PSCredential]$Credential
)
Experimentální atribut
Pomocí experimentálního atributu deklarujte nějaký kód jako experimentální. Úplný popis atributu najdete v tématu about_Experimental_Features.
Atribut PSDefaultValue
PsDefaultValue určuje výchozí hodnotu parametru příkazu ve skriptu. Tyto informace zobrazí rutina Get-Help . Aby se zobrazily informace o výchozí hodnotě, musí funkce obsahovat nápovědu založenou na komentářích. Příklad:
<#
.SYNOPSIS
This is a test script that has a parameter with a default value.
#>
function TestDefaultValue {
param(
[PSDefaultValue(Help='Current directory')]
[string]$Name = $PWD.Path
)
$Name
}
Slouží Get-Help k zobrazení výchozích informací o hodnotě.
Get-Help TestDefaultValue -Parameter name
-Name <String>
Required? false
Position? 1
Default value Current directory
Accept pipeline input? false
Accept wildcard characters? false
Argumenty atributu PSDefaultValue
Atribut PSDefaultValue má dva argumenty:
- Nápověda – řetězec, který popisuje výchozí hodnotu. Tyto informace zobrazí rutina
Get-Help. - Hodnota – výchozí hodnota parametru.
Oba argumenty jsou volitelné. Pokud nezadáte žádné argumenty, zobrazí Get-Help se hodnota přiřazená parametru.
Atribut PSTypeName
V deklaraci typu nelze použít rozšířené názvy typů. Atribut PSTypeName* umožňuje omezit typ parametru na rozšířený typ.
V tomto příkladu Test-Connection vrátí rutina rozšířený typ. Pomocí atributu PSTypeName můžete omezit typ parametru na rozšířený typ.
function TestType {
param(
[PSTypeName('Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus')]
[psobject]$MtuStatus
)
$MtuStatus
}
$mtu = Test-Connection -TargetName bing.com -MtuSize
TestType $mtu
Atribut System.Obsolete
Pomocí atributu System.Obsolete označte parametry, které již nejsou podporovány. To může být užitečné, když chcete odebrat parametr z funkce, ale nechcete přerušit existující skripty, které funkci používají.
Představte si například funkci, která má parametr přepínače NoTypeInformation , který řídí, zda informace o typu jsou zahrnuty do výstupu. Toto chování chcete nastavit jako výchozí a odebrat parametr z funkce. Nechcete ale přerušit existující skripty, které tuto funkci používají. Parametr můžete označit jako zastaralý a přidat zprávu s vysvětlením změny.
param(
[System.Obsolete("The NoTypeInformation parameter is obsolete.")]
[SwitchParameter]$NoTypeInformation
)
SupportsWildcards – atribut
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 hodnoty zástupných znaků.
param(
[Parameter(Mandatory)]
[SupportsWildcards()]
[string[]]$Path
)
Použití tohoto atributu automaticky nepovoluje podporu zástupných znaků. Vývojář rutiny 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 podkladové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čení 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ý validateSet. Oba atributy mají seznam hodnot, které se zobrazí, když uživatel po názvu parametru stiskne klávesu Tab . 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čení 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. Podobně jako DynamicParameters se dostupné hodnoty po stisknutí klávesy Tab za názvem parametru počítají za běhu.
Další informace najdete v tématu about_Functions_Argument_Completion.
Atributy ověřování parametrů a proměnných
Atributy ověření směrují PowerShell k otestování hodnot parametrů, které uživatelé odesílají při volání pokročilé funkce. Pokud hodnoty parametrů selžou test, vygeneruje se chyba a funkce se nevolá. Ověření parametru se použije jenom u zadaného vstupu a neověřují se žádné jiné hodnoty, jako jsou výchozí hodnoty.
Ověřovací atributy můžete také použít k omezení hodnot, které mohou uživatelé zadat pro proměnné.
[AllowNull()] [int]$number = 7
Ověřovací atributy lze použít pro libovolnou proměnnou, nejen parametry. Můžete definovat ověřování pro libovolnou proměnnou v rámci skriptu.
Poznámka:
Při použití atributů s typovou proměnnou 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é, typ se považuje 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, je přiřazená hodnota ověřena 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.
Atribut allowNull validation
Atribut AllowNull umožňuje hodnotu povinného parametru být $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ý volá funkci, mimo danou oblast.
Následující deklarace parametru vytvoří parametr ComputerName , který přebírá jednu až pět hodnot parametrů.
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 proměnné hodnoty. PowerShell vygeneruje chybu, pokud je délka hodnoty zadaná pro parametr nebo proměnná 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 s délkou 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ává 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řciferné číslo a každá číslice musí být číslo nula až devět.
param(
[Parameter(Mandatory)]
[ValidatePattern("[0-9]{4}")]
[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 nula až devět.
[ValidatePattern("^[0-9]{4}$")] [string]$ticketID = 1111
Ověřovací atribut ValidateRange
Atribut ValidateRange určuje číselnou oblast 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.
- Nenegativní – čí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 ValidateScriptu
Atribut ValidateScript určuje skript, který se používá k ověření parametru nebo hodnoty proměnné. PowerShell předá hodnotu skriptu a vygeneruje chybu, pokud skript vrátí $false nebo pokud skript vyvolá výjimku.
Když použijete atribut ValidateScript , hodnota, která se ověřuje, je namapována 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ší 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žíváte ValidateScript, nemůžete parametru předat $null hodnotu. Když předáte hodnotu null ValidateScript nemůže ověřit argument.
Přepsání výchozí chybové zprávy
Počínaje PowerShellem 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. Součást 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 povolí dokončování tabulátoru. PowerShell vygeneruje chybu, pokud parametr nebo hodnota 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 Čokoláda, 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 ve skriptu. Například následující výsledek způsobí chybu za běhu:
param(
[ValidateSet("hello", "world")]
[string]$Message
)
$Message = "bye"
Tento příklad vrátí následující chybu za běhu:
MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.
Použití ValidateSet také umožňuje rozšíření tabulátoru hodnot pro tento parametr. Další informace najdete v tématu about_Tab_Expansion.
Dynamické hodnoty ValidateSet pomocí tříd
Třídu můžete použít k dynamickému generování hodnot pro ValidateSet za běhu. V následujícím příkladu jsou platné hodnoty pro proměnnou $Sound generovány prostřednictvím třídy s názvem SoundNames , která kontroluje tři cesty systému souborů pro dostupné zvukové soubory:
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. Pokud je $nullhodnota , PowerShell vyvolá výjimku.
Atribut ValidateNotNull je navržen tak, aby byl použit, pokud je parametr volitelný a typ není definován nebo má převaděč typů, který nemůže implicitně převést hodnotu null jako 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 atribut.
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 přiřazená hodnota nemůže být žádná z následujících hodnot:
$null- prázdný řetězec (
"") - prázdné pole (
@())
Pokud je hodnota neplatná, PowerShell vyvolá výjimku.
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. PowerShell vygeneruje chybu, pokud hodnota parametru odkazuje na jiné jednotky než povolené. Existence cesty, s výjimkou samotné jednotky, není ověřena.
Pokud používáte 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 testuje pouze existenci předpony jednotky cesty.
Pokud používáte relativní cestu, musí být Useraktuální jednotka .
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 relací JEA (Just Enough Správa istration). V tomto příkladu vytvoříme jednotku User: (Uživatel: jednotka).
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 se atribut používá interně samotným PowerShellem a není určený pro externí použití.
Viz také
Váš názor
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu: https://aka.ms/ContentUserFeedback.
Odeslat a zobrazit názory pro