Register-ArgumentCompleter

Referentie

Module:: Microsoft.PowerShell.Core

Registreert een aangepaste argument completer.

Syntax

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.

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.

$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 parameter ScriptBlock voor meer informatie.

In het scriptblok worden de beschikbare waarden voor id opgehaald met behulp van de Get-TimeZone cmdlet. De id-eigenschap voor elke tijdzone wordt doorgesluisd naar de Where-Object cmdlet. Met Where-Object de cmdlet worden id's gefilterd die niet beginnen met de waarde die is opgegeven door $wordToComplete, wat de tekst vertegenwoordigt die de gebruiker heeft getypt voordat ze op Tab drukken. De gefilterde id's worden doorgesluisd naar de ForEach-Object cmdlet die elke waarde tussen aanhalingstekens plaatst, als de waarde spaties bevat.

Met de tweede opdracht wordt de argument completer geregistreerd door het scriptblock, de ParameterName-id en de CommandNameSet-TimeZone door te geven.

Voorbeeld 2: Details toevoegen aan de voltooiingswaarden van het tabblad

In het volgende voorbeeld wordt tabvoltooiing voor de naamparameter 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,
            $_.Name,
            "ParameterValue",
            $_.Name
    }
}
Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $s

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 opCtrl-spatiebalk+ 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 opCtrl-spatiebalk+ heeft gedrukt.

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

Voorbeeld 3: Een aangepaste systeemeigen argument completer registreren

U kunt de systeemeigen parameter gebruiken om tabvoltooiing voor een systeemeigen opdracht op te geven. 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($_, $_, 'ParameterValue', $_)
        }
}
Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

Binnen het scriptblok wordt de dotnet complete opdracht gebruikt om de tabvoltooiing uit te voeren. De resultaten worden doorgesluisd naar de ForEach-Object cmdlet die de nieuwe statische methode van de klasse System.Management.Automation.CompletionResult gebruikt om voor elke waarde een nieuw CompletionResult-object te maken.

Parameters

-CommandName

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

Type:	String[]
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-Native

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

Type:	SwitchParameter
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

-ParameterName

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

Zie about_Enum voor meer informatie over opsommingen.

Type:	String
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	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-Objectenzovoort) 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 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) - 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 drukken. Uw scriptblok moet deze waarde gebruiken om tabvoltooiingswaarden te bepalen.
$commandAst (Positie 3) - Deze parameter is ingesteld op de AST (Abstract Syntax Tree) voor de huidige invoerregel. Zie Ast Class voor meer informatie.
$fakeBoundParameters (Positie 4) - Deze parameter is ingesteld op een hashtabel met de $PSBoundParameters cmdlet 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) - Deze parameter is ingesteld op de waarde die de gebruiker heeft opgegeven voordat ze op Tab hebben gedrukt. Uw scriptblok moet deze waarde gebruiken om tabvoltooiingswaarden te bepalen.
$commandAst (Positie 1) - Deze parameter is ingesteld op de AST (Abstract Syntax Tree) voor de huidige invoerregel. Zie Ast Class voor meer informatie.
$cursorPosition (Positie 2) - Deze parameter is 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
Accept pipeline input:	False
Accept wildcard characters:	False

Invoerwaarden

None

U kunt geen objecten doorsluisen naar deze cmdlet.

Uitvoerwaarden