Register-ArgumentCompleter
Registreert een aangepaste argument completer.
Syntaxis
Register-ArgumentCompleter
-CommandName <String[]>
-ScriptBlock <ScriptBlock>
[-Native]
[<CommonParameters>]
Register-ArgumentCompleter
[-CommandName <String[]>]
-ParameterName <String>
-ScriptBlock <ScriptBlock>
[<CommonParameters>]
Description
De Register-ArgumentCompleter
cmdlet registreert een aangepaste argument completer. Met een argument completer kunt u dynamische tabvoltooiing opgeven, tijdens runtime voor elke opdracht die u opgeeft.
Wanneer u deze opdracht aanroept met de parameter CommandName en zonder parameterName of Systeemeigen parameters, wordt de opdracht uitgevoerd alsof u de systeemeigen parameter hebt opgegeven. Hiermee voorkomt u dat de argument completer werkt voor PowerShell-opdrachtparameters. Geef altijd de parameter ParameterName op wanneer u een argument completer wilt registreren voor PowerShell-opdrachten.
Voorbeelden
Voorbeeld 1: Een aangepaste argument completer registreren
In het volgende voorbeeld wordt een argument completer geregistreerd voor de id-parameter van de Set-TimeZone
cmdlet.
$s = {
param(
$commandName,
$parameterName,
$wordToComplete,
$commandAst,
$fakeBoundParameters
)
(Get-TimeZone -ListAvailable).Id | Where-Object {
$_ -like "$wordToComplete*"
} | ForEach-Object {
"'$_'"
}
}
Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $s
Met de eerste opdracht maakt u een scriptblok dat de vereiste parameters gebruikt, die worden doorgegeven wanneer de gebruiker op Tab drukt. Zie de beschrijving van de scriptblock-parameter voor meer informatie.
In het scriptblok worden de beschikbare waarden voor id opgehaald met behulp van de Get-TimeZone
cmdlet. De eigenschap Id voor elke tijdzone wordt doorgesluisd naar de Where-Object
cmdlet. De Where-Object
cmdlet filtert id's die niet beginnen met de waarde die wordt $wordToComplete
opgegeven door, die de tekst vertegenwoordigt die de gebruiker heeft getypt voordat ze op Tab drukten. De gefilterde id's worden doorgesluisd naar de ForEach-Object
cmdlet, die elke waarde tussen aanhalingstekens plaatst om waarden te verwerken die spaties bevatten.
Met de tweede opdracht wordt de argument completer geregistreerd door het scriptblock, de ParameterName-id en de CommandName Set-TimeZone
door te geven.
Voorbeeld 2: Details toevoegen aan de voltooiingswaarden van het tabblad
In het volgende voorbeeld wordt de tabvoltooiing voor de parameter Naam van de Stop-Service
cmdlet overschreven en worden alleen actieve services geretourneerd.
$s = {
param(
$commandName,
$parameterName,
$wordToComplete,
$commandAst,
$fakeBoundParameters
)
$services = Get-Service | Where-Object {
$_.Status -eq 'Running' -and $_.Name -like "$wordToComplete*"
}
$services | ForEach-Object {
New-Object -Type System.Management.Automation.CompletionResult -ArgumentList @(
$_.Name # completionText
$_.Name # listItemText
'ParameterValue' # resultType
$_.Name # toolTip
)
}
}
Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $s
Met de eerste opdracht maakt u een scriptblok dat de vereiste parameters gebruikt, die worden doorgegeven wanneer de gebruiker op Tab drukt. Zie de beschrijving van de scriptblock-parameter voor meer informatie.
Binnen het scriptblok haalt de eerste opdracht alle actieve services op met behulp van de Where-Object
cmdlet. De services worden doorgesluisd naar de ForEach-Object
cmdlet. De ForEach-Object
cmdlet maakt een nieuw System.Management.Automation.CompletionResult-object en vult het met de naam van de huidige service (vertegenwoordigd door de pijplijnvariabele $_.Name
).
Met het object CompletionResult kunt u aanvullende details opgeven voor elke geretourneerde waarde:
- completionText (Tekenreeks): de tekst die moet worden gebruikt als het resultaat voor automatisch aanvullen. Dit is de waarde die naar de opdracht wordt verzonden.
- listItemText (Tekenreeks): de tekst die moet worden weergegeven in een lijst, bijvoorbeeld wanneer de gebruiker op Ctrl-spatiebalk+ drukt. PowerShell gebruikt dit alleen voor weergave. Deze wordt niet doorgegeven aan de opdracht wanneer deze is geselecteerd.
- resultType (CompletionResultType) - Het type voltooiingsresultaat.
- knopinfo (tekenreeks): de tekst voor de knopinfo met details die over het object moeten worden weergegeven. Dit is zichtbaar wanneer de gebruiker een item selecteert na het drukken op Ctrl-spatiebalk+.
Voorbeeld 3: Een aangepast systeemeigen argument completer registreren
U kunt de systeemeigen parameter gebruiken om tabvoltooiing op te geven voor een systeemeigen opdracht. In het volgende voorbeeld wordt tabvoltooiing toegevoegd voor de dotnet
opdrachtregelinterface (CLI).
Notitie
De dotnet complete
opdracht is alleen beschikbaar in versie 2.0 en hoger van de dotnet-cli.
$scriptblock = {
param(
$wordToComplete,
$commandAst,
$cursorPosition
)
dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {
[System.Management.Automation.CompletionResult]::new(
$_, # completionText
$_, # listItemText
'ParameterValue', # resultType
$_ # toolTip
)
}
}
Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock
Met de eerste opdracht maakt u een scriptblok dat de vereiste parameters gebruikt, die worden doorgegeven wanneer de gebruiker op Tab drukt. Zie de beschrijving van de scriptblock-parameter voor meer informatie.
In het scriptblok voert de dotnet complete
opdracht de tabvoltooiing uit. De resultaten worden doorgesluisd naar de ForEach-Object
cmdlet, die gebruikmaakt van de nieuwe statische methode van de klasse System.Management.Automation.CompletionResult om voor elke waarde een CompletionResult-object te maken.
Parameters
-CommandName
Hiermee geeft u de naam van een of meer opdrachten voor het registreren van de argument completer voor. Deze parameter is verplicht voor systeemeigen opdrachten.
Wanneer u deze parameter opgeeft zonder parameternaam of systeemeigen parameters, gedraagt de opdracht zich alsof u de systeemeigen parameter hebt opgegeven. Bij het registreren van argument completers voor PowerShell-opdrachten, geeft u altijd de parameter ParameterName op.
Als u deze parameter niet opgeeft, registreert PowerShell de argument-completer voor de opgegeven ParameterName voor alle PowerShell-opdrachten.
Type: | String[] |
Position: | Named |
Default value: | None |
Vereist: | False |
Pijplijninvoer accepteren: | False |
Jokertekens accepteren: | False |
-Native
Geeft aan dat de argument completer is voor een systeemeigen opdracht waarbij PowerShell geen parameternamen kan voltooien.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Vereist: | False |
Pijplijninvoer accepteren: | False |
Jokertekens accepteren: | False |
-ParameterName
Hiermee geeft u de naam van de parameter op waar de argument completer op van toepassing is. Het type voor opgegeven parameters kan geen opsomming zijn, zoals de parameter ForegroundColor van de Write-Host
cmdlet.
Zie about_Enum voor meer informatie over opsommingen.
Wanneer u een argument completer registreert voor PowerShell-opdrachten, geeft u altijd deze parameter op. Wanneer u de parameter CommandName zonder parameterName of Systeemeigen parameters opgeeft, gedraagt de opdracht zich alsof u de systeemeigen parameter hebt opgegeven.
Type: | String |
Position: | Named |
Default value: | None |
Vereist: | True |
Pijplijninvoer accepteren: | False |
Jokertekens accepteren: | False |
-ScriptBlock
Hiermee geeft u de opdrachten die moeten worden uitgevoerd om tabvoltooiing uit te voeren. Het scriptblok dat u opgeeft, moet de waarden retourneren die de invoer voltooien. Het scriptblok moet de waarden uitschrijven met behulp van de pijplijn (ForEach-Object
, Where-Object
enzovoort) of een andere geschikte methode. Als u een matrix met waarden retourneert, wordt de hele matrix door PowerShell behandeld als een voltooiingswaarde van één tabblad.
Het scriptblok kan ook System.Management.Automation.CompletionResult-objecten retourneren voor elke waarde om de gebruikerservaring te verbeteren. Als u completionResult-objecten retourneert, kunt u knopinfo en aangepaste lijstitems definiëren die worden weergegeven wanneer gebruikers op Ctrl-spatiebalk+ drukken om de lijst met beschikbare voltooiingen weer te geven.
Het scriptblok moet de volgende parameters accepteren in de onderstaande volgorde. De namen van de parameters zijn niet belangrijk omdat PowerShell de waarden op positie doorgeeft.
$commandName
(Positie 0, Tekenreeks): deze parameter is ingesteld op de naam van de opdracht waarvoor het scriptblok tabvoltooiing biedt.$parameterName
(Positie 1, Tekenreeks): deze parameter is ingesteld op de parameter waarvan de waarde tabvoltooiing vereist.$wordToComplete
(Positie 2, Tekenreeks): deze parameter is ingesteld op de waarde die de gebruiker heeft opgegeven voordat deze op Tab drukt. Uw scriptblok moet deze waarde gebruiken om de waarden voor tabvoltooiing te bepalen.$commandAst
(Positie 3, CommandAst): deze parameter is ingesteld op de AST (Abstract Syntax Tree) voor de huidige invoerregel. Zie CommandAst-klasse voor meer informatie.$fakeBoundParameters
(Positie 4 IDictionary): deze parameter is ingesteld op een hashtabel die de$PSBoundParameters
cmdlet bevat, voordat de gebruiker op Tab drukt. Zie about_Automatic_Variables voor meer informatie.
Wanneer u de systeemeigen parameter opgeeft, moet het scriptblok de volgende parameters in de opgegeven volgorde hebben. De namen van de parameters zijn niet belangrijk omdat PowerShell de waarden op positie doorgeeft.
$wordToComplete
(Positie 0, Tekenreeks): deze parameter is ingesteld op de waarde die de gebruiker heeft opgegeven voordat deze op Tab drukt. Uw scriptblok moet deze waarde gebruiken om de waarden voor tabvoltooiing te bepalen.$commandAst
(Positie 1, CommandAst): deze parameter is ingesteld op de AST (Abstract Syntax Tree) voor de huidige invoerregel. Zie CommandAst-klasse voor meer informatie.$cursorPosition
(Positie 2, Int32): deze parameter wordt ingesteld op de positie van de cursor wanneer de gebruiker op Tab heeft gedrukt.
U kunt ook een ArgumentCompleter opgeven als parameterkenmerk. Zie about_Functions_Advanced_Parameters voor meer informatie.
Type: | ScriptBlock |
Position: | Named |
Default value: | None |
Vereist: | True |
Pijplijninvoer accepteren: | False |
Jokertekens accepteren: | False |
Invoerwaarden
None
U kunt geen objecten doorsluisen naar deze cmdlet.
Uitvoerwaarden
None
Deze cmdlet retourneert geen uitvoer.
Verwante koppelingen
Feedback
https://aka.ms/ContentUserFeedback.
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie:Feedback verzenden en weergeven voor