Register-ArgumentCompleter

Modul:

Microsoft.PowerShell.Core

Egyéni argumentum-befejezőt regisztrál.

Syntax

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

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

Description

A Register-ArgumentCompleter parancsmag regisztrál egy egyéni argumentum-befejezőt. Az argumentumkiegészítő lehetővé teszi a dinamikus lapkiegészítést a megadott parancsok futásidejű futtatásához.

Ha a parancsot a CommandName paraméterrel hívja meg, és a ParameterName vagy a natív paraméterek nélkül, a parancs úgy fut, mintha a natív paramétert adta volna meg. Ez megakadályozza, hogy az argumentum-befejező a PowerShell parancsparamétereihez dolgozzon. Mindig adja meg a ParameterName paramétert, ha argumentumkijelölőt szeretne regisztrálni a PowerShell-parancsokhoz.

Példák

1. példa: Egyéni argumentum-befejező regisztrálása

Az alábbi példa egy argumentum-befejezőt regisztrál a Set-TimeZone parancsmag Azonosító paraméteréhez.

$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

Az első parancs létrehoz egy szkriptblokkot, amely a szükséges paramétereket veszi figyelembe, amelyeket a felhasználó a Tab billentyű lenyomásakor ad át. További információ: ScriptBlock paraméter leírása.

A szkriptblokkon belül a rendszer a parancsmaggal kéri le az Get-TimeZone azonosító rendelkezésre álló értékeit. Az egyes időzónák id tulajdonsága a Where-Object parancsmagba van állítva. A Where-Object parancsmag kiszűri azokat az azonosítókat, amelyek nem az általuk $wordToCompletemegadott értékkel kezdődnek, ami azt a szöveget jelöli, amelyet a felhasználó a Tab billentyű lenyomása előtt írt be. A szűrt azonosítók a ForEach-Object parancsmagba vannak állítva, amely az egyes értékeket idézőjelekbe foglalja a szóközöket tartalmazó értékek kezeléséhez.

A második parancs regisztrálja az argumentum-befejezőt a szkriptblokk, a ParameterName azonosító és a CommandName Set-TimeZoneátengedésével.

2. példa: Részletek hozzáadása a lap kitöltési értékeihez

Az alábbi példa felülírja a parancsmag Név paraméterének lapkimenetét Stop-Service , és csak futó szolgáltatásokat ad vissza.

$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

Az első parancs létrehoz egy szkriptblokkot, amely a szükséges paramétereket veszi figyelembe, amelyeket a felhasználó a Tab billentyű lenyomásakor ad át. További információ: ScriptBlock paraméter leírása.

A szkriptblokkon belül az első parancs lekéri az összes futó szolgáltatást a Where-Object parancsmag használatával. A szolgáltatások a parancsmagra ForEach-Object vannak állítva. A ForEach-Object parancsmag létrehoz egy új System.Management.Automation.CompletionResult objektumot, és feltölti az aktuális szolgáltatás nevével (amelyet a folyamatváltozó $_.Namejelöl).

A CompletionResult objektum lehetővé teszi az egyes visszaadott értékek további részleteinek megadását:

• completionText (String) – Az automatikus befejezési eredményként használandó szöveg. Ez a parancsnak küldött érték.
• listItemText (String) – A listában megjelenítendő szöveg, például amikor a felhasználó lenyomja a Ctrl Szóköz billentyűkombinációt+. A PowerShell ezt csak megjelenítésre használja. A rendszer nem továbbítja a parancsnak, ha ki van választva.
• resultType (CompletionResultType) – A befejezési eredmény típusa.
• elemleírás (sztring) – Az elemleírás szövege az objektumról megjelenítendő részletekkel. Ez akkor jelenik meg, ha a felhasználó kijelöl egy elemet a Ctrl Szóköz billentyűkombináció+lenyomása után.

3. példa: Egyéni natív argumentum-befejező regisztrálása

A natív paraméterrel tabulátorkiegészítést biztosíthat egy natív parancshoz. Az alábbi példa tabulátorkiegészítést ad a dotnet parancssori felülethez (CLI).

Feljegyzés

A dotnet complete parancs csak a dotnet cli 2.0-s és újabb verziójában érhető el.

$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

Az első parancs létrehoz egy szkriptblokkot, amely a szükséges paramétereket veszi figyelembe, amelyeket a felhasználó a Tab billentyű lenyomásakor ad át. További információ: ScriptBlock paraméter leírása.

A szkriptblokkon belül a dotnet complete parancs végrehajtja a tabulátor befejezését. Az eredmények a ForEach-Object parancsmagra vannak állítva, amely a System.Management.Automation.CompletionResult osztály új statikus metódusával hoz létre egy CompletionResult objektumot minden értékhez.

Paraméterek

-CommandName

Egy vagy több parancs nevét adja meg az argumentum-kiegészítés regisztrálásához. Ez a paraméter natív parancsok esetén kötelező.

Ha ezt a paramétert a ParameterName vagy a natív paraméterek nélkül adja meg, a parancs úgy viselkedik, mintha a natív paramétert adta volna meg. A PowerShell-parancsok argumentum-befejezőinek regisztrálásakor mindig adja meg a ParameterName paramétert.

Ha nem adja meg ezt a paramétert, a PowerShell az összes PowerShell-parancson regisztrálja a megadott ParameterName argumentum-befejezőt.

Típus:	String[]
Position:	Named
Alapértelmezett érték:	None
Kötelező:	False
Folyamatbemenet elfogadása:	False
Helyettesítő karakterek elfogadása:	False

-Native

Azt jelzi, hogy az argumentum-befejező egy natív parancshoz tartozik, ahol a PowerShell nem tudja befejezni a paraméterneveket.

Típus:	SwitchParameter
Position:	Named
Alapértelmezett érték:	None
Kötelező:	False
Folyamatbemenet elfogadása:	False
Helyettesítő karakterek elfogadása:	False

-ParameterName

Megadja annak a paraméternek a nevét, amelyre az argumentum-befejező vonatkozik. A megadott paraméterek típusa nem lehet számbavétel, például a parancsmag ForegroundColor paramétere Write-Host .

A számokkal kapcsolatos további információkért lásd: about_Enum.

A PowerShell-parancsok argumentum-kiegészítésének regisztrálásakor mindig adja meg ezt a paramétert. Ha a CommandName paramétert paraméternév vagy natív paraméterek nélkül adja meg, a parancs úgy viselkedik, mintha a natív paramétert adta volna meg.

Típus:	String
Position:	Named
Alapértelmezett érték:	None
Kötelező:	True
Folyamatbemenet elfogadása:	False
Helyettesítő karakterek elfogadása:	False

-ScriptBlock

Megadja a tabulátor befejezéséhez futtatandó parancsokat. A megadott szkriptblokknak a bemenetet befejező értékeket kell visszaadnia. A szkriptblokknak fel kell vennie az értékek regisztrációját a folyamat (ForEach-Objectstb Where-Object.) vagy egy másik megfelelő módszer használatával. Ha értéktömböt ad vissza, a PowerShell a teljes tömböt egyetlen lapkiegészítési értékként kezeli.

A szkriptblokk a System.Management.Automation.CompletionResult objektumokat is visszaadhatja az egyes értékekhez a felhasználói élmény fokozása érdekében. A CompletionResult objektumok visszaadásával elemleírásokat és egyéni listabejegyzéseket határozhat meg, amikor a felhasználók a Ctrl Szóköz billentyűkombinációt+lenyomva jelenítik meg az elérhető befejezések listáját.

A szkriptblokknak az alábbi paramétereket kell elfogadnia az alább megadott sorrendben. A paraméterek neve nem fontos, mert a PowerShell pozíció szerint adja át az értékeket.

• $commandName (0. pozíció, Sztring) – Ez a paraméter annak a parancsnak a nevére van beállítva, amelyhez a szkriptblokk lapkizárást biztosít.
• $parameterName (1. pozíció, Sztring) – Ez a paraméter arra a paraméterre van beállítva, amelynek értéke lapkiegészítést igényel.
• $wordToComplete(2. pozíció, Karakterlánc) – Ez a paraméter úgy van beállítva, hogy a felhasználó a Tab billentyű lenyomása előtt megadott értéket adja meg. A szkriptblokknak ezt az értéket kell használnia a lapkiegészítési értékek meghatározásához.
• $commandAst (3. pozíció, CommandAst) – Ez a paraméter az aktuális bemeneti sor absztrakt szintaxisfára (AST) van állítva. További információt a CommandAst osztályban talál.
• $fakeBoundParameters(4. pozícióIDictionary) – Ez a paraméter egy kivonatolóra van állítva, amely tartalmazza a $PSBoundParameters parancsmagot, mielőtt a felhasználó lenyomta a Tab billentyűt. További információ: about_Automatic_Variables.

A natív paraméter megadásakor a szkriptblokknak a következő paramétereket kell figyelembe vennie a megadott sorrendben. A paraméterek neve nem fontos, mert a PowerShell pozíció szerint adja át az értékeket.

• $wordToComplete(0. pozíció, Karakterlánc) – Ez a paraméter úgy van beállítva, hogy a felhasználó a Tab billentyű lenyomása előtt megadott értéket adja meg. A szkriptblokknak ezt az értéket kell használnia a lapkiegészítési értékek meghatározásához.
• $commandAst (1. pozíció, CommandAst) – Ez a paraméter az aktuális bemeneti sor absztrakt szintaxisfára (AST) van állítva. További információt a CommandAst osztályban talál.
• $cursorPosition (2. pozíció, Int32) – Ez a paraméter a kurzor pozíciójára van állítva, amikor a felhasználó lenyomta a Tab billentyűt.

Paraméterattribútumként argumentumkiegészítőt is megadhat. További információ: about_Functions_Advanced_Parameters.

Típus:	ScriptBlock
Position:	Named
Alapértelmezett érték:	None
Kötelező:	True
Folyamatbemenet elfogadása:	False
Helyettesítő karakterek elfogadása:	False

Bevitelek

None

Ehhez a parancsmaghoz nem lehet objektumokat csövezni.

Kimenetek

None

Ez a parancsmag nem ad vissza kimenetet.

Kapcsolódó hivatkozások

• about_Functions_Argument_Completion