Dela via

Register-ArgumentCompleter

Modul:
Microsoft.PowerShell.Core Module

Registrerar en komplettering av ett anpassat argument.

Syntax

NativeSet 

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

PowerShellSet 

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

Description

Cmdleten Register-ArgumentCompleter registrerar en anpassad argument-completer. Med en argumentföreläsning kan du ange dynamisk flikavslut, vid körning för alla kommandon som du anger.

När du anropar det här kommandot med parametern CommandName och utan parametrarna ParameterName eller Native körs kommandot som om du angav parametern Native. Detta förhindrar att argumenteparametern fungerar för PowerShell-kommandoparametrar. Ange alltid parametern ParameterName när du vill registrera en argumenteparameter för PowerShell-kommandon.

Exempel

Exempel 1: Registrera en slutförd anpassad argument

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

$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

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

I skriptblocket hämtas tillgängliga värden för ID med hjälp av cmdleten Get-TimeZone. Egenskapen ID för varje tidszon skickas till cmdleten Where-Object. Cmdleten Where-Object filtrerar bort alla ID:er som inte börjar med värdet som anges av $wordToComplete, som representerar texten som användaren skrev innan de tryckte på Tab. De filtrerade ID:erna skickas till cmdleten ForEach-Object som omger varje värde inom citattecken för att hantera värden som innehåller blanksteg.

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

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

I följande exempel skrivs fliken över för parametern Name i 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          # completionText
            $_.Name          # listItemText
            'ParameterValue' # resultType
            $_.Name          # toolTip
        )
    }
}

Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $s

Det första kommandot skapar ett skriptblock som tar de obligatoriska parametrarna, som skickas när användaren trycker på Tab. 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-objektet och fyller det med namnet på den aktuella tjänsten (representeras av pipelinevariabeln $_.Name).

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

  • completionText (String) – Den text som ska användas som automatiskt slutföranderesultat. Det här är värdet som skickas till kommandot.
  • listItemText (String) – Texten som ska visas i en lista, till exempel när användaren trycker på Ctrl+Space. PowerShell använder detta endast för visning. Det 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 när Ctrl+Blanksteg.

Exempel 3: Registrera en anpassad intern argument-completer

Du kan använda parametern Native för att tillhandahålla tab-completion för ett internt kommando. Följande exempel lägger till tab-completion för dotnet Kommandoradsgränssnitt (CLI).

Anmärkning

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

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

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

Parametrar

-CommandName

Anger namnet på ett eller flera kommandon som argumenten ska slutföras för. Den här parametern är obligatorisk för interna kommandon.

När du anger den här parametern utan parametrarna ParameterName eller Native fungerar kommandot som om du hade angett parametern Native. När du registrerar slutförda argument för PowerShell-kommandon anger du alltid parametern ParameterName.

Om du inte anger den här parametern registrerar PowerShell argument completer för den angivna ParameterName- för alla PowerShell-kommandon.

Parameteregenskaper

Typ:

String[]

Standardvärde:None
Stöder jokertecken:False
DontShow:False

Parameteruppsättningar

NativeSet
Position:Named
Obligatorisk:True
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False
PowerShellSet
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-Native

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

Parameteregenskaper

Typ:SwitchParameter
Standardvärde:None
Stöder jokertecken:False
DontShow:False

Parameteruppsättningar

NativeSet
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-ParameterName

Anger namnet på parametern som argumenteparametern gäller för. Typen för angivna parametrar kan inte vara en uppräkning, till exempel parametern ForegroundColor i cmdleten Write-Host.

Mer information om uppräkningar finns i about_Enum.

När du registrerar en argument completer för PowerShell-kommandon anger du alltid den här parametern. När du anger parametern CommandName utan parametrarna ParameterName eller Native fungerar kommandot som om du angav parametern Native.

Parameteregenskaper

Typ:String
Standardvärde:None
Stöder jokertecken:False
DontShow:False

Parameteruppsättningar

PowerShellSet
Position:Named
Obligatorisk:True
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument: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 hjälp av pipelinen (ForEach-Object, Where-Objectosv.) eller en annan lämplig metod. Om du returnerar en matris med värden kan PowerShell behandla hela matrisen som ett flikslutvärde.

Skriptblocket kan också returnera System.Management.Automation.CompletionResult objekt för varje värde för att förbättra användarupplevelsen. När du returnerar CompletionResult objekt kan du definiera knappbeskrivningar och anpassade listposter som visas när användarna trycker på Ctrl+Blanksteg för att visa listan över tillgängliga slutföranden.

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, String) – Den här parametern är inställd på namnet på kommandot som skriptblocket tillhandahåller tabbavslut för.
  • $parameterName (Position 1, String) – Den här parametern är inställd på parametern vars värde kräver att fliken slutförs.
  • $wordToComplete (Position 2, String) – Den här parametern är inställd på värdet som användaren har angett innan användaren trycker på Tab. Skriptblocket bör använda det här värdet för att fastställa flikslutvärden.
  • $commandAst (position 3, CommandAst) – Den här parametern är inställd på AST (Abstract Syntax Tree) för den aktuella indataraden. Mer information finns i CommandAst Class.
  • $fakeBoundParameters (position 4 IDictionary) – Den här parametern är inställd på en hashtabell som innehåller $PSBoundParameters för cmdleten innan användaren tryckte på Tab. Mer information finns i about_Automatic_Variables.

När du anger parametern native 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, String) – Den här parametern är inställd på värdet som användaren har angett innan de tryckte på Tab. Skriptblocket bör använda det här värdet för att fastställa flikslutvärden.
  • $commandAst (position 1, CommandAst) – Den här parametern är inställd på AST (Abstract Syntax Tree) för den aktuella indataraden. Mer information finns i CommandAst Class.
  • $cursorPosition (position 2, Int32) – Den här parametern är inställd på markörens position när användaren tryckte på Tab.

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

Parameteregenskaper

Typ:ScriptBlock
Standardvärde:None
Stöder jokertecken:False
DontShow:False

Parameteruppsättningar

(All)
Position:Named
Obligatorisk:True
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

CommonParameters

Den här cmdleten stöder vanliga parametrar: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction och -WarningVariable. Mer information finns i about_CommonParameters.

Indata

None

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

Utdata

None

Den här cmdleten returnerar inga utdata.