Udostępnij za pośrednictwem

about_Functions_Advanced_Parameters

  • Artykuł

Krótki opis

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

Długi opis

Możesz dodać parametry do funkcji zaawansowanych, które piszesz, 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 .

Gdy używasz atrybutu CmdletBinding , program PowerShell automatycznie dodaje parametry wspólne. Nie można utworzyć żadnych parametrów, które używają tych samych nazw co common parameters. Aby uzyskać więcej informacji, zobacz about_CommonParameters.

Począwszy od programu PowerShell 3.0, można użyć splatting z elementem @Args , aby przedstawić parametry 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. 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ń języka niemieckiego. 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ą 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 o następujących cechach:

  • 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 jest obecny, 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 jako tablicy bajtów:

param([switch]$AsByteArray)

Parametry przełącznika są łatwe w użyciu i są preferowane w przypadku 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ą sugerować, że wartość jest wymagana.

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

  • Parametry przełącznika nie powinny mieć wartości domyślnych. Powinny one zawsze domyślnie mieć wartość false.

  • Parametry przełącznika są domyślnie wykluczane z parametrów pozycyjnych. Nawet jeśli inne parametry są niejawnie pozycyjne, parametry przełącznika nie są. Można zastąpić to 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ślnego zachowania do mniej popularnego 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 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 Get-Command ArgumentList 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 przedstawiono funkcję o standardowych parametrach o nazwie Name i Path oraz opcjonalny parametr dynamiczny o nazwie KeyCount. Parametr KeyCount znajduje się w zestawie parametrów ByRegistryPath Int32i ma typ . Parametr KeyCount jest dostępny w Get-Sample funkcji tylko wtedy, gdy wartość parametru Path zaczyna 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. Jeśli jednak pominiesz atrybut CmdletBinding , a następnie zostanie rozpoznana jako funkcja zaawansowana, funkcja musi zawierać atrybut Parametr .

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 było rozpoznać jako funkcję zaawansowaną, a nie prostą funkcję, 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 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 Parametr .

param(
    [Parameter(Argument1=value1, Argument2=value2)]
    $ParameterName
)

Typy argumentów logicznych atrybutu Parametr domyślnie mają 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, alternatywą dla używania 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.

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

Position Argument 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 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 deklarowania parametrów w funkcji. Aby wyłączyć tę funkcję, ustaw wartość PositionalBinding argumentu atrybutu CmdletBinding na $Falsewartość . Position Argument 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ślana jako liczba całkowita. Wartość pozycji 0 reprezentuje pierwszą pozycję w poleceniu, a 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 w oparciu o kolejność deklarowania parametrów. Jednak najlepszym rozwiązaniem nie jest poleganie na tym przypisaniu. Jeśli parametry mają być pozycyjne, użyj argumentu Position .

W poniższym przykładzie zadeklarowany jest 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 zestaw parametrów. Jeśli nie określono żadnego zestawu parametrów, parametr należy do wszystkich zestawów parametrów zdefiniowanych przez funkcję. 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 uwzględnić parametr w więcej niż jednym zestawie parametrów, dodaj dodatkowe atrybuty parametru .

Poniższy przykład jawnie dodaje parametr Summary do zestawów parametrów Computer i User . Parametr Summary jest opcjonalny w zestawie parametrów Computer i obowiązkowym 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).

Argument ValueFromPipeline

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.

W poniższym przykładzie zadeklarowano 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.

W poniższym przykładzie zadeklarowano parametr ComputerName, który jest obowiązkowy i akceptuje dane wejściowe z właściwości ComputerName obiektu przekazanej do funkcji za pośrednictwem potoku.

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

Rozważ implementację funkcji przy użyciu tego argumentu:

function Test-ValueFromPipelineByPropertyName{
  param(
      [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
      [string[]]$ComputerName
  )
  Write-Output -InputObject "Saw that ComputerName was '$ComputerName'"
}

Następnie pokaz potokowania obiektu z właściwością ComputerName będzie:

[pscustomobject]@{ ComputerName = "HelloWorld" } |
    Test-ValueFromPipelineByPropertyName

Saw that ComputerName was 'HelloWorld'

Uwaga

Typowany parametr, który akceptuje dane wejściowe potoku (by Value) lub (by PropertyName) umożliwia korzystanie z bloków skryptów powiązanych z opóźnieniem w parametrze.

Blok skryptu powiązania opóźnienia jest uruchamiany automatycznie podczas parametruBinding. Wynik jest powiązany z parametrem . Powiązanie delay nie działa dla parametrów zdefiniowanych jako typ ScriptBlock lub System.Object. Blok skryptu jest przekazywany bez wywoływanego. Aby uzyskać więcej informacji na temat bloków skryptów powiązanych z opóźnieniem , zobacz about_Script_Blocks.

Argument ValueFromRemainingArguments

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 Remaining , który akceptuje wszystkie pozostałe wartości parametrów, które są przesyłane do funkcji.

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 określa ciąg zawierający krótki opis parametru lub jego wartości. Jeśli uruchomisz polecenie bez obowiązkowego parametru, program PowerShell wyświetli monit o podanie danych wejściowych. Aby wyświetlić komunikat pomocy, wpisz !? monit i naciśnij Enter.

Poniższy przykład deklaruje obowiązkowy parametr ComputerName i komunikat pomocy, który wyjaśnia oczekiwaną wartość parametru.

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

Przykładowe wyjście:

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

Jeśli nie ma pomocy opartej na komentarzach dla funkcji, ten komunikat jest wyświetlany w danych wyjściowych Get-Help -Full .

Ten argument nie ma wpływu na parametry opcjonalne.

Atrybut aliasu

Atrybut Alias ustanawia alternatywną nazwę parametru. Nie ma limitu liczby aliasów, które można przypisać do parametru.

W poniższym przykładzie pokazano deklarację parametru, która dodaje aliasy CN i MachineName do obowiązkowego parametru ComputerName.

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

Atrybut poświadczeń

Atrybut Credential służy do wskazywania, że parametr akceptuje poświadczenia. W poniższym przykładzie pokazano deklarację parametru, która używa atrybutu Credential .

param(
    [Parameter()]
    [System.Management.Automation.Credential()]
    [PSCredential]$Credential
)

Atrybut eksperymentalny

Użyj atrybutu Eksperymentalne, aby zadeklarować kod jako eksperymentalny. Aby uzyskać pełny opis atrybutu, zobacz about_Experimental_Features.

Atrybut PSDefaultValue

Wartość PSDefaultValue określa wartość domyślną parametru polecenia w skrypicie. Te informacje są wyświetlane przez Get-Help polecenie cmdlet . Aby wyświetlić informacje o wartości domyślnej, funkcja musi zawierać pomoc opartą na komentarzach. Na przykład:

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

Użyj Get-Help polecenia , aby wyświetlić informacje o wartości domyślnej.

Get-Help TestDefaultValue -Parameter name

-Name <String>

    Required?                    false
    Position?                    1
    Default value                Current directory
    Accept pipeline input?       false
    Accept wildcard characters?  false

Argumenty atrybutu PSDefaultValue

Atrybut PSDefaultValue ma dwa argumenty:

  • Pomoc — ciąg opisujący wartość domyślną. Te informacje są wyświetlane przez Get-Help polecenie cmdlet .
  • Wartość — wartość domyślna parametru.

Oba argumenty są opcjonalne. Jeśli nie określisz żadnych argumentów, Get-Help zostanie wyświetlona wartość przypisana do parametru.

Atrybut PSTypeName

Nie można używać rozszerzonych nazw typów w deklaracji typu. Atrybut PSTypeName* umożliwia ograniczenie typu parametru do typu rozszerzonego.

W tym przykładzie Test-Connection polecenie cmdlet zwraca typ rozszerzony. Możesz użyć atrybutu PSTypeName , aby ograniczyć typ parametru do typu rozszerzonego.

function TestType {
    param(
        [PSTypeName('Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus')]
        [psobject]$MtuStatus
    )

    $MtuStatus
}

$mtu = Test-Connection -TargetName bing.com -MtuSize
TestType $mtu

Atrybut System.Obsolete

Użyj atrybutu System.Obsolete , aby oznaczyć parametry, które nie są już obsługiwane. Może to być przydatne, gdy chcesz usunąć parametr z funkcji, ale nie chcesz przerywać istniejących skryptów korzystających z funkcji.

Rozważmy na przykład funkcję, która ma parametr przełącznika NoTypeInformation , który kontroluje, czy informacje o typie są zawarte w danych wyjściowych. Chcesz ustawić to zachowanie jako domyślne i usunąć parametr z funkcji. Nie chcesz jednak przerywać istniejących skryptów korzystających z funkcji. Możesz oznaczyć parametr jako przestarzały i dodać komunikat wyjaśniający zmianę.

param(
    [System.Obsolete("The NoTypeInformation parameter is obsolete.")]
    [SwitchParameter]$NoTypeInformation
)

SupportsWildcards, atrybut

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 w celu obsługi danych wejściowych z symbolami wieloznacznymi. 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 tabulatora 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 Tab po nazwie parametru. Jednak w przeciwieństwie do elementu 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 parametry dynamiczne, dostępne wartości są obliczane w czasie wykonywania, gdy użytkownik naciska Tab po nazwie parametru.

Aby uzyskać więcej informacji, zobacz about_Functions_Argument_Completion.

Atrybuty sprawdzania poprawności 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 kończą się niepowodzeniem testu, zostanie wygenerowany błąd i 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.

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

Atrybuty weryfikacji można stosować do dowolnej zmiennej, a nie tylko do parametrów. Walidację dla dowolnej zmiennej w skrycie można zdefiniować.

Uwaga

W przypadku używania dowolnych atrybutów ze zmienną typową najlepszym rozwiązaniem jest zadeklarowanie atrybutu przed typem.

Jeśli zadeklarujesz typ z podziałem wiersza przed atrybutem i nazwą zmiennej, typ jest traktowany jako własna instrukcja.

[string]
[ValidateLength(1,5)] $Text = 'Okay'

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     String                                   System.Object

Jeśli zadeklarujesz atrybut weryfikacji po typie, przypisana wartość zostanie zweryfikowana przed konwersją typu, co może prowadzić do nieoczekiwanych błędów walidacji.

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

Atrybut weryfikacji AllowNull

Atrybut AllowNull zezwala na wartość obowiązkowego parametru na wartość $null. W poniższym przykładzie zadeklarowano 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żna 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
)

Atrybut weryfikacji AllowEmptyCollection

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 wywołującym funkcję znajduje się poza tym zakresem.

Następująca 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 validation attribute (Atrybut weryfikacji ValidateLength)

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 dziesięciu znaków.

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

W poniższym przykładzie wartość zmiennej $text musi mieć co najmniej jedną długość i maksymalnie dziesięć znaków.

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

ValidatePattern validation attribute (Atrybut weryfikacji validatePattern)

Atrybut ValidatePattern określa wyrażenie regularne, które jest porównywane z wartością parametru lub 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ć czterocyfrową liczbę, a każda cyfra musi być liczbą zero do dziewięciu.

param(
    [Parameter(Mandatory)]
    [ValidatePattern("[0-9]{4}")]
    [string[]]$ComputerName
)

W poniższym przykładzie wartość zmiennej $ticketID musi być dokładnie liczbą czterocyfrową, a każda cyfra musi być liczbą zero do dziewięciu.

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

ValidateRange validation attribute

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 umożliwia użycie następujących wartości:

  • Positive - Liczba większa niż zero.
  • Negative - 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 zera do dziesięciu.

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

W poniższym przykładzie wartość zmiennej $number musi być większa niż zero.

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

ValidateScript validation attribute (Atrybut weryfikacji validateScript)

Atrybut ValidateScript określa skrypt używany do weryfikowania wartości parametru lub 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ć mniejsza lub równa bieżącej dacie i godzinie.

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

Uwaga

Jeśli używasz języka ValidateScript, nie możesz przekazać $null wartości do parametru. Po przekazaniu wartości null język ValidateScript nie może zweryfikować argumentu.

Zastępowanie domyślnego komunikatu o błędzie

Począwszy od programu PowerShell 6, można zastąpić domyślny komunikat o błędzie wygenerowany, gdy określona wartość jest nieprawidłowa z argumentem ErrorMessage . Określ ciąg formatu złożonego. Składnik 0 indeksu używa wartości wejściowej. Składnik 1 indeksu używa elementu ScriptBlock używanego do sprawdzania poprawności wartości wejściowej.

W poniższym przykładzie wartość parametru EventDate musi być większa lub równa bieżącej dacie i godzinie. Jeśli wartość jest nieprawidłowa, komunikat o błędzie zgłasza, że określona data i godzina są zbyt stare.

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

Gdy określona wartość jest datą wcześniejszą, zwracany jest niestandardowy komunikat o błędzie.

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

Możesz zastosować dalsze formatowanie w ciągu przy użyciu opcjonalnych składników ciągu formatu.

W poniższym przykładzie wartość parametru EventDate musi być większa lub równa bieżącej dacie i godzinie. Jeśli wartość jest nieprawidłowa, komunikat o błędzie zgłasza, że określona data jest zbyt stara.

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

Gdy określona wartość jest datą wcześniejszą, zwracany jest niestandardowy komunikat o błędzie.

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

ValidateSet, atrybut

Atrybut ValidateSet określa zestaw prawidłowych wartości dla parametru lub zmiennej i włącza uzupełnianie kart. 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 odbywa się za każdym razem, gdy ta zmienna zostanie przypisana nawet w skry skrycie. Na przykład następujące wyniki powoduje wystąpienie błędu 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.

Użyj ValidateSet również włącz rozszerzanie tabulatora wartości dla tego parametru. Aby uzyskać więcej informacji, zobacz about_Tab_Expansion.

Dynamiczne wartości ValidateSet przy użyciu klas

Klasa umożliwia dynamiczne generowanie 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 dla 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. Gdy wartość to $null, program PowerShell zgłasza wyjątek.

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 niejawnie konwertuje 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 atrybutu ValidateNotNullOrEmpty .

W poniższym przykładzie wartość parametru ID nie może mieć wartości $null.

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

ValidateNotNullOrEmpty validation attribute (Atrybut weryfikacji ValidateNotNullOrEmpty)

Atrybut ValidateNotNullOrEmpty określa, że przypisana wartość nie może być dowolną z następujących wartości:

  • $null
  • pusty ciąg ("")
  • pusta tablica (@())

Jeśli wartość jest nieprawidłowa, program PowerShell zgłasza wyjątek.

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

ValidateNotNullOrWhiteSpace validation attribute (Atrybut weryfikacji ValidateNotNullOrWhiteSpace)

Atrybut ValidateNotNullOrWhiteSpace określa, że przypisana wartość nie może być żadną z następujących wartości:

  • $null
  • pusty ciąg ("")
  • pusta tablica @()
  • ciąg zawierający tylko znaki odstępu, takie jak tabulatory, spacje, powroty karetki i nowe linie
  • tablica zawierająca wszystkie ciągi, które są puste lub zawierają tylko znaki odstępu

Jeśli wartość jest nieprawidłowa, program PowerShell zgłasza wyjątek.

param(
    [Parameter(Mandatory)]
    [ValidateNotNullOrWhiteSpace()]
    [string[]]$UserName
)

ValidateDrive validation attribute (Weryfikowanie atrybutu 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 usługi ValidateUserDrive)

Atrybut ValidateUserDrive określa, że wartość parametru User musi być reprezentowana na dysku. Program PowerShell generuje błąd, jeśli ścieżka odwołuje się do innego dysku. Atrybut weryfikacji sprawdza tylko istnienie prefiksu 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: drive.

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

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życia zewnętrznego.

Zobacz też