about_Functions_Argument_Completion
Descrizione breve
Il completamento degli argomenti è una funzionalità di PowerShell che fornisce hint, abilita l'individuazione e accelera l'immissione di input dei valori degli argomenti.
Descrizione lunga
Questo articolo descrive i diversi modi in cui è possibile implementare i completer di argomenti per le funzioni di PowerShell. I completer di argomenti forniscono i valori possibili per un parametro. I valori disponibili vengono calcolati in fase di esecuzione quando l'utente preme tabulazioni dopo il nome del parametro. Esistono diversi modi per definire un completore di argomenti per un parametro.
Nota
Tab è l'associazione di tasti predefinita in Windows. Questo tasto di scelta rapida può essere modificato dal modulo PSReadLine o dall'applicazione che ospita PowerShell. Il tasto di scelta rapida è diverso nelle piattaforme non Windows. Per altre informazioni, vedere about_PSReadLine.
Attributo ValidateSet
L'attributo ValidateSet specifica un set di valori validi per un parametro o una variabile e abilita il completamento della scheda. PowerShell genera un errore se un parametro o un valore di variabile non corrisponde a un valore nel set. Nell'esempio seguente il valore del parametro Fruit può essere solo Apple, Banana o Pear.
Param(
[Parameter(Mandatory=$true)]
[ValidateSet('Apple', 'Banana', 'Pear')]
[string[]]
$Fruit
)
Nell'esempio seguente il valore della variabile $flavor deve essere Chocolate, Strawberry o Vanilla. L'attributo ValidateSet può essere usato in qualsiasi variabile, non solo in parametri.
[ValidateSet('Chocolate', 'Strawberry', 'Vanilla')]
[string]$flavor = 'Strawberry'
La convalida viene eseguita ogni volta che tale variabile viene assegnata anche all'interno dello script.
Param(
[ValidateSet('hello', 'world')]
[string]$Message
)
$Message = 'bye'
In questo esempio viene restituito l'errore seguente in fase di esecuzione:
MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.
Per altre informazioni sull'espansione delle schede, vedere about_Tab_Expansion.
Valori ValidateSet dinamici che usano classi
È possibile usare una classe per generare dinamicamente i valori per ValidateSet in fase di esecuzione. Nell'esempio seguente i valori validi per la variabile $Sound vengono generati tramite una classe denominata SoundNames che controlla tre percorsi del file system per i file audio disponibili:
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
}
}
La [SoundNames] classe viene quindi implementata come valore ValidateSet dinamico come segue:
Param(
[ValidateSet([SoundNames])]
[string]$Sound
)
Nota
La IValidateSetValuesGenerator classe è stata introdotta in PowerShell 6.0.
Attributo ArgumentCompletions
L'attributo ArgumentCompletions consente di aggiungere valori di completamento tramite tabulazione a un parametro specifico. È necessario definire un attributo ArgumentCompletions per ogni parametro che richiede il completamento della scheda. L'attributo ArgumentCompletions è simile a ValidateSet. Entrambi gli attributi accettano un elenco di valori da presentare quando l'utente preme TAB dopo il nome del parametro. Tuttavia, a differenza di ValidateSet, i valori non vengono convalidati e più simili ai suggerimenti. Pertanto, l'utente può fornire qualsiasi valore, non solo i valori nell'elenco.
L'attributo ArgumentCompletions non deve essere confuso con l'attributo ArgumentCompleter , che richiede un blocco script per definire le opzioni. sono disponibili i valori specificati
La sintassi è la seguente:
function Test-ArgumentCompletions {
[CmdletBinding()]
param (
[Parameter(Mandatory=$true)]
[ArgumentCompletions('Fruits', 'Vegetables')]
$Type,
[Parameter()]
[ArgumentCompletions('Apple', 'Banana', 'Orange')]
$Fruit,
[Parameter()]
[ArgumentCompletions('Onion', 'Carrot', 'Lettuce')]
$Vegetable
)
}
A ogni parametro viene fornito un elenco di opzioni per l'attributo ArgumentCompletions per abilitare il completamento tramite tabulazione.
Questo attributo è stato introdotto in PowerShell 6.0.
Attributo ArgumentCompleter
L'attributo ArgumentCompleter consente di aggiungere valori di completamento tramite tabulazione a un parametro specifico. È necessario definire un attributo ArgumentCompleter per ogni parametro che richiede il completamento tramite tabulazione.
Per aggiungere un attributo ArgumentCompleter , è necessario definire un blocco di script che determina i valori. Il blocco di script deve accettare i parametri seguenti nell'ordine specificato di seguito. I nomi dei parametri non sono importanti perché i valori vengono forniti in modo posizionale.
La sintassi è la seguente:
function MyArgumentCompleter {
Param(
[Parameter(Mandatory)]
[ArgumentCompleter( {
param ( $commandName,
$parameterName,
$wordToComplete,
$commandAst,
$fakeBoundParameters )
# Perform calculation of tab completed values here.
} )]
$ParamName
)
}
Blocco di script ArgumentCompleter
I parametri del blocco di script sono impostati sui valori seguenti:
$commandName(Posizione 0): questo parametro viene impostato sul nome del comando per il quale il blocco di script fornisce il completamento tramite tabulazione.$parameterName(Posizione 1): questo parametro è impostato sul parametro il cui valore richiede il completamento della scheda.$wordToComplete(Posizione 2): questo parametro è impostato sul valore fornito dall'utente prima di premere TAB. Il blocco di script deve usare questo valore per determinare i valori di completamento della scheda.$commandAst(Posizione 3): questo parametro è impostato sull'albero della sintassi astratta (AST) per la riga di input corrente. Per altre informazioni, vedere la documentazione sul tipo di AST .$fakeBoundParameters(Posizione 4): questo parametro è impostato su una tabella hash contenente per$PSBoundParametersil cmdlet, prima che l'utente preme tab. Per altre informazioni, vedere about_Automatic_Variables.
Il blocco di script ArgumentCompleter deve annullare la registrazione dei valori usando la pipeline, ad esempio ForEach-Object, Where-Objecto un altro metodo appropriato.
Se si restituisce una matrice di valori, PowerShell considera l'intera matrice come un valore di completamento tramite tabulazione.
Nell'esempio seguente viene aggiunto il completamento tramite tabulazione al parametro Value . Se viene specificato solo il parametro Value , vengono visualizzati tutti i valori o gli argomenti possibili per Value . Quando si specifica il parametro Type , il parametro Value visualizza solo i valori possibili per tale tipo.
Inoltre, l'operatore -like garantisce che se l'utente digita il comando seguente e usa il completamento tabulazione , viene restituito solo Apple .
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
)
}
Completer di argomenti basati su classi
A partire da PowerShell 7.2 è stata aggiunta una nuova funzionalità che consente di definire implementazioni più generiche dei completer di argomenti con parametri.
Derivando da ArgumentCompleterAttribute, è possibile creare complete generici che possono essere riutilizzate, ad esempio:
[DirectoryCompleter(ContainingFile="pswh.exe", Depth=2)]
[DateCompleter(WeekDay='Monday', From="LastYear")]
[GitCommits(Branch='release')]
Gli attributi derivati devono implementare l'interfaccia IArgumentCompleterFactory e usare i valori delle proprietà per creare un completore specializzato.
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) }
}
L'utilizzo da PowerShell sarà quindi:
function Add{
param(
[NumberCompletions(0, 100, 5)]
[int] $X,
[NumberCompletions(0, 100, 5)]
[int] $Y
)
$X + $Y
}
Register-ArgumentCompleter
Il Register-ArgumentCompleter cmdlet registra un completore di argomenti personalizzato.
Un completore di argomenti consente di fornire il completamento di schede dinamiche, in fase di esecuzione per qualsiasi comando specificato.
Per altre informazioni, vedere Register-ArgumentCompleter.
Vedi anche
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per