about_Functions_Argument_Completion
Korte beschrijving
Voltooiing van argumenten is een functie van PowerShell die hints biedt, detectie mogelijk maakt en de invoer van argumentwaarden versnelt.
Lange beschrijving
In dit artikel worden de verschillende manieren beschreven waarop u argumentvervolledigers voor PowerShell-functies kunt implementeren. Argument completers bieden de mogelijke waarden voor een parameter. De beschikbare waarden worden berekend tijdens runtime wanneer de gebruiker op de Tab-toets drukt na de parameternaam. Er zijn verschillende manieren om een argument-completer voor een parameter te definiëren.
Notitie
Tab is de standaardsleutelbinding in Windows. Deze sleutelbinding kan worden gewijzigd door de PSReadLine-module of de toepassing die Als host fungeert voor PowerShell. De sleutelbinding is anders op niet-Windows-platforms. Zie about_PSReadLine voor meer informatie.
Kenmerk ValidateSet
Het kenmerk ValidateSet geeft een set geldige waarden op voor een parameter of variabele en maakt voltooiing van tabbladen mogelijk. PowerShell genereert een fout als een parameter of variabele waarde niet overeenkomt met een waarde in de set. In het volgende voorbeeld kan de waarde van de parameter Fruit alleen Appel, Banaan of Peer zijn.
Param(
[Parameter(Mandatory=$true)]
[ValidateSet('Apple', 'Banana', 'Pear')]
[string[]]
$Fruit
)
In het volgende voorbeeld moet de waarde van de variabele $flavorChocolade, Aardbei of Vanille zijn. Het ValidateSet kenmerk kan worden gebruikt voor elke variabele, niet alleen parameters.
[ValidateSet('Chocolate', 'Strawberry', 'Vanilla')]
[string]$flavor = 'Strawberry'
De validatie vindt plaats wanneer die variabele wordt toegewezen, zelfs binnen het script.
Param(
[ValidateSet('hello', 'world')]
[string]$Message
)
$Message = 'bye'
In dit voorbeeld wordt de volgende fout tijdens runtime geretourneerd:
MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.
Zie about_Tab_Expansion voor meer informatie over tabbladuitbreiding.
Dynamische ValidateWaarden instellen met behulp van klassen
U kunt een klasse gebruiken om de waarden voor ValidateSet tijdens runtime dynamisch te genereren. In het volgende voorbeeld worden de geldige waarden voor de variabele $Sound gegenereerd via een klasse met de naam SoundNames die drie bestandssysteempaden controleert op beschikbare geluidsbestanden:
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
}
}
De [SoundNames] klasse wordt vervolgens als volgt geïmplementeerd als een dynamische ValidateSet-waarde :
Param(
[ValidateSet([SoundNames])]
[string]$Sound
)
Notitie
De IValidateSetValuesGenerator klasse is geïntroduceerd in PowerShell 6.0.
Kenmerk ArgumentCompletions
Met het kenmerk ArgumentCompletions kunt u voltooiingswaarden voor tabbladen toevoegen aan een specifieke parameter. Er moet een ArgumentCompletions-kenmerk worden gedefinieerd voor elke parameter waarvoor tabs moeten worden voltooid. Het kenmerk ArgumentCompletions is vergelijkbaar met ValidateSet. Voor beide kenmerken wordt een lijst met waarden gebruikt die moet worden weergegeven wanneer de gebruiker op Tab drukt na de parameternaam. In tegenstelling tot ValidateSet worden de waarden echter niet gevalideerd en lijken ze meer op suggesties. Daarom kan de gebruiker elke waarde opgeven, niet alleen de waarden in de lijst.
Het kenmerk ArgumentCompletions moet niet worden verward met het kenmerk ArgumentCompleter , waarvoor een scriptblok nodig is om de opties te definiëren. de opgegeven waarden beschikbaar zijn
De syntaxis is als volgt:
function Test-ArgumentCompletions {
[CmdletBinding()]
param (
[Parameter(Mandatory=$true)]
[ArgumentCompletions('Fruits', 'Vegetables')]
$Type,
[Parameter()]
[ArgumentCompletions('Apple', 'Banana', 'Orange')]
$Fruit,
[Parameter()]
[ArgumentCompletions('Onion', 'Carrot', 'Lettuce')]
$Vegetable
)
}
Elk van de parameters krijgt een lijst met opties voor het kenmerk ArgumentCompletions om tabvoltooiing in te schakelen.
Dit kenmerk is geïntroduceerd in PowerShell 6.0.
Kenmerk ArgumentCompleter
Met het kenmerk ArgumentCompleter kunt u voltooiingswaarden voor tabbladen toevoegen aan een specifieke parameter. Er moet een ArgumentCompleter-kenmerk worden gedefinieerd voor elke parameter waarvoor tabs moeten worden voltooid.
Als u een ArgumentCompleter-kenmerk wilt toevoegen, moet u een scriptblok definiëren waarmee de waarden worden bepaald. Het scriptblok moet de volgende parameters hebben in de onderstaande volgorde. De namen van de parameter zijn niet van belang omdat de waarden positioneel worden opgegeven.
De syntaxis is als volgt:
function MyArgumentCompleter {
Param(
[Parameter(Mandatory)]
[ArgumentCompleter( {
param ( $commandName,
$parameterName,
$wordToComplete,
$commandAst,
$fakeBoundParameters )
# Perform calculation of tab completed values here.
} )]
$ParamName
)
}
ArgumentCompleter-scriptblok
De parameters voor het scriptblok zijn ingesteld op de volgende waarden:
$commandName(Positie 0) - Deze parameter is ingesteld op de naam van de opdracht waarvoor het scriptblok tabvoltooiing biedt.$parameterName(Positie 1) - Deze parameter is ingesteld op de parameter waarvan de waarde tabvoltooiing vereist.$wordToComplete(Positie 2) - Deze parameter is ingesteld op de waarde die de gebruiker heeft opgegeven voordat ze op Tab drukten. Het scriptblok moet deze waarde gebruiken om de voltooiingswaarden voor tabbladen te bepalen.$commandAst(Positie 3) - Deze parameter is ingesteld op de abstracte syntaxisstructuur (AST) voor de huidige invoerregel. Zie de documentatie over het AST-type voor meer informatie.$fakeBoundParameters(Positie 4) - Deze parameter is ingesteld op een hashtabel met de$PSBoundParametersvoor de cmdlet, voordat de gebruiker op Tab drukt. Zie about_Automatic_Variables voor meer informatie.
Het scriptblok ArgumentCompleter moet de waarden uitschrijven met behulp van de pijplijn, zoals ForEach-Object, Where-Objectof een andere geschikte methode.
Het retourneren van een matrix met waarden zorgt ervoor dat PowerShell de hele matrix als één voltooiingswaarde voor tabbladen behandelt.
In het volgende voorbeeld wordt tabvoltooiing toegevoegd aan de parameter Waarde . Als alleen de parameter Value is opgegeven, worden alle mogelijke waarden of argumenten voor Waarde weergegeven. Wanneer de parameter Type is opgegeven , geeft de waardeparameter alleen de mogelijke waarden voor dat type weer.
Bovendien zorgt de -like operator ervoor dat als de gebruiker de volgende opdracht typt en tabvoltooiing gebruikt, alleen Apple wordt geretourneerd.
Test-ArgumentCompleter -Type Fruits -Value A
function MyArgumentCompleter{
param ( $commandName,
$parameterName,
$wordToComplete,
$commandAst,
$fakeBoundParameters )
$possibleValues = @{
Fruits = @('Apple', 'Orange', 'Banana')
Vegetables = @('Onion', 'Carrot', 'Lettuce')
}
if ($fakeBoundParameters.ContainsKey('Type')) {
$possibleValues[$fakeBoundParameters.Type] | Where-Object {
$_ -like "$wordToComplete*"
}
} else {
$possibleValues.Values | ForEach-Object {$_}
}
}
function Test-ArgumentCompleter {
[CmdletBinding()]
param (
[Parameter(Mandatory=$true)]
[ValidateSet('Fruits', 'Vegetables')]
$Type,
[Parameter(Mandatory=$true)]
[ArgumentCompleter({ MyArgumentCompleter @args })]
$Value
)
}
Op klassen gebaseerde argumentvervolledigers
Vanaf PowerShell 7.2 is een nieuwe functie toegevoegd waarmee u meer algemene implementaties van geparameteriseerde argument-completers kunt definiëren.
Door af te leiden van ArgumentCompleterAttribute, is het mogelijk om algemene completers te maken die opnieuw kunnen worden gebruikt, bijvoorbeeld:
[DirectoryCompleter(ContainingFile="pswh.exe", Depth=2)]
[DateCompleter(WeekDay='Monday', From="LastYear")]
[GitCommits(Branch='release')]
De afgeleide kenmerken moeten de IArgumentCompleterFactory interface implementeren en eigenschapswaarden gebruiken om een gespecialiseerde completer te maken.
using namespace System.Collections
using namespace System.Collections.Generic
using namespace System.Management.Automation
using namespace System.Management.Automation.Language
class NumberCompleter : IArgumentCompleter {
[int] $From
[int] $To
[int] $Step
NumberCompleter([int] $from, [int] $to, [int] $step) {
if ($from -gt $to) {
throw [ArgumentOutOfRangeException]::new("from")
}
$this.From = $from
$this.To = $to
$this.Step = $step -lt 1 ? 1 : $step
}
[IEnumerable[CompletionResult]] CompleteArgument(
[string] $CommandName,
[string] $parameterName,
[string] $wordToComplete,
[CommandAst] $commandAst,
[IDictionary] $fakeBoundParameters) {
$resultList = [List[CompletionResult]]::new()
$local:to = $this.To
$local:step = $this.Step
for ($i = $this.From; $i -lt $to; $i += $step) {
$resultList.Add([CompletionResult]::new($i.ToString()))
}
return $resultList
}
}
class NumberCompletionsAttribute : ArgumentCompleterAttribute, IArgumentCompleterFactory {
[int] $From
[int] $To
[int] $Step
NumberCompletionsAttribute([int] $from, [int] $to, [int] $step) {
$this.From = $from
$this.To = $to
$this.Step = $step
}
[IArgumentCompleter] Create() { return [NumberCompleter]::new($this.From, $this.To, $this.Step) }
}
Het gebruik van PowerShell is dan:
function Add{
param(
[NumberCompletions(0, 100, 5)]
[int] $X,
[NumberCompletions(0, 100, 5)]
[int] $Y
)
$X + $Y
}
Register-ArgumentCompleter
De Register-ArgumentCompleter cmdlet registreert een aangepaste argument-completer.
Met een argument-completer kunt u dynamische tabvoltooiing bieden, tijdens runtime voor elke opdracht die u opgeeft.
Zie Register-ArgumentCompleter voor meer informatie.