Delen via

Register-ArgumentCompleter

Module:
Microsoft.PowerShell.Core Module

Registreert een aangepaste argument completer.

Syntax

PowerShellSet 

Register-ArgumentCompleter
    -ParameterName <String>
    -ScriptBlock <ScriptBlock>
    [-CommandName <String[]>]
    [<CommonParameters>]

NativeSet 

Register-ArgumentCompleter
    -CommandName <String[]>
    -ScriptBlock <ScriptBlock>
    [-Native]
    [<CommonParameters>]

Description

De cmdlet Register-ArgumentCompleter registreert een aangepaste argument-completer. Met een argument completer kunt u dynamische tabvoltooiing opgeven, tijdens runtime voor elke opdracht die u opgeeft.

Voorbeelden

Voorbeeld 1: Een aangepaste argument completer registreren

In het volgende voorbeeld wordt een argument completer geregistreerd voor de parameter van de -id van de -cmdlet.

$scriptBlock = {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)

    (Get-TimeZone -ListAvailable).Id | Where-Object {
        $_ -like "$wordToComplete*"
    } | ForEach-Object {
          "'$_'"
    }
}
Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -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 worden de beschikbare waarden voor id- opgehaald met behulp van de cmdlet Get-TimeZone. 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 is opgegeven door $wordToComplete, die de tekst vertegenwoordigt die de gebruiker heeft getypt voordat ze op <TAB>drukken. De gefilterde id's worden doorgesluisd naar de For-EachObject cmdlet die elke waarde tussen aanhalingstekens plaatst, indien de waarde spaties bevat.

Met de tweede opdracht wordt de argument completer geregistreerd door het scriptblok door te geven, de ParameterName "Id" en de CommandNameSet-TimeZone.

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" }
    $services | Where-Object { $_.Name -like "$wordToComplete*" } | ForEach-Object {
        New-Object -Type System.Management.Automation.CompletionResult -ArgumentList $_,
            $_,
            "ParameterValue",
            $_
    }
}
Register-ArgumentCompleter -CommandName dotnet -Native -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 cmdlet Where-Object. De services worden doorgesluisd naar de cmdlet ForEach-Object. De cmdlet ForEach-Object maakt een nieuw [System.Management.Automation.CompletionResult]-object en vult het met de waarden van de huidige service (vertegenwoordigd door de pijplijnvariabele $_).

Met het object CompletionResult kunt u aanvullende details opgeven voor elke geretourneerde waarde:

  • completionText (tekenreeks): de tekst die moet worden gebruikt als het resultaat van automatische voltooiing. 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>+<Space>drukt. Dit wordt alleen gebruikt voor weergave en 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 nadat hij op <Ctrl>+<Space>heeft gedrukt.

De laatste opdracht laat zien dat gestopte services nog steeds handmatig kunnen worden doorgegeven aan de Stop-Service cmdlet. De voltooiing van het tabblad is het enige aspect dat wordt beïnvloed.

Voorbeeld 3: Een aangepast systeemeigen argument completer registreren

U kunt de parameter Native gebruiken om tabvoltooiing op te geven voor een systeemeigen opdracht. In het volgende voorbeeld wordt tabvoltooiing toegevoegd voor de dotnet CLI (Opdrachtregelinterface).

Opmerking

De dotnet complete opdracht is alleen beschikbaar in versie 2.0 en hoger van de dotnet cli.

$scriptblock = {
     param($commandName, $wordToComplete, $cursorPosition)
         dotnet complete --position $cursorPosition "$wordToComplete" | ForEach-Object {
            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
         }
 }
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 wordt de opdracht dotnet complete gebruikt om de tabvoltooiing uit te voeren. De resultaten worden doorgesluisd naar de ForEach-Object-cmdlet die gebruikmaakt van de nieuwe statische methode van de [System.Management.Automation.CompletionResult]-klasse om een nieuw CompletionResult-object voor elke waarde te maken.

Parameters

-CommandName

Hiermee geeft u de naam van de opdrachten als een matrix.

Parametereigenschappen

Type:

String[]

Default value:None
Ondersteunt jokertekens:False
DontShow:False

Parametersets

PowerShellSet
Position:Named
Verplicht:False
Waarde uit pijplijn:False
Waarde uit pijplijn op eigenschapsnaam:False
Waarde van resterende argumenten:False
NativeSet
Position:Named
Verplicht:True
Waarde uit pijplijn:False
Waarde uit pijplijn op eigenschapsnaam:False
Waarde van resterende argumenten:False

-Native

Geeft aan dat de argument completer is voor een systeemeigen opdracht waarbij PowerShell geen parameternamen kan voltooien.

Parametereigenschappen

Type:SwitchParameter
Default value:None
Ondersteunt jokertekens:False
DontShow:False

Parametersets

NativeSet
Position:Named
Verplicht:False
Waarde uit pijplijn:False
Waarde uit pijplijn op eigenschapsnaam:False
Waarde van resterende argumenten:False

-ParameterName

Hiermee geeft u de naam van de parameter waarvan het argument wordt voltooid. De opgegeven parameternaam kan geen opsommingswaarde zijn, zoals de ForegroundColor parameter van de cmdlet Write-Host.

Zie about_Enumvoor meer informatie over opsommingen.

Parametereigenschappen

Type:String
Default value:None
Ondersteunt jokertekens:False
DontShow:False

Parametersets

PowerShellSet
Position:Named
Verplicht:True
Waarde uit pijplijn:False
Waarde uit pijplijn op eigenschapsnaam:False
Waarde van resterende argumenten: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 één tabvoltooiingswaarde.

Het scriptblok moet ook de volgende parameters accepteren in de onderstaande volgorde. De namen van de parameters zijn niet belangrijk omdat PowerShell de waarden positioneeldoorgeeft.

  • $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 deze op <TAB>drukt. Uw scriptblok moet deze waarde gebruiken om de waarden voor tabvoltooiing te bepalen.
  • $commandAst (Positie 3): deze parameter is ingesteld op de AST (Abstract Syntax Tree) voor de huidige invoerregel. Zie Ast Classvoor meer informatie.
  • $fakeBoundParameter (Positie 4): deze parameter is ingesteld op een hashtabel met de $PSBoundParameters voor de cmdlet, voordat de gebruiker op <TAB>heeft gedrukt. Voor meer informatie, zie about_Automatic_Variables.

Wanneer u de parameter Systeemeigen opgeeft, moet het scriptblok de volgende parameters in de opgegeven volgorde hebben. De namen van de parameters zijn niet belangrijk omdat PowerShell de waarden positioneeldoorgeeft.

  • $commandName (Positie 0): deze parameter is ingesteld op de naam van de opdracht waarvoor het scriptblok tabvoltooiing biedt.
  • $wordToComplete (Positie 1): deze parameter is ingesteld op de waarde die de gebruiker heeft opgegeven voordat ze op <TAB>drukken. Uw scriptblok moet deze waarde gebruiken om de waarden voor tabvoltooiing te bepalen.
  • $cursorPosition (Positie 2): deze parameter wordt ingesteld op de positie van de cursor wanneer de gebruiker op <TAB>drukt.

U kunt ook een ArgumentCompleter opgeven als parameterkenmerk. Zie about_Functions_Advanced_Parametersvoor meer informatie.

Parametereigenschappen

Type:ScriptBlock
Default value:None
Ondersteunt jokertekens:False
DontShow:False

Parametersets

(All)
Position:Named
Verplicht:True
Waarde uit pijplijn:False
Waarde uit pijplijn op eigenschapsnaam:False
Waarde van resterende argumenten:False

CommonParameters

Deze cmdlet ondersteunt de algemene parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction en -WarningVariable. Zie about_CommonParametersvoor meer informatie.

Invoerwaarden

None

U kunt geen objecten doorsluisen naar deze cmdlet.

Uitvoerwaarden

None

Deze cmdlet retourneert geen uitvoer.