about_Functions_Advanced_Parameters

Krótki opis

Objaśnienie sposobu dodawania parametrów do funkcji zaawansowanych.

Długi opis

Możesz dodać parametry do funkcji zaawansowanych, które zapisujesz, i 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ć splatting z elementem @Args , aby reprezentować parametry w poleceniu. Funkcja Splatting jest prawidłowa w przypadku prostych i zaawansowanych funkcji. 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. Funkcje zaawansowane wykonują niezmienne analizowanie wartości parametrów przez kulturę.

Natomiast 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 jest zmieniana tak, aby korzystała z ustawień niemieckich. Data sformatowana w języku 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ą analizy niezmiennej 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 przedstawiono 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ą wartości parametru. Zamiast tego przekazują wartość logiczną true-or-false przez ich obecność lub nieobecność, tak aby gdy parametr przełącznika ma wartość true i gdy jest nieobecny, ma wartość false .

Na przykład parametr Recurse parametru 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ć możliwość wyprowadzania danych wyjściowych 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 przełącznika, 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 starannie wybierz 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 wymagana jest wartość.

Zagadnienia dotyczące projektowania parametrów przełącznika

  • Parametry przełącznika nie powinny mieć wartości domyślnych. Powinny zawsze domyślnie mieć wartość 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żesz zastąpić to w atrybucie Parametr, ale spowoduje to mylenie użytkowników.

  • Parametry przełącznika powinny być zaprojektowane tak, aby ustawienie ich przenosiło polecenie z jego 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 dokonanie obowiązkowego parametru przełącznika, jest to, że konieczne jest odróżnienie zestawu parametrów.

  • Jawne ustawienie przełącznika z wartości logicznej można wykonać za pomocą -MySwitch:$boolValue polecenia 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 jest wyświetlany 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 ArgumentList polecenia cmdlet lub użyć parametru Get-CommandŚcieżka .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 przedstawiono funkcję z standardowymi parametrami o nazwie Name and Path oraz opcjonalnym parametrem dynamicznym o nazwie KeyCount. Parametr KeyCount znajduje się w ByRegistryPath zestawie parametrów Int32i ma typ . Parametr KeyCount jest dostępny w Get-Sample funkcji tylko wtedy, gdy wartość parametru Path zaczyna się od HKLM:, co wskazuje, ż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. Jeśli jednak pominięto atrybut CmdletBinding , należy go rozpoznać jako funkcję zaawansowaną, funkcja musi zawierać atrybut Parametr .

Można dodać jeden lub wiele atrybutów w każdej deklaracji parametru. Nie ma limitu liczby atrybutów, które można dodać do deklaracji parametrów.

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 było rozpoznać ją jako funkcję zaawansowaną, a nie prostą, funkcja musi mieć atrybut CmdletBinding lub atrybut Parametr albo oba te elementy.

Atrybut Parametr zawiera 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, które otaczają argument i jego wartość, muszą być zgodne z parametrem bez interweniujących 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 Parametr .

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

Typy argumentów logicznych atrybutu parametru domyślne 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 Parametr bez argumentów, jako alternatywy dla użycia atrybutu CmdletBinding nawiasy zgodne z 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.

Poniższy przykład deklaruje 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, można pominąć nazwę parametru, 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 zostanie określony, nazwa parametru lub alias nazwy parametru lub skrót, 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 której parametry są deklarowane w funkcji. Aby wyłączyć tę funkcję, ustaw wartość PositionalBinding argumentu atrybutu CmdletBinding na $False. 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

Za pomocą klasy można dynamicznie generować 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.

Zobacz też