about_Functions_Advanced_Parameters
Krótki opis
Wyjaśnia sposób dodawania parametrów do funkcji zaawansowanych.
Długi opis
Możesz dodać parametry do zapisywanych funkcji zaawansowanych oraz użyć atrybutów parametrów i argumentów, aby ograniczyć wartości parametrów, które użytkownicy funkcji przesyłają za pomocą parametru .
Parametry dodawane do funkcji są dostępne dla użytkowników oprócz typowych parametrów, które program PowerShell dodaje automatycznie do wszystkich poleceń cmdlet i funkcji zaawansowanych. Aby uzyskać więcej informacji na temat typowych parametrów programu PowerShell, zobacz about_CommonParameters.
Począwszy od programu PowerShell 3.0, można użyć narzędzia splatting z @Args do reprezentowania parametrów w poleceniu. Splatting jest prawidłowy w prostych i zaawansowanych funkcjach. Aby uzyskać więcej informacji, zobacz about_Functions i about_Splatting.
Konwersja typów wartości parametrów
Po podaniu ciągów jako argumentów do parametrów, które oczekują innego typu, program PowerShell niejawnie konwertuje ciągi na typ docelowy parametru. Zaawansowane funkcje wykonują niezmienne analizowanie wartości parametrów przez kulturę.
Z kolei konwersja wrażliwa na kulturę jest wykonywana podczas wiązania parametrów dla skompilowanych poleceń cmdlet.
W tym przykładzie utworzymy polecenie cmdlet i funkcję skryptu, która pobiera [datetime] parametr. Bieżąca kultura została zmieniona tak, aby korzystała z ustawień języka niemieckiego.
Data w formacie niemieckim jest przekazywana do parametru .
# 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 pokazano powyżej, polecenia cmdlet używają analizy wrażliwej na kulturę, aby przekonwertować ciąg.
# 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
Funkcje zaawansowane używają niezmiennego analizowania kultury, co powoduje następujący błąd.
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."
Parametry statyczne
Parametry statyczne to parametry, które są zawsze dostępne w funkcji. Większość parametrów w poleceniach cmdlet i skryptach programu PowerShell to parametry statyczne.
W poniższym przykładzie pokazano deklarację parametru ComputerName , który ma następujące cechy:
- Jest to obowiązkowe (wymagane).
- Pobiera dane wejściowe z potoku.
- Przyjmuje tablicę ciągów jako dane wejściowe.
Param(
[Parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[string[]]
$ComputerName
)
Parametry przełącznika
Parametry przełącznika to parametry, które nie przyjmują żadnej wartości parametru. Zamiast tego przekazują wartość logiczną true-or-false przez ich obecność lub nieobecność, tak aby gdy parametr przełącznika jest obecny, ma wartość true i gdy jest nieobecny, ma wartość false .
Na przykład parametr Recurse polecenia Get-ChildItem to parametr przełącznika.
Aby utworzyć parametr przełącznika w funkcji, określ switch typ w definicji parametru.
Na przykład funkcja może mieć opcję wyprowadzania danych jako tablicy bajtów:
Param([switch]$AsByteArray)
Parametry przełącznika są łatwe w użyciu i są preferowane dla parametrów logicznych, które mają mniej naturalną składnię dla programu PowerShell.
Aby na przykład użyć parametru switch, użytkownik wpisze parametr w poleceniu .
-IncludeAll
Aby użyć parametru logicznego, użytkownik wpisze parametr i wartość logiczną.
-IncludeAll $true
Podczas tworzenia parametrów przełącznika należy dokładnie wybrać nazwę parametru. Upewnij się, że nazwa parametru komunikuje efekt parametru użytkownikowi. Unikaj niejednoznacznych terminów, takich jak Filtr lub Maksimum , które mogą oznaczać, że wartość jest wymagana.
Zagadnienia dotyczące projektowania parametrów przełącznika
Parametry przełącznika nie powinny mieć wartości domyślnych. Zawsze powinny mieć wartość domyślną false.
Parametry przełącznika są domyślnie wykluczone z parametrów pozycyjnych. Nawet jeśli inne parametry są niejawnie pozycyjne, parametry przełącznika nie są. Można to przesłonić w atrybucie Parametr, ale spowoduje to mylące użytkowników.
Parametry przełącznika powinny być zaprojektowane tak, aby ustawienie ich przenosiło polecenie z domyślnej funkcjonalności do mniej wspólnego lub bardziej skomplikowanego trybu. Najprostszym zachowaniem polecenia powinno być zachowanie domyślne, które nie wymaga użycia parametrów przełącznika.
Parametry przełącznika nie powinny być obowiązkowe. Jedynym przypadkiem, w którym konieczne jest wprowadzenie parametru przełącznika jako obowiązkowego, jest wtedy, gdy jest to konieczne do odróżnienia zestawu parametrów.
Jawne ustawienie przełącznika z wartości logicznej można wykonać za pomocą
-MySwitch:$boolValuepolecenia i wplatanie za pomocą$params = @{ MySwitch = $boolValue }polecenia .Parametry przełącznika są typu
SwitchParameter, który niejawnie konwertuje na wartość logiczną. Zmienna parametru może być używana bezpośrednio w wyrażeniu warunkowym. Na przykład:if ($MySwitch) { ... }Nie ma potrzeby pisania
if ($MySwitch.IsPresent) { ... }
Parametry dynamiczne
Parametry dynamiczne to parametry polecenia cmdlet, funkcji lub skryptu, które są dostępne tylko w określonych warunkach.
Na przykład kilka poleceń cmdlet dostawcy ma parametry, które są dostępne tylko wtedy, gdy polecenie cmdlet jest używane na dysku dostawcy lub w określonej ścieżce dysku dostawcy. Na przykład parametr Kodowanie jest dostępny w Add-Contentpoleceniach cmdlet , Get-Contenti Set-Content tylko wtedy, gdy jest używany na dysku systemu plików.
Można również utworzyć parametr, który pojawia się tylko wtedy, gdy inny parametr jest używany w poleceniu funkcji lub gdy inny parametr ma określoną wartość.
Parametry dynamiczne mogą być przydatne, ale należy ich używać tylko wtedy, gdy jest to konieczne, ponieważ mogą być trudne do odnalezienia przez użytkowników. Aby znaleźć parametr dynamiczny, użytkownik musi znajdować się w ścieżce dostawcy, użyć parametru Get-CommandArgumentList polecenia cmdlet lub użyć parametru Path polecenia Get-Help.
Aby utworzyć parametr dynamiczny dla funkcji lub skryptu, użyj słowa kluczowego DynamicParam .
Składnia wygląda następująco:
dynamicparam {<statement-list>}
Na liście instrukcji użyj if instrukcji , aby określić warunki, w których parametr jest dostępny w funkcji.
W poniższym przykładzie pokazano funkcję z standardowymi parametrami o nazwie Name i Path oraz opcjonalnym parametrem dynamicznym o nazwie KeyCount. Parametr KeyCount znajduje się w zestawie parametrów ByRegistryPathInt32i ma typ . Parametr KeyCount jest dostępny w Get-Sample funkcji tylko wtedy, gdy wartość parametru Path rozpoczyna się od HKLM:, wskazując, że jest używany na HKEY_LOCAL_MACHINE dysku rejestru.
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
}
}
}
Aby uzyskać więcej informacji, zobacz dokumentację typu RuntimeDefinedParameter .
Atrybuty parametrów
W tej sekcji opisano atrybuty, które można dodać do parametrów funkcji.
Wszystkie atrybuty są opcjonalne. Jednak w przypadku pominięcia atrybutu CmdletBinding , aby można było go rozpoznać jako funkcję zaawansowaną, funkcja musi zawierać atrybut Parameter .
W każdej deklaracji parametru można dodać jeden lub wiele atrybutów. Nie ma limitu liczby atrybutów, które można dodać do deklaracji parametru.
Atrybut parametru
Atrybut Parametr służy do deklarowania atrybutów parametrów funkcji.
Atrybut Parametr jest opcjonalny i można go pominąć, jeśli żaden z parametrów funkcji nie potrzebuje atrybutów. Jednak aby można je było rozpoznać jako funkcję zaawansowaną, a nie prostą, funkcja musi mieć atrybut CmdletBinding lub atrybut Parameter albo oba te elementy.
Atrybut Parametr ma argumenty definiujące cechy parametru, takie jak to, czy parametr jest obowiązkowy, czy opcjonalny.
Użyj następującej składni, aby zadeklarować atrybut Parametr , argument i wartość argumentu. Nawiasy otaczające argument i jego wartość muszą być zgodne z parametrem bez interweniowania spacji.
Param(
[Parameter(Argument=value)]
$ParameterName
)
Użyj przecinków, aby oddzielić argumenty w nawiasach. Użyj następującej składni, aby zadeklarować dwa argumenty atrybutu Parameter .
Param(
[Parameter(Argument1=value1,
Argument2=value2)]
)
Typy argumentów logicznych atrybutu Parametr domyślnie ma wartość False po pominięciu z atrybutu Parametr . Ustaw wartość argumentu na $true lub po prostu wyświetl argument według nazwy. Na przykład następujące atrybuty parametru są równoważne.
Param(
[Parameter(Mandatory=$true)]
)
# Boolean arguments can be defined using this shorthand syntax
Param(
[Parameter(Mandatory)]
)
Jeśli używasz atrybutu Parameter bez argumentów, alternatywą dla używania atrybutu CmdletBinding , nawiasy, które podążają za nazwą atrybutu, są nadal wymagane.
Param(
[Parameter()]
$ParameterName
)
Argument obowiązkowy
Argument Mandatory wskazuje, że parametr jest wymagany. Jeśli ten argument nie zostanie określony, parametr jest opcjonalny.
W poniższym przykładzie zadeklarowany jest parametr ComputerName . Używa argumentu Mandatory , aby parametr był obowiązkowy.
Param(
[Parameter(Mandatory)]
[string[]]
$ComputerName
)
Argument pozycji
Argument Position określa, czy nazwa parametru jest wymagana, gdy parametr jest używany w poleceniu. Gdy deklaracja parametru Position zawiera argument, nazwę parametru można pominąć, a program PowerShell identyfikuje nienazwaną wartość parametru według jego pozycji lub kolejności na liście nienazwanych wartości parametrów w poleceniu.
Position Jeśli argument nie jest określony, nazwa parametru lub alias lub skrót nazwy parametru, musi poprzedzać wartość parametru za każdym razem, gdy parametr jest używany w poleceniu.
Domyślnie wszystkie parametry funkcji są pozycyjne. Program PowerShell przypisuje numery pozycji do parametrów w kolejności, w jakiej parametry są deklarowane w funkcji. Aby wyłączyć tę funkcję, ustaw wartość PositionalBinding argumentu atrybutu CmdletBinding na $Falsewartość . Argument Position ma pierwszeństwo przed wartością PositionalBinding argumentu atrybutu CmdletBinding . Aby uzyskać więcej informacji, zobacz PositionalBinding w about_Functions_CmdletBindingAttribute.
Wartość argumentu Position jest określona jako liczba całkowita. Wartość pozycji 0 reprezentuje pierwszą pozycję w poleceniu, wartość pozycji 1 reprezentuje drugą pozycję w poleceniu itd.
Jeśli funkcja nie ma parametrów pozycyjnych, program PowerShell przypisuje pozycje do każdego parametru na podstawie kolejności deklarowanej parametrów.
Jednak najlepszym rozwiązaniem nie jest poleganie na tym przypisaniu. Jeśli chcesz, aby parametry mają być pozycyjne, użyj argumentu Position .
Poniższy przykład deklaruje parametr ComputerName . Używa argumentu Position z wartością 0. W związku z tym, gdy -ComputerName zostanie pominięty z polecenia, jego wartość musi być pierwszą lub tylko nienazwaną wartością parametru w poleceniu.
Param(
[Parameter(Position=0)]
[string[]]
$ComputerName
)
Argument ParameterSetName
Argument ParameterSetName określa parametr, do którego należy parametr. Jeśli nie określono żadnego zestawu parametrów, parametr należy do wszystkich zestawów parametrów zdefiniowanych przez funkcję. W związku z tym, aby był unikatowy, każdy zestaw parametrów musi mieć co najmniej jeden parametr, który nie jest elementem członkowskim żadnego innego zestawu parametrów.
Uwaga
W przypadku polecenia cmdlet lub funkcji istnieje limit 32 zestawów parametrów.
Poniższy przykład deklaruje parametr ComputerName w Computer zestawie parametrów, parametr UserName w User zestawie parametrów i parametr Podsumowanie w obu zestawach parametrów.
Param(
[Parameter(Mandatory,
ParameterSetName="Computer")]
[string[]]
$ComputerName,
[Parameter(Mandatory,
ParameterSetName="User")]
[string[]]
$UserName,
[Parameter()]
[switch]
$Summary
)
W każdym argumencie można określić tylko jedną ParameterSetName wartość i tylko jeden ParameterSetName argument w każdym atrybucie Parametr . Aby wskazać, że parametr pojawia się w więcej niż jednym zestawie parametrów, dodaj dodatkowe atrybuty parametru .
Poniższy przykład jawnie dodaje parametr Podsumowanie do zestawów parametrów Computer i User . Parametr Podsumowanie jest opcjonalny w zestawie parametrów Computer i obowiązkowy w zestawie parametrów User .
Param(
[Parameter(Mandatory,
ParameterSetName="Computer")]
[string[]]
$ComputerName,
[Parameter(Mandatory,
ParameterSetName="User")]
[string[]]
$UserName,
[Parameter(ParameterSetName="Computer")]
[Parameter(Mandatory, ParameterSetName="User")]
[switch]
$Summary
)
Aby uzyskać więcej informacji na temat zestawów parametrów, zobacz About Parameter Sets (Informacje o zestawach parametrów).
ValueFromPipeline, argument
Argument ValueFromPipeline wskazuje, że parametr akceptuje dane wejściowe z obiektu potoku. Określ ten argument, jeśli funkcja akceptuje cały obiekt, a nie tylko właściwość obiektu.
Poniższy przykład deklaruje parametr ComputerName , który jest obowiązkowy i akceptuje obiekt przekazany do funkcji z potoku.
Param(
[Parameter(Mandatory,
ValueFromPipeline)]
[string[]]
$ComputerName
)
ValueFromPipelineByPropertyName, argument
Argument ValueFromPipelineByPropertyName wskazuje, że parametr akceptuje dane wejściowe z właściwości obiektu potoku. Właściwość obiektu musi mieć taką samą nazwę lub alias jak parametr .
Jeśli na przykład funkcja ma parametr ComputerName , a obiekt potokowy ma właściwość ComputerName , wartość właściwości ComputerName jest przypisana do parametru ComputerName funkcji.
Poniższy przykład deklaruje parametr ComputerName , który jest obowiązkowy i akceptuje dane wejściowe z właściwości ComputerName obiektu przekazanej do funkcji przez potok.
Param(
[Parameter(Mandatory,
ValueFromPipelineByPropertyName)]
[string[]]
$ComputerName
)
Uwaga
Typowany parametr, który akceptuje dane wejściowe potoku (by Value) lub (by PropertyName) umożliwia używanie bloków skryptów powiązanych z opóźnieniem w parametrze.
Blok skryptu powiązania opóźnienia jest uruchamiany automatycznie podczas parametrówBinding. Wynik jest powiązany z parametrem. Powiązanie opóźnienia nie działa dla parametrów zdefiniowanych jako typ ScriptBlock lub System.Object. Blok skryptu jest przekazywany bez wywoływana.
Więcej informacji na temat bloków skryptów powiązania opóźnienia można znaleźć tutaj about_Script_Blocks.md.
ValueFromRemainingArguments argument
Argument ValueFromRemainingArguments wskazuje, że parametr akceptuje wszystkie wartości parametru w poleceniu, które nie są przypisane do innych parametrów funkcji.
W poniższym przykładzie zadeklarowany jest parametr Value , który jest obowiązkowy i parametr Pozostały , który akceptuje wszystkie pozostałe wartości parametrów przesyłane do funkcji.
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
Uwaga
Przed programem PowerShell 6.2 kolekcja ValueFromRemainingArguments została dołączona jako pojedyncza jednostka w indeksie 0.
Argument HelpMessage
Argument HelpMessage określa ciąg zawierający krótki opis parametru lub jego wartości. Program PowerShell wyświetla ten komunikat w wierszu polecenia, który pojawia się, gdy w poleceniu brakuje obowiązkowej wartości parametru. Ten argument nie ma wpływu na parametry opcjonalne.
Poniższy przykład deklaruje obowiązkowy parametr ComputerName i komunikat pomocy, który wyjaśnia oczekiwaną wartość parametru.
Jeśli nie ma innej składni pomocy opartej na komentarzach dla funkcji (na przykład .SYNOPSIS), ten komunikat jest również wyświetlany w Get-Help danych wyjściowych.
Param(
[Parameter(Mandatory,
HelpMessage="Enter one or more computer names separated by commas.")]
[string[]]
$ComputerName
)
Atrybut Alias
Atrybut Alias ustanawia alternatywną nazwę parametru. Nie ma limitu liczby aliasów, które można przypisać do parametru.
W poniższym przykładzie przedstawiono deklarację parametru, która dodaje aliasy CN i MachineName do obowiązkowego parametru ComputerName .
Param(
[Parameter(Mandatory)]
[Alias("CN","MachineName")]
[string[]]
$ComputerName
)
Atrybut SupportsWildcards
Atrybut SupportsWildcards służy do wskazywania, że parametr akceptuje wartości wieloznaczne. W poniższym przykładzie przedstawiono deklarację parametru dla obowiązkowego parametru Path , który obsługuje wartości wieloznaczne.
Param(
[Parameter(Mandatory)]
[SupportsWildcards()]
[string[]]
$Path
)
Użycie tego atrybutu nie powoduje automatycznego włączenia obsługi symboli wieloznacznych. Deweloper poleceń cmdlet musi zaimplementować kod do obsługi danych wejściowych symboli wieloznacznych. Obsługiwane symbole wieloznaczne mogą się różnić w zależności od bazowego interfejsu API lub dostawcy programu PowerShell. Aby uzyskać więcej informacji, zobacz about_Wildcards.
Atrybuty uzupełniania argumentów
Atrybut ArgumentCompletions
Atrybut ArgumentCompletions umożliwia dodawanie wartości uzupełniania tabulacji do określonego parametru. Atrybut ArgumentCompletions musi być zdefiniowany dla każdego parametru, który wymaga ukończenia karty. Atrybut ArgumentCompletions jest podobny do ValidateSet. Oba atrybuty przyjmują listę wartości, które mają być prezentowane, gdy użytkownik naciska klawisz Tab po nazwie parametru. Jednak w przeciwieństwie do funkcji ValidateSet wartości nie są weryfikowane.
Ten atrybut został wprowadzony w programie PowerShell 6.0.
Aby uzyskać więcej informacji, zobacz about_Functions_Argument_Completion.
ArgumentCompleter, atrybut
Atrybut ArgumentCompleter umożliwia dodawanie wartości uzupełniania tabulacji do określonego parametru. Atrybut ArgumentCompleter musi być zdefiniowany dla każdego parametru, który wymaga ukończenia karty. Podobnie jak DynamicParameters, dostępne wartości są obliczane w czasie wykonywania, gdy użytkownik naciska klawisz Tab po nazwie parametru.
Aby uzyskać więcej informacji, zobacz about_Functions_Argument_Completion.
Atrybuty weryfikacji parametrów i zmiennych
Atrybuty weryfikacji kierują program PowerShell do testowania wartości parametrów przesyłanych przez użytkowników podczas wywoływania funkcji zaawansowanej. Jeśli wartości parametrów nie powiedzą się testowi, zostanie wygenerowany błąd, a funkcja nie zostanie wywołana. Walidacja parametru jest stosowana tylko do podanych danych wejściowych, a wszystkie inne wartości, takie jak wartości domyślne, nie są weryfikowane.
Możesz również użyć atrybutów weryfikacji, aby ograniczyć wartości, które użytkownicy mogą określić dla zmiennych. W przypadku używania konwertera typów wraz z atrybutem weryfikacji przed atrybutem należy zdefiniować konwerter typów.
[int32][AllowNull()] $number = 7
Uwaga
Atrybuty weryfikacji można zastosować do dowolnej zmiennej, a nie tylko parametrów. Możesz zdefiniować walidację dla dowolnej zmiennej w skrycie.
AllowNull validation attribute (Atrybut weryfikacji allowNull)
Atrybut AllowNull umożliwia wartość obowiązkowego parametru na wartość $null. Poniższy przykład deklaruje parametr ComputerInfo w formie skrótu, który może mieć wartość null .
Param(
[Parameter(Mandatory)]
[AllowNull()]
[hashtable]
$ComputerInfo
)
Uwaga
Atrybut AllowNull nie działa, jeśli konwerter typów jest ustawiony na ciąg, ponieważ typ ciągu nie zaakceptuje wartości null. W tym scenariuszu możesz użyć atrybutu AllowEmptyString .
AllowEmptyString, atrybut weryfikacji
Atrybut AllowEmptyString umożliwia wartość obowiązkowego parametru jako pusty ciąg (""). Poniższy przykład deklaruje parametr ComputerName , który może mieć pustą wartość ciągu.
Param(
[Parameter(Mandatory)]
[AllowEmptyString()]
[string]
$ComputerName
)
AllowEmptyCollection , atrybut weryfikacji
Atrybut AllowEmptyCollection umożliwia wartość obowiązkowego parametru jako pustą kolekcję @(). Poniższy przykład deklaruje parametr ComputerName , który może mieć pustą wartość kolekcji.
Param(
[Parameter(Mandatory)]
[AllowEmptyCollection()]
[string[]]
$ComputerName
)
ValidateCount, atrybut weryfikacji
Atrybut ValidateCount określa minimalną i maksymalną liczbę wartości parametrów akceptowanych przez parametr. Program PowerShell generuje błąd, jeśli liczba wartości parametrów w poleceniu, które wywołuje funkcję, znajduje się poza tym zakresem.
Poniższa deklaracja parametru tworzy parametr ComputerName , który przyjmuje od jednego do pięciu wartości parametrów.
Param(
[Parameter(Mandatory)]
[ValidateCount(1,5)]
[string[]]
$ComputerName
)
ValidateLength, atrybut weryfikacji
Atrybut ValidateLength określa minimalną i maksymalną liczbę znaków w wartości parametru lub zmiennej. Program PowerShell generuje błąd, jeśli długość wartości określonej dla parametru lub zmiennej znajduje się poza zakresem.
W poniższym przykładzie każda nazwa komputera musi mieć od jednego do dziesięciu znaków.
Param(
[Parameter(Mandatory)]
[ValidateLength(1,10)]
[string[]]
$ComputerName
)
W poniższym przykładzie wartość zmiennej $number musi mieć co najmniej jedną długość i maksymalnie dziesięć znaków.
[Int32][ValidateLength(1,10)]$number = '01'
Uwaga
W tym przykładzie wartość 01 jest owinięta w apostrofy. Atrybut ValidateLength nie akceptuje liczby bez zawijania cudzysłowów.
ValidatePattern validation attribute (Atrybut weryfikacji ValidatePattern)
Atrybut ValidatePattern określa wyrażenie regularne, które jest porównywane z parametrem lub wartością zmiennej. Program PowerShell generuje błąd, jeśli wartość nie jest zgodna ze wzorcem wyrażenia regularnego.
W poniższym przykładzie wartość parametru musi zawierać liczbę czterocyfrową, a każda cyfra musi być liczbą zero do dziewięciu.
Param(
[Parameter(Mandatory)]
[ValidatePattern("[0-9][0-9][0-9][0-9]")]
[string[]]
$ComputerName
)
W poniższym przykładzie wartość zmiennej $number musi być dokładnie liczbą czterocyfrową, a każda cyfra musi być liczbą zero do dziewięciu.
[Int32][ValidatePattern("^[0-9][0-9][0-9][0-9]$")]$number = 1111
ValidateRange validation attribute (Atrybut weryfikacji ValidateRange)
Atrybut ValidateRange określa zakres liczbowy lub wartość wyliczenia ValidateRangeKind dla każdego parametru lub wartości zmiennej. Program PowerShell generuje błąd, jeśli jakakolwiek wartość znajduje się poza tym zakresem.
Wyliczenie ValidateRangeKind zezwala na następujące wartości:
- Dodatni — liczba większa niż zero.
- Ujemna — liczba mniejsza niż zero.
- NonPositive — liczba mniejsza lub równa zero.
- NonNegative — liczba większa lub równa zero.
W poniższym przykładzie wartość parametru Próby musi należeć do zera do dziesięciu.
Param(
[Parameter(Mandatory)]
[ValidateRange(0,10)]
[Int]
$Attempts
)
W poniższym przykładzie wartość zmiennej $number musi należeć do zakresu od zera do dziesięciu.
[Int32][ValidateRange(0,10)]$number = 5
W poniższym przykładzie wartość zmiennej $number musi być większa niż zero.
[Int32][ValidateRange("Positive")]$number = 1
ValidateScript validation attribute (Atrybut weryfikacji kodu ValidateScript)
Atrybut ValidateScript określa skrypt, który jest używany do sprawdzania poprawności parametru lub wartości zmiennej. Program PowerShell potokuje wartość skryptu i generuje błąd, jeśli skrypt zwróci $false błąd lub jeśli skrypt zgłosi wyjątek.
W przypadku używania atrybutu ValidateScript wartość, która jest weryfikowana, jest mapowana na zmienną $_ . Możesz użyć zmiennej $_ , aby odwołać się do wartości w skry skrycie.
W poniższym przykładzie wartość parametru EventDate musi być większa lub równa bieżącej dacie.
Param(
[Parameter(Mandatory)]
[ValidateScript({$_ -ge (Get-Date)})]
[DateTime]
$EventDate
)
W poniższym przykładzie wartość zmiennej $date musi być większa lub równa bieżącej dacie i godzinie.
[DateTime][ValidateScript({$_ -ge (Get-Date)})]$date = (Get-Date)
Uwaga
Jeśli używasz języka ValidateScript, nie można przekazać $null wartości do parametru. Po przekazaniu wartości null ValidateScript nie można zweryfikować argumentu.
ValidateSet, atrybut
Atrybut ValidateSet określa zestaw prawidłowych wartości dla parametru lub zmiennej i włącza uzupełnianie tabulacji. Program PowerShell generuje błąd, jeśli wartość parametru lub zmiennej nie jest zgodna z wartością w zestawie. W poniższym przykładzie wartość parametru Detail może być tylko niska, średnia lub wysoka.
Param(
[Parameter(Mandatory)]
[ValidateSet("Low", "Average", "High")]
[string[]]
$Detail
)
W poniższym przykładzie wartość zmiennej $flavor musi być czekoladowa, truskawkowa lub waniliowa.
[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[string]$flavor = "Strawberry"
Walidacja jest wykonywana za każdym razem, gdy ta zmienna zostanie przypisana nawet w skry skrycie. Na przykład następujące wyniki powoduje błąd w czasie wykonywania:
Param(
[ValidateSet("hello", "world")]
[string]$Message
)
$Message = "bye"
Ten przykład zwraca następujący błąd w czasie wykonywania:
MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.
Za pomocą polecenia ValidateSet włącz również rozszerzanie wartości tabulacji dla tego parametru. Aby uzyskać więcej informacji, zobacz about_Tab_Expansion.
Dynamiczne wartości ValidateSet przy użyciu klas
Możesz użyć klasy , aby dynamicznie wygenerować wartości elementu ValidateSet w czasie wykonywania. W poniższym przykładzie prawidłowe wartości zmiennej $Sound są generowane za pośrednictwem klasy o nazwie SoundNames , która sprawdza trzy ścieżki systemu plików pod kątem dostępnych plików dźwiękowych:
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
}
}
Klasa [SoundNames] jest następnie implementowana jako dynamiczna wartość ValidateSet w następujący sposób:
Param(
[ValidateSet([SoundNames])]
[string]$Sound
)
Uwaga
Klasa została wprowadzona IValidateSetValuesGenerator w programie PowerShell 6.0
ValidateNotNull validation attribute (Atrybut weryfikacji ValidateNotNull)
Atrybut ValidateNotNull określa, że wartość parametru nie może być $null. Program PowerShell generuje błąd, jeśli wartość parametru to $null.
Atrybut ValidateNotNull jest przeznaczony do użycia, gdy parametr jest opcjonalny, a typ jest niezdefiniowany lub ma konwerter typów, który nie może niejawnie przekonwertować wartości null, takiej jak obiekt. Jeśli określisz typ, który będzie niejawnie konwertować wartość null, taką jak ciąg, wartość null jest konwertowana na pusty ciąg nawet w przypadku używania atrybutu ValidateNotNull . W tym scenariuszu użyj elementu ValidateNotNullOrEmpty
W poniższym przykładzie wartość parametru ID nie może mieć wartości $null.
Param(
[Parameter()]
[ValidateNotNull()]
$ID
)
ValidateNotNullOrEmpty, atrybut weryfikacji
Atrybut ValidateNotNullOrEmpty określa, że wartość parametru nie może być $null i nie może być pustym ciągiem (""). Program PowerShell generuje błąd, jeśli parametr jest używany w wywołaniu funkcji, ale jego wartość to $null, pusty ciąg ("") lub pusta tablica @().
Param(
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string[]]
$UserName
)
ValidateDrive validation attribute (Atrybut weryfikacji usługi ValidateDrive)
Atrybut ValidateDrive określa, że wartość parametru musi reprezentować ścieżkę, która odnosi się tylko do dozwolonych dysków. Program PowerShell generuje błąd, jeśli wartość parametru odwołuje się do dysków innych niż dozwolone. Istnienie ścieżki, z wyjątkiem samego dysku, nie jest weryfikowane.
Jeśli używasz ścieżki względnej, bieżący dysk musi znajdować się na liście dozwolonych dysków.
Param(
[ValidateDrive("C", "D", "Variable", "Function")]
[string]$Path
)
ValidateUserDrive validation attribute (Weryfikowanie atrybutu weryfikacji elementuUserDrive)
Atrybut ValidateUserDrive określa, że wartość parametru musi reprezentować ścieżkę, która odwołuje się do User dysku. Program PowerShell generuje błąd, jeśli ścieżka odwołuje się do innego dysku. Atrybut weryfikacji sprawdza tylko istnienie części dysku ścieżki.
Jeśli używasz ścieżki względnej, bieżący dysk musi mieć wartość 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.
Dysk można zdefiniować User w konfiguracjach sesji just enough administration (JEA). W tym przykładzie utworzymy dysk 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
ValidateTrustedData validation attribute (Atrybut weryfikacji ValidateTrustedData)
Ten atrybut został dodany w programie PowerShell 6.1.1.
W tej chwili atrybut jest używany wewnętrznie przez program PowerShell i nie jest przeznaczony do użytku zewnętrznego.