Register-ArgumentCompleter

Módulo:

Microsoft.PowerShell.Core

Registra un completador de argumentos personalizado.

Sintaxis

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

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

Description

El Register-ArgumentCompleter cmdlet 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 ScriptBlock.

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 ForEach-Object que incluye cada valor entre comillas, si el valor contiene espacios.

El segundo comando registra el completador de argumentos pasando el scriptblock, el ParameterNameId 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 del cmdlet y solo devuelve servicios en ejecución.

$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

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 ScriptBlock.

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 el nombre del servicio actual (representado por la variable de canalización $_.Name).

El objeto CompletionResult le permite proporcionar detalles adicionales a cada valor devuelto:

• 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+Espacio. 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+Espacio.

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($wordToComplete, $commandAst, $cursorPosition)
        dotnet complete --position $cursorPosition $commandAst.ToString() | 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 ScriptBlock.

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 método estático de la clase System.Management.Automation.CompletionResult para crear un 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 que completan la entrada. El bloque de script debe anular la inscripción de los valores mediante la canalización (ForEach-Object, Where-Object, etc.) 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.

El bloque de script 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 por posición.

• $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.
• $fakeBoundParameters (Posición 4): este parámetro se establece en una tabla hash que contiene para $PSBoundParameters el cmdlet, antes de que el usuario presione tab. Para obtener más información, consulte 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 por posición.

• $wordToComplete (Posición 0): 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 1): 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.
• $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, consulte 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.