Register-ArgumentCompleter
Registra un completador de argumentos personalizado.
Sintaxis
Register-ArgumentCompleter
[-CommandName <String[]>]
-ParameterName <String>
-ScriptBlock <ScriptBlock>
[<CommonParameters>]
Register-ArgumentCompleter
-CommandName <String[]>
-ScriptBlock <ScriptBlock>
[-Native]
[<CommonParameters>]
Description
El cmdlet Register-ArgumentCompleter
registra un completador de argumentos personalizado. Un completador de argumentos permite proporcionar finalización dinámica de tabulaciones, en tiempo de ejecución para cualquier comando que especifique.
Ejemplos
Ejemplo 1: Registro de un completador de argumentos personalizado
En el ejemplo siguiente se registra un completador de argumentos para el parámetro id. de del cmdlet 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
El primer comando crea un bloque de script que toma los parámetros necesarios que se pasan cuando el usuario presiona <TAB>
. Para obtener más información, consulte la descripción del parámetro
Dentro del bloque de script, los valores disponibles para Id se recuperan mediante el cmdlet Get-TimeZone
. La propiedad Id para cada zona horaria se canaliza al cmdlet Where-Object
.
El cmdlet Where-Object
filtra los identificadores que no empiezan por el valor proporcionado por $wordToComplete
, que representa el texto que el usuario ha escrito antes de presionar <TAB>
. Los identificadores filtrados se canalizan al cmdlet For-EachObject
que incluye cada valor entre comillas, si el valor contiene espacios.
El segundo comando registra el completador de argumentos pasando el scriptblock, el ParameterName "Id" y el CommandNameSet-TimeZone
.
Ejemplo 2: Agregar detalles a los valores de finalización de la pestaña
En el ejemplo siguiente se sobrescribe la finalización de la pestaña para el parámetro name
$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
El primer comando crea un bloque de script que toma los parámetros necesarios que se pasan cuando el usuario presiona <TAB>
. Para obtener más información, consulte la descripción del parámetro
Dentro del bloque de script, el primer comando recupera todos los servicios en ejecución mediante el cmdlet Where-Object
. Los servicios se canalizan al cmdlet ForEach-Object
. El cmdlet ForEach-Object
crea un nuevo objeto [System.Management.Automation.CompletionResult]
y lo rellena con los valores del servicio actual (representado por la variable de canalización $_
).
El objeto
- completionText (String): el texto que se usará como resultado de finalización automática. Este es el valor enviado al comando .
-
listItemText (String): el texto que se va a mostrar en una lista, como cuando el usuario presiona
<Ctrl>+<Space>
. Se usa solo para mostrar y no se pasa al comando cuando se selecciona. - resultType (CompletionResultType): tipo de resultado de finalización.
-
información sobre herramientas (string): el texto de la información sobre herramientas con detalles que se mostrarán sobre el objeto.
Esto es visible cuando el usuario selecciona un elemento después de presionar
<Ctrl>+<Space>
.
El último comando muestra que los servicios detenidos todavía se pueden pasar manualmente al cmdlet Stop-Service
. La finalización de la pestaña es el único aspecto afectado.
Ejemplo 3: Registro de un completor de argumentos nativos personalizado
Puede usar el parámetro Native para proporcionar la finalización de tabulación para un comando nativo. En el ejemplo siguiente se agrega la finalización de tabulación para la interfaz de línea de comandos (CLI) de dotnet
.
Nota
El comando dotnet complete
solo está disponible en la versión 2.0 y posterior de la cli de dotnet.
$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
El primer comando crea un bloque de script que toma los parámetros necesarios que se pasan cuando el usuario presiona <TAB>
. Para obtener más información, consulte la descripción del parámetro
Dentro del bloque de script, el comando dotnet complete
se usa para realizar la finalización de la pestaña.
Los resultados se canalizan al cmdlet ForEach-Object
que usa el nuevo nuevo método estático de la clase [System.Management.Automation.CompletionResult]
para crear un nuevo objeto CompletionResult para cada valor.
Parámetros
-CommandName
Especifica el nombre de los comandos como una matriz.
Tipo: | String[] |
Posición: | Named |
Valor predeterminado: | None |
Requerido: | False |
Aceptar entrada de canalización: | False |
Aceptar caracteres comodín: | False |
-Native
Indica que el completador de argumentos es para un comando nativo en el que PowerShell no puede completar los nombres de parámetro.
Tipo: | SwitchParameter |
Posición: | Named |
Valor predeterminado: | None |
Requerido: | False |
Aceptar entrada de canalización: | False |
Aceptar caracteres comodín: | False |
-ParameterName
Especifica el nombre del parámetro cuyo argumento se está completando. El nombre del parámetro especificado no puede ser un valor enumerado, como el parámetro ForegroundColor del cmdlet Write-Host
.
Para obtener más información sobre las enumeraciones, vea about_Enum.
Tipo: | String |
Posición: | Named |
Valor predeterminado: | None |
Requerido: | True |
Aceptar entrada de canalización: | False |
Aceptar caracteres comodín: | False |
-ScriptBlock
Especifica los comandos que se van a ejecutar para realizar la finalización de tabulación. El bloque de script que proporcione debe devolver los valores para completar la entrada. El bloque de script debe anular la inscripción de los valores mediante la canalización (ForEach-Object
, Where-Object
, etcetera.) u otro método adecuado. Devolver una matriz de valores hace que PowerShell trate toda la matriz como un valor de finalización de tabulación de.
El bloque de script también debe aceptar los parámetros siguientes en el orden especificado a continuación. Los nombres de los parámetros no son importantes porque PowerShell pasa los valores posicionalmente.
-
$commandName
(posición 0): este parámetro se establece en el nombre del comando para el que el bloque de script proporciona finalización de tabulación. -
$parameterName
(posición 1): este parámetro se establece en el parámetro cuyo valor requiere finalización de tabulación. -
$wordToComplete
(Posición 2): este parámetro se establece en el valor proporcionado por el usuario antes de presionar<TAB>
. El bloque de script debe usar este valor para determinar los valores de finalización de tabulación. -
$commandAst
(posición 3): este parámetro se establece en el árbol de sintaxis abstracta (AST) para la línea de entrada actual. Para obtener más información, vea clase Ast. -
$fakeBoundParameter
(posición 4): este parámetro se establece en una tabla hash que contiene el$PSBoundParameters
del cmdlet, antes de que el usuario presione<TAB>
. Para obtener más información, vea about_Automatic_Variables.
Al especificar el parámetro native, el bloque de script debe tomar los parámetros siguientes en el orden especificado. Los nombres de los parámetros no son importantes porque PowerShell pasa los valores posicionalmente.
-
$commandName
(posición 0): este parámetro se establece en el nombre del comando para el que el bloque de script proporciona finalización de tabulación. -
$wordToComplete
(Posición 1): este parámetro se establece en el valor proporcionado por el usuario antes de presionar<TAB>
. El bloque de script debe usar este valor para determinar los valores de finalización de tabulación. -
$cursorPosition
(posición 2): este parámetro se establece en la posición del cursor cuando el usuario presionaba<TAB>
.
También puede proporcionar un argumentCompleter como atributo de parámetro. Para obtener más información, vea about_Functions_Advanced_Parameters.
Tipo: | ScriptBlock |
Posición: | Named |
Valor predeterminado: | None |
Requerido: | True |
Aceptar entrada de canalización: | False |
Aceptar caracteres comodín: | False |
Entradas
None
No se pueden canalizar objetos a este cmdlet.
Salidas
None
Este cmdlet no devuelve ninguna salida.