Registro-ArgumentCompleter (Microsoft.PowerShell.Core)

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>]

Descripción

El cmdlet Register-ArgumentCompleter registra un completador de argumentos personalizado. Un completador de argumentos le permite proporcionar finalización de tabulación dinámica, en tiempo de ejecución, para cualquier comando que especifique.

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

Ejemplos

Ejemplo 1: registrar un completador de argumentos personalizado

El siguiente ejemplo registra un completador de argumentos para el parámetro Id del cmdlet Set-TimeZone.

$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 requeridos, 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 secuencia de comandos, 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 cualquier ID que no comience con el valor proporcionado por $wordToComplete, que representa el texto que el usuario escribió antes de presionar Tab. . Los identificadores filtrados se canalizan al cmdlet ForEach-Object, que encierra cada valor entre comillas para manejar los valores que contienen espacios.

El segundo comando registra el argumento completo pasando el bloque de script, el ParameterName Id y el CommandName Set-TimeZone.

Ejemplo 2: agregar detalles a los valores de finalización de pestañas

El siguiente ejemplo sobrescribe la finalización de tabulación para el parámetro Name del cmdlet Stop-Service 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          # completionText
            $_.Name          # listItemText
            'ParameterValue' # resultType
            $_.Name          # toolTip
        )
    }
}

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

Dentro del bloque de secuencia de comandos, 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 completa 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 (Cadena): el texto que se utilizará como resultado de la finalización automática. Este es el valor enviado al comando.
listItemText (Cadena): el texto que se mostrará en una lista, como cuando el usuario presiona Ctrl+Espacio. PowerShell usa esto solo para visualización. No se pasa al comando cuando se selecciona.
resultType (CompletionResultType): el tipo de resultado de finalización.
toolTip (Cadena): 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.

Ejemplo 3: registrar un completador de argumentos nativo personalizado

Puede utilizar el parámetro Native para proporcionar tabulación para un comando nativo. El siguiente ejemplo agrega tabulación para la interfaz de línea de comandos (CLI) dotnet.

Nota

El comando dotnet complete solo está disponible en la versión 2.0 y posteriores de 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

Dentro del bloque de secuencia de comandos, el comando dotnet complete realiza la finalización de tabulación. Los resultados se canalizan al cmdlet ForEach-Object, que utiliza el nuevo método estático de la clase System.Management.Automation.CompletionResult para crear un CompletionResult. objeto para cada valor.

Parámetros

-CommandName

Especifica el nombre de uno o más comandos para registrar el completador de argumentos. Este parámetro es obligatorio para los comandos nativos.

Cuando especifica 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 complemento de argumento para el ParameterName especificado en todos los comandos de PowerShell.

Tipo :: String[]
Posición:: Nombrado
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 donde PowerShell no puede completar los nombres de los parámetros.

Tipo :: SwitchParameter
Posición:: Nombrado
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 de argumentos. El tipo de parámetros especificados no puede ser una enumeración, como el parámetro ForegroundColor del cmdlet Write-Host.

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

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

Tipo :: String
Posición:: Nombrado
Valor predeterminado:: None
Requerido:: True
Aceptar entrada de canalización:: False
Aceptar caracteres comodín:: False

-ScriptBlock

Especifica los comandos que se ejecutarán para completar la tabulación. El bloque de script que proporcione debe devolver los valores que completan la entrada. El bloque de secuencia de comandos debe desenrollar los valores utilizando la canalización (ForEach-Object, Where-Object, etc.) u otro método adecuado. Al devolver una matriz de valores, PowerShell trata la matriz completa como un valor de finalización de una pestaña.

El bloque de secuencia de comandos también puede devolver objetos System.Management.Automation.CompletionResult para cada valor para mejorar la experiencia del usuario. Devolver objetos CompletionResult le 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 terminaciones disponibles.

El bloque de script debe aceptar los siguientes parámetros 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, Cadena): este parámetro se establece en el nombre del comando para el cual el bloque de script proporciona finalización de tabulación.
$parameterName (Posición 1, Cadena): este parámetro se establece en el parámetro cuyo valor requiere completar con tabulación.
$wordToComplete (Posición 2, Cadena): este parámetro se establece en el valor que el usuario proporcionó antes de presionar Tab. Su 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, consulte Clase CommandAst.
$fakeBoundParameters (Posición 4 IDictionary): este parámetro se establece en una tabla hash que contiene $PSBoundParameters para el cmdlet, antes de que el usuario presionara Pestaña. Para obtener más información, consulte about_Automatic_Variables.

Cuando especifica el parámetro Nativo, el bloque de script debe tomar los siguientes parámetros 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, Cadena): este parámetro se establece en el valor que el usuario proporcionó antes de presionar Tab. Su 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, consulte Clase CommandAst.
$cursorPosition (Posición 2, Int32): este parámetro se establece en la posición del cursor cuando el usuario presionó 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:: Nombrado
Valor predeterminado:: None
Requerido:: True
Aceptar entrada de canalización:: False
Aceptar caracteres comodín:: False

Entradas

Ninguno

No puede canalizar objetos a este cmdlet.

Salidas