Register-ArgumentCompleter

  • Referens
Modul:
Microsoft.PowerShell.Core

Registrerar en anpassad argument-slutförare.

Syntax

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

Description

Cmdleten Register-ArgumentCompleter registrerar en anpassad argument-completer. Med en argumentkompletterare kan du ange dynamiskt tabbslut, vid körning för alla kommandon som du anger.

Exempel

Exempel 1: Registrera en slutförd anpassat argument

I följande exempel registreras en argument completer för ID-parametern för cmdleten Set-TimeZone .

$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

Det första kommandot skapar ett skriptblock som tar de obligatoriska parametrar som skickas när användaren trycker på Tabb. Mer information finns i parameterbeskrivningen ScriptBlock .

I skriptblocket hämtas tillgängliga värden för ID med hjälp av cmdleten Get-TimeZone . Id-egenskapen för varje tidszon skickas till cmdletenWhere-Object. Cmdleten Where-Object filtrerar bort alla ID:t som inte börjar med värdet som tillhandahålls av $wordToComplete, som representerar texten som användaren skrev innan de tryckte på Tabb. De filtrerade ID:erna skickas till cmdleten For-EachObject som omsluter varje värde med citattecken om värdet innehåller blanksteg.

Det andra kommandot registrerar argument completer genom att skicka scriptblock, ParameterNameID och CommandNameSet-TimeZone.

Exempel 2: Lägg till information i tabbslutvärdena

I följande exempel skrivs flikens slutförande över för parametern Namn för cmdleten Stop-Service och returnerar endast tjänster som körs.

$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

Det första kommandot skapar ett skriptblock som tar de obligatoriska parametrar som skickas när användaren trycker på Tabb. Mer information finns i parameterbeskrivningen ScriptBlock .

I skriptblocket hämtar det första kommandot alla tjänster som körs med hjälp av cmdleten Where-Object . Tjänsterna skickas till cmdleten ForEach-Object . Cmdleten ForEach-Object skapar ett nytt System.Management.Automation.CompletionResult-objekt och fyller det med namnet på den aktuella tjänsten (representeras av pipelinevariabeln $_.Name).

Med objektet CompletionResult kan du ange ytterligare information för varje returnerat värde:

  • completionText (Sträng) – den text som ska användas som automatiskt slutföranderesultat. Det här är värdet som skickas till kommandot.
  • listItemText (Sträng) – texten som ska visas i en lista, till exempel när användaren trycker på Ctrl-blanksteg+. Detta används endast för visning och skickas inte till kommandot när det väljs.
  • resultType (CompletionResultType) – typ av slutföranderesultat.
  • toolTip (String) – Texten för knappbeskrivningen med information som ska visas om objektet. Detta visas när användaren väljer ett objekt efter att ha tryckt påCtrl-blanksteg+.

Det sista kommandot visar att stoppade tjänster fortfarande kan skickas manuellt till cmdleten Stop-Service . Flikens slutförande är den enda aspekten som påverkas.

Exempel 3: Registrera en anpassad intern argument-completer

Du kan använda den interna parametern för att tillhandahålla tab-completion för ett internt kommando. I följande exempel läggs tab-completion till för kommandoradsgränssnittet dotnet (CLI).

Anteckning

Kommandot dotnet complete är endast tillgängligt i version 2.0 och senare av 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

Det första kommandot skapar ett skriptblock som tar de obligatoriska parametrar som skickas när användaren trycker på Tabb. Mer information finns i parameterbeskrivningen ScriptBlock .

I skriptblocket dotnet complete används kommandot för att slutföra fliken. Resultatet skickas till cmdleten ForEach-Object som använder den nya statiska metoden i klassen System.Management.Automation.CompletionResult för att skapa ett nytt CompletionResult-objekt för varje värde.

Parametrar

-CommandName

Anger namnet på kommandona som en matris.

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

-Native

Anger att argument completer är för ett internt kommando där PowerShell inte kan slutföra parameternamn.

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

-ParameterName

Anger namnet på parametern vars argument håller på att slutföras. Det angivna parameternamnet får inte vara ett uppräknat värde, till exempel parametern ForegroundColor för cmdleten Write-Host .

Mer information om uppräkningar finns i about_Enum.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ScriptBlock

Anger vilka kommandon som ska köras för att slutföra fliken. Skriptblocket som du anger ska returnera de värden som slutför indata. Skriptblocket måste avregistrera värdena med pipelinen (ForEach-Object, Where-Objectosv.) eller någon annan lämplig metod. Om du returnerar en matris med värden behandlar PowerShell hela matrisen som ett flikslutvärde.

Skriptblocket måste acceptera följande parametrar i den ordning som anges nedan. Namnen på parametrarna är inte viktiga eftersom PowerShell skickar värdena efter position.

  • $commandName (Position 0) – Den här parametern är inställd på namnet på det kommando som skriptblocket tillhandahåller tabbslut.
  • $parameterName (Position 1) – Den här parametern är inställd på parametern vars värde kräver att fliken slutförs.
  • $wordToComplete (Position 2) – Den här parametern är inställd på det värde som användaren har angett innan de trycker på Tabb. Skriptblocket bör använda det här värdet för att fastställa tabbslutvärden.
  • $commandAst (Position 3) – Den här parametern är inställd på abstrakt syntaxträd (AST) för den aktuella indatalinjen. Mer information finns i Ast-klass.
  • $fakeBoundParameters (Position 4) – Den här parametern är inställd på en hashtable som innehåller $PSBoundParameters för cmdleten innan användaren trycker på Tabb. Mer information finns i about_Automatic_Variables.

När du anger den interna parametern måste skriptblocket ha följande parametrar i den angivna ordningen. Namnen på parametrarna är inte viktiga eftersom PowerShell skickar värdena efter position.

  • $wordToComplete (Position 0) – Den här parametern är inställd på det värde som användaren har angett innan de trycker på Tabb. Skriptblocket bör använda det här värdet för att fastställa tabbslutvärden.
  • $commandAst (Position 1) – Den här parametern är inställd på abstrakt syntaxträd (AST) för den aktuella indatalinjen. Mer information finns i Ast-klass.
  • $cursorPosition (Position 2) – Den här parametern är inställd på markörens position när användaren tryckte på Tabb.

Du kan också ange en ArgumentCompleter som ett parameterattribut. Mer information finns i about_Functions_Advanced_Parameters.

Type:ScriptBlock
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

Indata

None

Du kan inte skicka objekt till den här cmdleten.

Utdata

None

Den här cmdleten returnerar inga utdata.