Register-ArgumentCompleter

Módulo:

Microsoft.PowerShell.Core

Registra un completador de argumentos personalizado.

Syntax

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

$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 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, si el valor contiene espacios.

El segundo comando registra el completador de argumentos pasando el scriptblock, parameterName Id y 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 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,
            $_.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 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. Se usa solo para mostrar y no se pasa al comando cuando se selecciona.
• resultType (CompletionResultType): el tipo de resultado de finalización.
• toolTip (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 Stop-Service cmdlet . 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 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($_, $_, '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 dotnet complete comando se usa para realizar 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 nuevo objeto CompletionResult para cada valor.

Parámetros

-CommandName

Especifica el nombre de los comandos como una matriz.

Type:	String[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 Write-Host cmdlet.

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

Type:	String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	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 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): 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 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.

Type:	ScriptBlock
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

Entradas

None

No se pueden canalizar objetos a este cmdlet.

Salidas

None

Este cmdlet no devuelve ningún resultado.