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.

Cuando se llama a este comando con el parámetro CommandName y sin los parámetros ParameterName o Native, el comando se ejecuta como si especificase el parámetro Native. Esto impide que el completador de argumentos funcione para los parámetros de comando de PowerShell. Especifique siempre el parámetro ParameterName cuando desee registrar un completador de argumentos para los comandos de PowerShell.

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 del Set-TimeZone cmdlet.

$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

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 Get-TimeZone cmdlet . La propiedad Id para cada zona horaria se canaliza al Where-Object cmdlet . El Where-Object cmdlet 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 ForEach-Object cmdlet , que incluye cada valor entre comillas para controlar los valores que contienen espacios.

El segundo comando registra el completador del argumento pasando el scriptblock, parameterName Id y CommandName . Set-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 Stop-Service cmdlet y solo se devuelven los 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          # completionText
            $_.Name          # listItemText
            'ParameterValue' # resultType
            $_.Name          # toolTip
        )
    }
}

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 Where-Object cmdlet . Los servicios se canalizan al ForEach-Object cmdlet . El ForEach-Object cmdlet crea un nuevo objeto System.Management.Automation.CompletionResult y lo rellena con el nombre del servicio actual (representado por la variable $_.Namede canalización ).

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

• completionText (String): el texto que se va a 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. PowerShell solo lo usa para mostrar. No se pasa al comando cuando está seleccionado.
• resultType (CompletionResultType): el tipo de resultado de finalización.
• toolTip (String): el texto de la información sobre herramientas con detalles para mostrar sobre el objeto. Esto es visible cuando el usuario selecciona un elemento después de presionar Ctrl+Espacio.

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 la dotnet línea de comandos (CLI).

Nota:

El dotnet complete comando 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(
            $_,               # completionText
            $_,               # listItemText
            'ParameterValue', # resultType
            $_                # toolTip
        )
    }
}

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 dotnet complete comando realiza la finalización de la pestaña. Los resultados se canalizan al ForEach-Object cmdlet , 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 uno o varios comandos para los que se va a registrar el completador del argumento. Este parámetro es obligatorio para los comandos nativos.

Al especificar este parámetro sin los parámetros ParameterName o Native , el comando se comporta como si hubiera especificado el parámetro Native . Al registrar completadores de argumentos para comandos de PowerShell, especifique siempre el parámetro ParameterName .

Si no especifica este parámetro, PowerShell registra el completador de argumentos para el parameterName especificado en todos los comandos de PowerShell.

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 al que se aplica el completador del argumento. El tipo para los parámetros especificados no puede ser una enumeración, como el parámetro ForegroundColor del Write-Host cmdlet .

Para obtener más información sobre las enumeraciones, consulte about_Enum.

Al registrar un completador de argumentos para comandos de PowerShell, especifique siempre este parámetro. Al especificar el parámetro CommandName sin los parámetros ParameterName o Native, el comando se comporta como si especificó el parámetro Native.

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

El bloque de script también puede devolver objetos System.Management.Automation.CompletionResult para cada valor para mejorar la experiencia del usuario. Devolver objetos CompletionResult permite definir información sobre herramientas y entradas de lista personalizadas que se muestran cuando los usuarios presionan Ctrl+Espacio para mostrar la lista de finalizaciones disponibles.

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, String): 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, String): este parámetro se establece en el parámetro cuyo valor requiere finalización de tabulación.
• $wordToComplete (Posición 2, String): este parámetro se establece en el valor que el usuario ha proporcionado 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, CommandAst): 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 CommandAst Class.
• $fakeBoundParameters (Posición 4 IDictionary): 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, String): este parámetro se establece en el valor que el usuario ha proporcionado 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, CommandAst): 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 CommandAst Class.
• $cursorPosition (Posición 2, Int32): este parámetro se establece en la posición del cursor cuando el usuario presiona la pestaña.

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 ningún resultado.

Vínculos relacionados

• about_Functions_Argument_Completion