Informacje o zaawansowanych parametrach funkcjiAbout Functions Advanced Parameters

Krótki opisShort description

Wyjaśnia, jak dodać parametry do funkcji zaawansowanych.Explains how to add parameters to advanced functions.

Długi opisLong description

Można dodać parametry do funkcji zaawansowanych, które należy napisać, i użyć atrybutów parametrów i argumentów, aby ograniczyć wartości parametrów, które są przesyłane przez użytkowników z parametrem.You can add parameters to the advanced functions that you write, and use parameter attributes and arguments to limit the parameter values that function users submit with the parameter.

Parametry dodawane do funkcji są dostępne dla użytkowników oprócz wspólnych parametrów, które program PowerShell automatycznie dodaje do wszystkich poleceń cmdlet i funkcji zaawansowanych.The parameters that you add to your function are available to users in addition to the common parameters that PowerShell adds automatically to all cmdlets and advanced functions. Aby uzyskać więcej informacji o typowych parametrach programu PowerShell, zobacz about_CommonParameters.For more information about the PowerShell common parameters, see about_CommonParameters.

Począwszy od programu PowerShell 3,0, można użyć korzystając z @Args do reprezentowania parametrów w poleceniu.Beginning in PowerShell 3.0, you can use splatting with @Args to represent the parameters in a command. Korzystając jest prawidłowy w funkcjach prostych i zaawansowanych.Splatting is valid on simple and advanced functions. Aby uzyskać więcej informacji, zobacz about_Functions i about_Splatting.For more information, see about_Functions and about_Splatting.

Konwersja wartości parametrówType conversion of parameter values

Podczas dostarczania ciągów jako argumentów do parametrów, które oczekują innego typu, program PowerShell niejawnie konwertuje ciągi na typ docelowy parametru.When you supply strings as arguments to parameters that expect a different type, PowerShell implicitly converts the strings to the parameter target type. Funkcje zaawansowane wykonują analizę niezmienną dla wartości parametrów.Advanced functions perform culture-invariant parsing of parameter values.

Z drugiej strony Konwersja z uwzględnieniem kultur jest wykonywana podczas wiązania parametrów dla skompilowanych poleceń cmdlet.By contrast, a culture-sensitive conversion is performed during parameter binding for compiled cmdlets.

W tym przykładzie utworzysz polecenie cmdlet i funkcję skryptu, która przyjmuje [datetime] parametr.In this example, we create a cmdlet and a script function that take a [datetime] parameter. Bieżąca kultura została zmieniona tak, aby korzystała z ustawień niemieckich.The current culture is changed to use German settings. Do parametru jest przenoszona Data w formacie niemieckim.A German-formatted date is passed to the parameter.

# 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 zależnej od kultury do konwersji ciągu.As shown above, cmdlets use culture-sensitive parsing to convert the string.

# 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 korzystają z analizy niezmiennej kultury, co powoduje następujące błędy.Advanced functions use culture-invariant parsing, which results in the following error.

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 statyczneStatic parameters

Parametry statyczne to parametry, które są zawsze dostępne w funkcji.Static parameters are parameters that are always available in the function. Większość parametrów w poleceniach cmdlet programu PowerShell i skryptach jest parametrami statycznymi.Most parameters in PowerShell cmdlets and scripts are static parameters.

W poniższym przykładzie pokazano deklarację parametru ComputerName o następującej charakterystyce:The following example shows the declaration of a ComputerName parameter that has the following characteristics:

  • Jest to obowiązkowe (wymagane).It's mandatory (required).
  • Pobiera dane wejściowe z potoku.It takes input from the pipeline.
  • Pobiera tablicę ciągów jako dane wejściowe.It takes an array of strings as input.
Param(
    [Parameter(Mandatory=$true,
    ValueFromPipeline=$true)]
    [String[]]
    $ComputerName
)

Atrybuty parametrówAttributes of parameters

W tej sekcji opisano atrybuty, które można dodać do parametrów funkcji.This section describes the attributes that you can add to function parameters.

Wszystkie atrybuty są opcjonalne.All attributes are optional. Jednak w przypadku pominięcia atrybutu CmdletBinding , który zostanie rozpoznany jako funkcja zaawansowana, funkcja musi zawierać atrybut Parameter .However, if you omit the CmdletBinding attribute, then to be recognized as an advanced function, the function must include the Parameter attribute.

Można dodać jeden lub wiele atrybutów w każdej deklaracji parametru.You can add one or multiple attributes in each parameter declaration. Nie ma żadnego limitu liczby atrybutów, które można dodać do deklaracji parametru.There's no limit to the number of attributes that you can add to a parameter declaration.

Atrybut parametruParameter attribute

Atrybut parametru służy do deklarowania atrybutów parametrów funkcji.The Parameter attribute is used to declare the attributes of function parameters.

Atrybut parametru jest opcjonalny i można go pominąć, jeśli żaden z parametrów funkcji nie wymaga atrybutów.The Parameter attribute is optional, and you can omit it if none of the parameters of your functions need attributes. Jednak, aby można było rozpoznać funkcję zaawansowaną, a nie prostą, funkcja musi mieć atrybut CmdletBinding lub atrybut lub oba te Parametry .But, to be recognized as an advanced function, rather than a simple function, a function must have either the CmdletBinding attribute or the Parameter attribute, or both.

Atrybut parametru ma argumenty, które definiują charakterystykę parametru, na przykład czy parametr jest obowiązkowy, czy opcjonalny.The Parameter attribute has arguments that define the characteristics of the parameter, such as whether the parameter is mandatory or optional.

Użyj następującej składni, aby zadeklarować atrybut Parameter , argument i wartość argumentu.Use the following syntax to declare the Parameter attribute, an argument, and an argument value. Nawiasy otaczające argument i jego wartość muszą być zgodne z parametrem bez miejsca na interwencję.The parentheses that enclose the argument and its value must follow Parameter with no intervening space.

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

Użyj przecinków, aby oddzielić argumenty w nawiasach.Use commas to separate arguments within the parentheses. Użyj następującej składni, aby zadeklarować dwa argumenty atrybutu Parameter .Use the following syntax to declare two arguments of the Parameter attribute.

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

W przypadku pominięcia z atrybutu parametru typy argumentu logicznego atrybutu parametru są domyślnie fałszywe .The boolean argument types of the Parameter attribute default to False when omitted from the Parameter attribute. Ustaw wartość argumentu na $true lub po prostu Wyświetl argument według nazwy.Set the argument value to $true or just list the argument by name. Na przykład następujące atrybuty parametrów są równoważne.For example, the following Parameter attributes are equivalent.

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, jako alternatywy dla użycia atrybutu CmdletBinding , nawiasy, które są zgodne z nazwą atrybutu, są nadal wymagane.If you use the Parameter attribute without arguments, as an alternative to using the CmdletBinding attribute, the parentheses that follow the attribute name are still required.

Param(
    [Parameter()]
    $ParameterName
)

Argument obowiązkowyMandatory argument

MandatoryArgument wskazuje, że parametr jest wymagany.The Mandatory argument indicates that the parameter is required. Jeśli ten argument nie jest określony, parametr jest opcjonalny.If this argument isn't specified, the parameter is optional.

Poniższy przykład deklaruje parametr ComputerName .The following example declares the ComputerName parameter. Używa argumentu, Mandatory Aby parametr był obowiązkowy.It uses the Mandatory argument to make the parameter mandatory.

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

Argument pozycjiPosition argument

PositionArgument określa, czy nazwa parametru jest wymagana, gdy parametr jest używany w poleceniu.The Position argument determines whether the parameter name is required when the parameter is used in a command. Gdy deklaracja parametru zawiera Position argument, można pominąć nazwę parametru, a program PowerShell zidentyfikuje wartość parametru nienazwanego przez jego pozycję lub kolejność, na liście wartości parametrów nienazwanych w poleceniu.When a parameter declaration includes the Position argument, the parameter name can be omitted and PowerShell identifies the unnamed parameter value by its position, or order, in the list of unnamed parameter values in the command.

Jeśli Position 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.If the Position argument isn't specified, the parameter name, or a parameter name alias or abbreviation, must precede the parameter value whenever the parameter is used in a command.

Domyślnie wszystkie parametry funkcji są pozycjonowane.By default, all function parameters are positional. Program PowerShell przypisuje numery pozycji do parametrów w kolejności, w jakiej parametry są zadeklarowane w funkcji.PowerShell assigns position numbers to parameters in the order in which the parameters are declared in the function. Aby wyłączyć tę funkcję, należy ustawić wartość PositionalBinding argumentu atrybutu CmdletBinding na $False .To disable this feature, set the value of the PositionalBinding argument of the CmdletBinding attribute to $False. PositionArgument ma pierwszeństwo przed wartością PositionalBinding argumentu atrybutu CmdletBinding .The Position argument takes precedence over the value of the PositionalBinding argument of the CmdletBinding attribute. Aby uzyskać więcej informacji, zobacz PositionalBinding w about_Functions_CmdletBindingAttribute.For more information, see PositionalBinding in about_Functions_CmdletBindingAttribute.

Wartość Position argumentu jest określona jako liczba całkowita.The value of the Position argument is specified as an integer. Wartość pozycji 0 oznacza pierwszą pozycję w poleceniu, wartość pozycji 1 reprezentuje drugą pozycję w poleceniu itd.A position value of 0 represents the first position in the command, a position value of 1 represents the second position in the command, and so on.

Jeśli funkcja nie ma parametrów pozycyjnych, program PowerShell przypisuje pozycje do każdego parametru w zależności od kolejności, w której są zadeklarowane parametry.If a function has no positional parameters, PowerShell assigns positions to each parameter based on the order in which the parameters are declared. Jednak najlepszym rozwiązaniem jest nie poleganie na tym przypisaniu.However, as a best practice, don't rely on this assignment. Jeśli chcesz, aby parametry były pozycyjne, użyj Position argumentu.When you want parameters to be positional, use the Position argument.

Poniższy przykład deklaruje parametr ComputerName .The following example declares the ComputerName parameter. Używa Position argumentu z wartością 0.It uses the Position argument with a value of 0. W związku z tym, gdy -ComputerName zostanie pominięty z polecenia, jego wartość musi być pierwszą lub tylko nienazwanymi parametrami w poleceniu.As a result, when -ComputerName is omitted from command, its value must be the first or only unnamed parameter value in the command.

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

ParameterSetName — argumentParameterSetName argument

ParameterSetNameArgument określa zestaw parametrów, do których należy parametr.The ParameterSetName argument specifies the parameter set to which a parameter belongs. Jeśli nie określono żadnego zestawu parametrów, parametr należy do wszystkich zestawów parametrów zdefiniowanych przez funkcję.If no parameter set is specified, the parameter belongs to all the parameter sets defined by the function. 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.Therefore, to be unique, each parameter set must have at least one parameter that isn't a member of any other parameter set.

Uwaga

W przypadku polecenia cmdlet lub funkcji istnieje limit 32 zestawów parametrów.For a cmdlet or function, there is a limit of 32 parameter sets.

Poniższy przykład deklaruje parametr ComputerName w Computer zestawie parametrów, parametr nazwy użytkownika w User zestawie parametrów i parametr podsumowania w obu zestawach parametrów.The following example declares a ComputerName parameter in the Computer parameter set, a UserName parameter in the User parameter set, and a Summary parameter in both parameter sets.

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

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

    [Parameter(Mandatory=$false)]
    [Switch]
    $Summary
)

W każdym argumencie można określić tylko jedną ParameterSetName wartość i tylko jeden ParameterSetName argument w każdym atrybucie Parameter .You can specify only one ParameterSetName value in each argument and only one ParameterSetName argument in each Parameter attribute. Aby wskazać, że parametr występuje w więcej niż jednym zestawie parametrów, Dodaj dodatkowe atrybuty parametrów .To indicate that a parameter appears in more than one parameter set, add additional Parameter attributes.

Poniższy przykład jawnie dodaje parametr podsumowania do Computer User zestawów parametrów i.The following example explicitly adds the Summary parameter to the Computer and User parameter sets. Parametr Summary jest opcjonalny w Computer zestawie parametrów i obowiązkowym w User zestawie parametrów.The Summary parameter is optional in the Computer parameter set and mandatory in the User parameter set.

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

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

    [Parameter(Mandatory=$false, ParameterSetName="Computer")]
    [Parameter(Mandatory=$true, ParameterSetName="User")]
    [Switch]
    $Summary
)

Aby uzyskać więcej informacji na temat zestawów parametrów, zobacz Informacje o zestawach parametrów.For more information about parameter sets, see About Parameter Sets.

ValueFromPipeline — argumentValueFromPipeline argument

ValueFromPipelineArgument wskazuje, że parametr akceptuje dane wejściowe z obiektu potoku.The ValueFromPipeline argument indicates that the parameter accepts input from a pipeline object. Określ ten argument, jeśli funkcja akceptuje cały obiekt, a nie tylko właściwość obiektu.Specify this argument if the function accepts the entire object, not just a property of the object.

Poniższy przykład deklaruje parametr ComputerName , który jest obowiązkowy i akceptuje obiekt, który jest przesyłany do funkcji z potoku.The following example declares a ComputerName parameter that's mandatory and accepts an object that's passed to the function from the pipeline.

Param(
    [Parameter(Mandatory=$true,
    ValueFromPipeline=$true)]
    [String[]]
    $ComputerName
)

ValueFromPipelineByPropertyName — argumentValueFromPipelineByPropertyName argument

ValueFromPipelineByPropertyNameArgument wskazuje, że parametr akceptuje dane wejściowe z właściwości obiektu potoku.The ValueFromPipelineByPropertyName argument indicates that the parameter accepts input from a property of a pipeline object. Właściwość Object musi mieć taką samą nazwę lub alias jak parametr.The object property must have the same name or alias as the parameter.

Na przykład jeśli funkcja ma parametr ComputerName , a obiekt z potokiem ma właściwość ComputerName , wartość właściwości ComputerName jest przypisywana do parametru ComputerName funkcji.For example, if the function has a ComputerName parameter, and the piped object has a ComputerName property, the value of the ComputerName property is assigned to the function's ComputerName parameter.

Poniższy przykład deklaruje parametr ComputerName , który jest obowiązkowy i akceptuje dane wejściowe z właściwości ComputerName obiektu, która jest przenoszona do funkcji za pośrednictwem potoku.The following example declares a ComputerName parameter that's mandatory and accepts input from the object's ComputerName property that's passed to the function through the pipeline.

Param(
    [Parameter(Mandatory=$true,
    ValueFromPipelineByPropertyName=$true)]
    [String[]]
    $ComputerName
)

Uwaga

Parametr z określonym typem, który akceptuje dane wejściowe potoku ( by Value ) lub ( by PropertyName ) umożliwia użycie bloków skryptu z opóźnieniem dla parametru.A typed parameter that accepts pipeline input (by Value) or (by PropertyName) enables use of delay-bind script blocks on the parameter.

Blok skryptu z opóźnieniem jest uruchamiany automatycznie podczas parametrubinding.The delay-bind script block is run automatically during ParameterBinding. Wynik jest powiązany z parametrem.The result is bound to the parameter. Opóźnienie powiązania nie działa dla parametrów zdefiniowanych jako typ ScriptBlock lub System.Object .Delay binding does not work for parameters defined as type ScriptBlock or System.Object. Blok skryptu jest przenoszona przez nie wywoływany.The script block is passed through without being invoked.

Informacje na temat bloków skryptu z opóźnieniem można znaleźć tutaj about_Script_Blocks. MD.You can read about delay-bind script blocks here about_Script_Blocks.md.

ValueFromRemainingArguments — argumentValueFromRemainingArguments argument

ValueFromRemainingArgumentsArgument wskazuje, że parametr akceptuje wszystkie wartości parametrów w poleceniu, które nie są przypisane do innych parametrów funkcji.The ValueFromRemainingArguments argument indicates that the parameter accepts all the parameter's values in the command that aren't assigned to other parameters of the function.

Poniższy przykład deklaruje parametr Value , który jest obowiązkowy, i pozostały parametr, który akceptuje wszystkie pozostałe wartości parametrów, które są przesyłane do funkcji.The following example declares a Value parameter that's mandatory and a Remaining parameter that accepts all the remaining parameter values that are submitted to the function.

function Test-Remainder
{
     param(
         [string]
         [Parameter(Mandatory = $true, 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 uruchomieniem programu PowerShell 6,2 kolekcja ValueFromRemainingArguments została dołączona jako pojedyncza jednostka pod indeksem 0.Prior to PowerShell 6.2, the ValueFromRemainingArguments collection was joined as single entity under index 0.

HelpMessage — argumentHelpMessage argument

HelpMessageArgument określa ciąg, który zawiera krótki opis parametru lub jego wartości.The HelpMessage argument specifies a string that contains a brief description of the parameter or its value. Program PowerShell wyświetla ten komunikat w monicie, który pojawia się, gdy w poleceniu brakuje obowiązkowej wartości parametru.PowerShell displays this message in the prompt that appears when a mandatory parameter value is missing from a command. Ten argument nie ma wpływu na parametry opcjonalne.This argument has no effect on optional parameters.

Poniższy przykład deklaruje obowiązkowy parametr ComputerName i komunikat pomocy, który objaśnia oczekiwaną wartość parametru.The following example declares a mandatory ComputerName parameter and a help message that explains the expected parameter value.

Jeśli nie ma żadnej 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.If there is no other comment-based help syntax for the function (for example, .SYNOPSIS) then this message also shows up in Get-Help output.

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

Atrybut aliasuAlias attribute

Atrybut aliasu ustanawia alternatywną nazwę dla parametru.The Alias attribute establishes an alternate name for the parameter. Nie ma żadnego limitu liczby aliasów, które można przypisać do parametru.There's no limit to the number of aliases that you can assign to a parameter.

W poniższym przykładzie pokazano deklarację parametru, która dodaje aliasy CN i MachineName do obowiązkowego parametru ComputerName .The following example shows a parameter declaration that adds the CN and MachineName aliases to the mandatory ComputerName parameter.

Param(
    [Parameter(Mandatory=$true)]
    [Alias("CN","MachineName")]
    [String[]]
    $ComputerName
)

SupportsWildcards — atrybutSupportsWildcards attribute

Atrybut SupportsWildcards jest używany do wskazania, że parametr akceptuje wartości symboli wieloznacznych.The SupportsWildcards attribute is used to indicate that the parameter accepts wildcard values. W poniższym przykładzie pokazano deklarację parametru dla obowiązkowego parametru ścieżki , który obsługuje wartości wieloznaczne.The following example shows a parameter declaration for a mandatory Path parameter that supports wildcard values.

Param(
    [Parameter(Mandatory=$true)]
    [SupportsWildcards()]
    [String[]]
    $Path
)

Użycie tego atrybutu nie powoduje automatycznego włączenia obsługi symboli wieloznacznych.Using this attribute does not automatically enable wildcard support. Deweloper poleceń cmdlet musi zaimplementować kod obsługujący symbole wieloznaczne.The cmdlet developer must implement the code to handle the wildcard input. Obsługiwane symbole wieloznaczne mogą się różnić w zależności od źródłowego interfejsu API lub dostawcy programu PowerShell.The wildcards supported can vary according to the underlying API or PowerShell provider. Aby uzyskać więcej informacji, zobacz about_Wildcards.For more information, see about_Wildcards.

Atrybuty walidacji parametrów i zmiennychParameter and variable validation attributes

Atrybuty walidacji bezpośrednie środowisko PowerShell do testowania wartości parametrów przesyłanych przez użytkowników po wywołaniu funkcji zaawansowanej.Validation attributes direct PowerShell to test the parameter values that users submit when they call the advanced function. W przypadku niepowodzenia testu wartości parametrów zostanie wygenerowany błąd i funkcja nie zostanie wywołana.If the parameter values fail the test, an error is generated and the function isn't called. Sprawdzanie poprawności parametru jest stosowane tylko do danych wejściowych, a inne wartości, takie jak wartości domyślne, nie są sprawdzane.Parameter validation is only applied to the input provided and any other values like default values are not validated.

Można również użyć atrybutów walidacji, aby ograniczyć wartości, które użytkownicy mogą określić dla zmiennych.You can also use the validation attributes to restrict the values that users can specify for variables. Jeśli używasz konwertera typów wraz z atrybutem walidacji, konwerter typu musi być zdefiniowany przed atrybutem.When you use a type converter along with a validation attribute, the type converter has to be defined before the attribute.

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

AllowNull — atrybut walidacjiAllowNull validation attribute

Atrybut AllowNull umożliwia wartość obowiązkowego parametru $null .The AllowNull attribute allows the value of a mandatory parameter to be $null. Poniższy przykład deklaruje parametr Hashtable ComputerInfo , który może mieć wartość null .The following example declares a hashtable ComputerInfo parameter that can have a null value.

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

Uwaga

Atrybut AllowNull nie działa, jeśli konwerter typu jest ustawiony na ciąg, ponieważ typ ciągu nie akceptuje wartości null.The AllowNull attribute doesn't work if the type converter is set to string as the string type will not accept a null value. W tym scenariuszu można użyć atrybutu AllowEmptyString .You can use the AllowEmptyString attribute for this scenario.

AllowEmptyString — atrybut walidacjiAllowEmptyString validation attribute

Atrybut AllowEmptyString umożliwia wartość obowiązkowego parametru jako pusty ciąg ( "" ).The AllowEmptyString attribute allows the value of a mandatory parameter to be an empty string (""). Poniższy przykład deklaruje parametr ComputerName , który może mieć pustą wartość ciągu.The following example declares a ComputerName parameter that can have an empty string value.

Param(
    [Parameter(Mandatory=$true)]
    [AllowEmptyString()]
    [String]
    $ComputerName
)

AllowEmptyCollection — atrybut walidacjiAllowEmptyCollection validation attribute

Atrybut AllowEmptyCollection umożliwia wartość obowiązkowego parametru jako pustą kolekcję @() .The AllowEmptyCollection attribute allows the value of a mandatory parameter to be an empty collection @(). Poniższy przykład deklaruje parametr ComputerName , który może mieć pustą wartość kolekcji.The following example declares a ComputerName parameter that can have an empty collection value.

Param(
    [Parameter(Mandatory=$true)]
    [AllowEmptyCollection()]
    [String[]]
    $ComputerName
)

ValidateCount — atrybut walidacjiValidateCount validation attribute

Atrybut ValidateCount określa minimalną i maksymalną liczbę wartości parametrów akceptowanych przez parametr.The ValidateCount attribute specifies the minimum and maximum number of parameter values that a parameter accepts. Program PowerShell generuje błąd, jeśli liczba wartości parametrów w poleceniu, które wywołuje funkcję, wykracza poza ten zakres.PowerShell generates an error if the number of parameter values in the command that calls the function is outside that range.

Następująca deklaracja parametru tworzy parametr ComputerName , który przyjmuje od 1 do pięciu wartości parametrów.The following parameter declaration creates a ComputerName parameter that takes one to five parameter values.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateCount(1,5)]
    [String[]]
    $ComputerName
)

ValidateLength — atrybut walidacjiValidateLength validation attribute

Atrybut ValidateLength określa minimalną i maksymalną liczbę znaków w wartości parametru lub zmiennej.The ValidateLength attribute specifies the minimum and maximum number of characters in a parameter or variable value. Program PowerShell generuje błąd, jeśli długość wartości określonej dla parametru lub zmiennej znajduje się poza zakresem.PowerShell generates an error if the length of a value specified for a parameter or a variable is outside of the range.

W poniższym przykładzie każda nazwa komputera musi mieć jeden do dziesięciu znaków.In the following example, each computer name must have one to ten characters.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateLength(1,10)]
    [String[]]
    $ComputerName
)

W poniższym przykładzie wartość zmiennej $number musi być co najmniej jeden znak w długości i maksymalnie 10 znaków.In the following example, the value of the variable $number must be a minimum of one character in length, and a maximum of ten characters.

[Int32][ValidateLength(1,10)]$number = '01'

Uwaga

W tym przykładzie wartość 01 jest opakowana w apostrofy.In this example, the value of 01 is wrapped in single quotes. Atrybut ValidateLength nie akceptuje liczby bez zawijania w cudzysłowie.The ValidateLength attribute won't accept a number without being wrapped in quotes.

ValidatePattern — atrybut walidacjiValidatePattern validation attribute

Atrybut ValidatePattern określa wyrażenie regularne, które jest porównywane z wartością parametru lub zmiennej.The ValidatePattern attribute specifies a regular expression that's compared to the parameter or variable value. Program PowerShell generuje błąd, jeśli wartość nie jest zgodna z wzorcem wyrażenia regularnego.PowerShell generates an error if the value doesn't match the regular expression pattern.

W poniższym przykładzie wartość parametru musi zawierać czterocyfrowy numer, a każda cyfra musi być liczbą od zera do dziewięciu.In the following example, the parameter value must contain a four-digit number, and each digit must be a number zero to nine.

Param(
    [Parameter(Mandatory=$true)]
    [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ć cyfrą od zera do dziewięciu.In the following example, the value of the variable $number must be exactly a four-digit number, and each digit must be a number zero to nine.

[Int32][ValidatePattern("^[0-9][0-9][0-9][0-9]$")]$number = 1111

ValidateRange — atrybut walidacjiValidateRange validation attribute

Atrybut ValidateRange określa zakres liczbowy lub wartość wyliczenia ValidateRangeKind dla każdego parametru lub wartości zmiennej.The ValidateRange attribute specifies a numeric range or a ValidateRangeKind enum value for each parameter or variable value. Program PowerShell generuje błąd, jeśli jakakolwiek wartość znajduje się poza tym zakresem.PowerShell generates an error if any value is outside that range.

Wyliczenie ValidateRangeKind umożliwia stosowanie następujących wartości:The ValidateRangeKind enum allows for the following values:

  • Dodatnia — liczba większa od zera.Positive - A number greater than zero.
  • Ujemna — liczba mniejsza od zera.Negative - A number less than zero.
  • Niedodatni — liczba mniejsza lub równa zero.NonPositive - A number less than or equal to zero.
  • Nieujemne — liczba większa lub równa zero.NonNegative - A number greater than or equal to zero.

W poniższym przykładzie wartość parametru próby musi należeć do zakresu od zero do dziesięciu.In the following example, the value of the Attempts parameter must be between zero and ten.

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

W poniższym przykładzie wartość zmiennej $number musi zawierać się w przedziale od zero do dziesięciu.In the following example, the value of the variable $number must be between zero and ten.

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

W poniższym przykładzie wartość zmiennej $number musi być większa od zera.In the following example, the value of the variable $number must be greater than zero.

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

ValidateScript — atrybut walidacjiValidateScript validation attribute

Atrybut ValidateScript określa skrypt, który jest używany do walidacji wartości parametru lub zmiennej.The ValidateScript attribute specifies a script that is used to validate a parameter or variable value. Program PowerShell potokuje wartość do skryptu i generuje błąd, jeśli skrypt zwróci $false lub jeśli skrypt zgłasza wyjątek.PowerShell pipes the value to the script, and generates an error if the script returns $false or if the script throws an exception.

Przy użyciu atrybutu ValidateScript wartość, która jest sprawdzana, jest mapowana na $_ zmienną.When you use the ValidateScript attribute, the value that's being validated is mapped to the $_ variable. Możesz użyć zmiennej, $_ Aby odwołać się do wartości w skrypcie.You can use the $_ variable to refer to the value in the script.

W poniższym przykładzie wartość parametru EventDate musi być większa lub równa bieżącej dacie.In the following example, the value of the EventDate parameter must be greater than or equal to the current date.

Param(
    [Parameter(Mandatory=$true)]
    [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.In the following example, the value of the variable $date must be greater than or equal to the current date and time.

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

Uwaga

Jeśli używasz ValidateScript , nie można przekazać $null wartości do parametru.If you use ValidateScript , you cannot pass a $null value to the parameter. W przypadku przekazania wartości null ValidateScript nie można zweryfikować argumentu.When you pass a null value ValidateScript can't validate the argument.

ValidateSet — atrybutValidateSet attribute

Atrybut ValidateSet określa zestaw prawidłowych wartości dla parametru lub zmiennej i włącza uzupełnianie kart.The ValidateSet attribute specifies a set of valid values for a parameter or variable and enables tab completion. Program PowerShell generuje błąd, jeśli wartość parametru lub zmiennej nie pasuje do wartości w zestawie.PowerShell generates an error if a parameter or variable value doesn't match a value in the set. W poniższym przykładzie wartość parametru detail może być tylko niska, średnia lub wysoka.In the following example, the value of the Detail parameter can only be Low, Average, or High.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateSet("Low", "Average", "High")]
    [String[]]
    $Detail
)

W poniższym przykładzie wartość zmiennej $flavor musi być czekolada, truskawka lub Wanili.In the following example, the value of the variable $flavor must be either Chocolate, Strawberry, or Vanilla.

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

Walidacja odbywa się za każdym razem, gdy ta zmienna jest przypisana nawet w skrypcie.The validation occurs whenever that variable is assigned even within the script. Na przykład następujące wyniki dotyczą błędu w czasie wykonywania:For example, the following results in an error at runtime:

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

$Message = "bye"

Dynamiczne wartości validateSetDynamic validateSet values

Można użyć klasy do dynamicznego generowania wartości dla ValidateSet w czasie wykonywania.You can use a Class to dynamically generate the values for ValidateSet at runtime. W poniższym przykładzie prawidłowe wartości dla 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:In the following example, the valid values for the variable $Sound are generated via a Class named SoundNames that checks three filesystem paths for available sound files:

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

[SoundNames]Następnie Klasa jest zaimplementowana jako dynamiczna wartość ValidateSet w następujący sposób:The [SoundNames] class is then implemented as a dynamic ValidateSet value as follows:

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

ValidateNotNull — atrybut walidacjiValidateNotNull validation attribute

Atrybut ValidateNotNull określa, że wartość parametru nie może być $null .The ValidateNotNull attribute specifies that the parameter value can't be $null. Program PowerShell generuje błąd, jeśli wartość parametru to $null .PowerShell generates an error if the parameter value is $null.

Atrybut ValidateNotNull jest przeznaczony do użycia, gdy parametr jest opcjonalny, a typ jest niezdefiniowany lub ma konwerter typu, który nie może niejawnie skonwertować wartości null like obiektu.The ValidateNotNull attribute is designed to be used when the parameter is optional and the type is undefined or has a type converter that can't implicitly convert a null value like object. Jeśli określisz typ, który niejawnie przekonwertuje wartość null, taką jak ciąg , wartość null zostanie przekonwertowana na pusty ciąg nawet przy użyciu atrybutu ValidateNotNull .If you specify a type that that will implicitly convert a null value such as a string , the null value is converted to an empty string even when using the ValidateNotNull attribute. W tym scenariuszu Użyj ValidateNotNullOrEmptyFor this scenario use the ValidateNotNullOrEmpty

W poniższym przykładzie wartość parametru ID nie może być $null .In the following example, the value of the ID parameter can't be $null.

Param(
    [Parameter(Mandatory=$false)]
    [ValidateNotNull()]
    $ID
)

ValidateNotNullOrEmpty — atrybut walidacjiValidateNotNullOrEmpty validation attribute

Atrybut ValidateNotNullOrEmpty określa, że wartość parametru nie może być $null ciągiem pustym ( "" ).The ValidateNotNullOrEmpty attribute specifies that the parameter value can't be $null and can't be an empty string (""). Program PowerShell generuje błąd, jeśli parametr jest używany w wywołaniu funkcji, ale jego wartość jest $null ciągiem pustym ( "" ) lub pustą tablicą @() .PowerShell generates an error if the parameter is used in a function call, but its value is $null, an empty string (""), or an empty array @().

Param(
    [Parameter(Mandatory=$true)]
    [ValidateNotNullOrEmpty()]
    [String[]]
    $UserName
)

ValidateDrive — atrybut walidacjiValidateDrive validation attribute

Atrybut ValidateDrive określa, że wartość parametru musi reprezentować ścieżkę, która odwołuje się tylko do dozwolonych dysków.The ValidateDrive attribute specifies that the parameter value must represent the path, that's referring to allowed drives only. Program PowerShell generuje błąd, jeśli wartość parametru odwołuje się do dysków innych niż dozwolone.PowerShell generates an error if the parameter value refers to drives other than the allowed. Istnienie ścieżki, z wyjątkiem samego dysku, nie jest weryfikowane.Existence of the path, except for the drive itself, isn't verified.

Jeśli używasz ścieżki względnej, bieżący dysk musi znajdować się na liście dozwolonych dysków.If you use relative path, the current drive must be in the allowed drive list.

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

ValidateUserDrive — atrybut walidacjiValidateUserDrive validation attribute

Atrybut ValidateUserDrive określa, że wartość parametru musi reprezentować ścieżkę, która odwołuje się do User dysku.The ValidateUserDrive attribute specifies that the parameter value must represent the path, that is referring to User drive. Program PowerShell generuje błąd, jeśli ścieżka odwołuje się do innego dysku.PowerShell generates an error if the path refers to a different drive. Atrybut walidacji sprawdza tylko obecność części dysku ścieżki.The validation attribute only tests for the existence of the drive portion of the path.

Jeśli używasz ścieżki względnej, bieżący dysk musi mieć wartość User .If you use relative path, the current drive must be 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 odpowiedniej konfiguracji sesji administracji (jea).You can define User drive in Just Enough Administration (JEA) session configurations. W tym przykładzie tworzymy użytkownika: Drive.For this example, we create the 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

```powershell
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
True

ValidateTrustedData — atrybut walidacjiValidateTrustedData validation attribute

Ten atrybut został dodany w programie PowerShell 6.1.1.This attribute was added in 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.At this time, the attribute is used internally by PowerShell itself and is not intended for external usage.

Parametry dynamiczneDynamic parameters

Parametry dynamiczne są parametrami polecenia cmdlet, funkcji lub skryptu, które są dostępne tylko w określonych warunkach.Dynamic parameters are parameters of a cmdlet, function, or script that are available only under certain conditions.

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.For example, several provider cmdlets have parameters that are available only when the cmdlet is used in the provider drive, or in a particular path of the provider drive. Na przykład parametr kodowania jest dostępny w Add-Content Get-Content poleceniach cmdlet, i, Set-Content tylko wtedy, gdy jest używany na dysku systemu plików.For example, the Encoding parameter is available on the Add-Content, Get-Content, and Set-Content cmdlets only when it's used in a file system drive.

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ść.You can also create a parameter that appears only when another parameter is used in the function command or when another parameter has a certain value.

Parametry dynamiczne mogą być przydatne, ale są używane tylko w razie potrzeby, ponieważ mogą być trudne do odnalezienia przez użytkowników.Dynamic parameters can be useful, but use them only when necessary, because they can be difficult for users to discover. Aby znaleźć parametr dynamiczny, użytkownik musi znajdować się w ścieżce dostawcy, użyć parametru listaargumentów Get-Command polecenia cmdlet lub użyć parametru Path Get-Help .To find a dynamic parameter, the user must be in the provider path, use the ArgumentList parameter of the Get-Command cmdlet, or use the Path parameter of Get-Help.

Aby utworzyć parametr dynamiczny dla funkcji lub skryptu, użyj DynamicParam słowa kluczowego.To create a dynamic parameter for a function or script, use the DynamicParam keyword.

Składnia wygląda następująco:The syntax is as follows:

DynamicParam {<statement-list>}

Na liście instrukcji Użyj If instrukcji, aby określić warunki, w których parametr jest dostępny w funkcji.In the statement list, use an If statement to specify the conditions under which the parameter is available in the function.

Użyj New-Object polecenia cmdlet, aby utworzyć obiekt System. Management. Automation. RuntimeDefinedParameter reprezentujący parametr i określić jego nazwę.Use the New-Object cmdlet to create a System.Management.Automation.RuntimeDefinedParameter object to represent the parameter and specify its name.

Możesz użyć polecenia, New-Object Aby utworzyć obiekt System. Management. Automation. ParameterAttribute do reprezentowania atrybutów parametru, takich jak obowiązkowy , Position lub ValueFromPipeline lub jego zestaw parametrów.You can use a New-Object command to create a System.Management.Automation.ParameterAttribute object to represent attributes of the parameter, such as Mandatory , Position , or ValueFromPipeline or its parameter set.

W poniższym przykładzie przedstawiono przykładową funkcję z parametrami standardowymi o nazwie name i Path oraz opcjonalnym parametrem dynamicznym o nazwie DP1.The following example shows a sample function with standard parameters named Name and Path , and an optional dynamic parameter named DP1. Parametr DP1 znajduje się w PSet1 zestawie parametrów i ma typ Int32 .The DP1 parameter is in the PSet1 parameter set and has a type of Int32. Parametr DP1 jest dostępny w Get-Sample funkcji tylko wtedy, gdy wartość parametru Path zaczyna się od HKLM: , wskazując, że jest używana na HKEY_LOCAL_MACHINE dysku rejestru.The DP1 parameter is available in the Get-Sample function only when the value of the Path parameter starts with HKLM:, indicating that it's being used in the HKEY_LOCAL_MACHINE registry drive.

function Get-Sample {
  [CmdletBinding()]
  Param([String]$Name, [String]$Path)

  DynamicParam
  {
    if ($Path.StartsWith("HKLM:"))
    {
      $attributes = New-Object -Type `
        System.Management.Automation.ParameterAttribute
      $attributes.ParameterSetName = "PSet1"
      $attributes.Mandatory = $false
      $attributeCollection = New-Object `
        -Type System.Collections.ObjectModel.Collection[System.Attribute]
      $attributeCollection.Add($attributes)

      $dynParam1 = New-Object -Type `
        System.Management.Automation.RuntimeDefinedParameter("DP1", [Int32],
          $attributeCollection)

      $paramDictionary = New-Object `
        -Type System.Management.Automation.RuntimeDefinedParameterDictionary
      $paramDictionary.Add("DP1", $dynParam1)
      return $paramDictionary
    }
  }
}

Aby uzyskać więcej informacji, zobacz RuntimeDefinedParameter.For more information, see RuntimeDefinedParameter.

Parametry przełącznikaSwitch parameters

Parametry przełącznika są parametrami bez wartości parametru.Switch parameters are parameters with no parameter value. Są one skuteczne tylko wtedy, gdy są używane i mają tylko jeden efekt.They're effective only when they're used and have only one effect.

Na przykład parametr noprofile powershell.exe jest parametrem Switch.For example, the NoProfile parameter of powershell.exe is a switch parameter.

Aby utworzyć parametr Switch w funkcji, należy określić Switch Typ w definicji parametru.To create a switch parameter in a function, specify the Switch type in the parameter definition.

Przykład:For example:

Param([Switch]<ParameterName>)

Można też użyć innej metody:Or, you can use an another method:

Param(
    [Parameter(Mandatory=$false)]
    [Switch]
    $<ParameterName>
)

Parametry przełącznika są łatwe w użyciu i są preferowane przez parametry logiczne, które mają trudniejszą składnię.Switch parameters are easy to use and are preferred over Boolean parameters, which have a more difficult syntax.

Na przykład, aby użyć parametru przełącznika, użytkownik wpisuje parametr w poleceniu.For example, to use a switch parameter, the user types the parameter in the command.

-IncludeAll

Aby użyć parametru logicznego, użytkownik wpisuje parametr i wartość logiczną.To use a Boolean parameter, the user types the parameter and a Boolean value.

-IncludeAll:$true

Podczas tworzenia parametrów przełącznika należy uważnie wybrać nazwę parametru.When creating switch parameters, choose the parameter name carefully. Upewnij się, że nazwa parametru komunikuje się z efektem parametru do użytkownika.Be sure that the parameter name communicates the effect of the parameter to the user. Unikaj niejednoznacznych warunków, takich jak Filter lub maksimum , które mogą oznaczać, że wartość jest wymagana.Avoid ambiguous terms, such as Filter or Maximum that might imply a value is required.

ArgumentCompleter — atrybutArgumentCompleter attribute

Atrybut ArgumentCompleter umożliwia dodanie wartości uzupełniania kart do określonego parametru.The ArgumentCompleter attribute allows you to add tab completion values to a specific parameter. Atrybut ArgumentCompleter musi być zdefiniowany dla każdego parametru, który wymaga zakończenia tabulacji.An ArgumentCompleter attribute must be defined for each parameter that needs tab completion. Podobnie jak w przypadku DynamicParameters , dostępne wartości są obliczane w czasie wykonywania, gdy użytkownik naciśnie klawisz Tab po nazwie parametru.Similar to DynamicParameters , the available values are calculated at runtime when the user presses Tab after the parameter name.

Aby dodać atrybut ArgumentCompleter , należy zdefiniować blok skryptu, który określa wartości.To add an ArgumentCompleter attribute, you need to define a script block that determines the values. Blok skryptu musi przyjmować następujące parametry w kolejności określonej poniżej.The script block must take the following parameters in the order specified below. Nazwy parametrów nie mają znaczenia, ponieważ wartości są podane na pozycji.The parameter's names don't matter as the values are provided positionally.

Składnia wygląda następująco:The syntax is as follows:

Param(
    [Parameter(Mandatory)]
    [ArgumentCompleter({
        param ( $commandName,
                $parameterName,
                $wordToComplete,
                $commandAst,
                $fakeBoundParameters )
        # Perform calculation of tab completed values here.
    })]
)

Blok skryptu ArgumentCompleterArgumentCompleter script block

Parametry bloku skryptu są ustawione na następujące wartości:The script block parameters are set to the following values:

  • $commandName (Pozycja 0) — ten parametr jest ustawiony na nazwę polecenia, dla którego blok skryptu zapewnia uzupełnianie karty.$commandName (Position 0) - This parameter is set to the name of the command for which the script block is providing tab completion.
  • $parameterName (Pozycja 1) — ten parametr jest ustawiony na parametr, którego wartość wymaga zakończenia karty.$parameterName (Position 1) - This parameter is set to the parameter whose value requires tab completion.
  • $wordToComplete (Pozycja 2) — ten parametr jest ustawiony na wartość dostarczoną przez użytkownika przed naciśnięciem klawisza Tab. Blok skryptu powinien używać tej wartości, aby określić wartości uzupełniania kart.$wordToComplete (Position 2) - This parameter is set to value the user has provided before they pressed Tab. Your script block should use this value to determine tab completion values.
  • $commandAst (Pozycja 3) — ten parametr jest ustawiony na drzewo składni abstrakcyjnej (AST) dla bieżącej linii wejściowej.$commandAst (Position 3) - This parameter is set to the Abstract Syntax Tree (AST) for the current input line. Aby uzyskać więcej informacji, zobacz AST Class.For more information, see Ast Class.
  • $fakeBoundParameters (Pozycja 4) — ten parametr jest ustawiany na tablicę skrótów zawierającą $PSBoundParameters dla polecenia cmdlet przed naciśnięciem klawisza Tab. Aby uzyskać więcej informacji, zobacz about_Automatic_Variables.$fakeBoundParameters (Position 4) - This parameter is set to a hashtable containing the $PSBoundParameters for the cmdlet, before the user pressed Tab. For more information, see about_Automatic_Variables.

Blok skryptu ArgumentCompleter musi odrzucić wartości przy użyciu potoku, takiego jak ForEach-Object , Where-Object lub innej odpowiedniej metody.The ArgumentCompleter script block must unroll the values using the pipeline, such as ForEach-Object, Where-Object, or another suitable method. Zwrócenie tablicy wartości powoduje, że program PowerShell traktuje całą tablicę jako jedną wartość ukończenia tabulacji.Returning an array of values causes PowerShell to treat the entire array as one tab completion value.

Poniższy przykład dodaje zakończenie tabulacji do parametru Value .The following example adds tab completion to the Value parameter. Jeśli zostanie określony tylko parametr Value , zostanie wyświetlona wartość wszystkie możliwe wartości lub argumenty.If only the Value parameter is specified, all possible values, or arguments, for Value are displayed. W przypadku określenia parametru typu wartość parametru value wyświetla tylko możliwe wartości tego typu.When the Type parameter is specified, the Value parameter only displays the possible values for that type.

Ponadto -like operator gwarantuje, że jeśli użytkownik wpisze następujące polecenie i używa kończenia karty , zwracany jest tylko Apple .In addition, the -like operator ensures that if the user types the following command and uses Tab completion, only Apple is returned.

Test-ArgumentCompleter -Type Fruits -Value A

function Test-ArgumentCompleter {
[CmdletBinding()]
 param (
        [Parameter(Mandatory=$true)]
        [ValidateSet('Fruits', 'Vegetables')]
        $Type,
        [Parameter(Mandatory=$true)]
        [ArgumentCompleter( {
            param ( $commandName,
                    $parameterName,
                    $wordToComplete,
                    $commandAst,
                    $fakeBoundParameters )

            $possibleValues = @{
                Fruits = @('Apple', 'Orange', 'Banana')
                Vegetables = @('Tomato', 'Squash', 'Corn')
            }
            if ($fakeBoundParameters.ContainsKey('Type'))
            {
                $possibleValues[$fakeBoundParameters.Type] | Where-Object {
                    $_ -like "$wordToComplete*"
                }
            }
            else
            {
                $possibleValues.Values | ForEach-Object {$_}
            }
        } )]
        $Value
      )
}

Zobacz teżSee also

about_Automatic_Variablesabout_Automatic_Variables

about_Functionsabout_Functions

about_Functions_Advancedabout_Functions_Advanced

about_Functions_Advanced_Methodsabout_Functions_Advanced_Methods

about_Functions_CmdletBindingAttributeabout_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttributeabout_Functions_OutputTypeAttribute