Register-ArgumentCompleter

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

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

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.

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 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 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 Where-Object cmdlet filtra los identificadores que no comienzan con el valor proporcionado por $wordToComplete, que representa el texto que el usuario escribió antes de presionar Tab. Los identificadores filtrados se canalizan al ForEach-Object cmdlet que incluye cada valor entre comillas, en caso de que el valor contenga espacios.

El segundo comando registra el completador de argumentos pasando el scriptblock, parameterNameId y CommandNameSet-TimeZone.

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

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.

$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 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 script, el comando dotnet complete 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.

Este cmdlet admite los parámetros comunes: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction y -WarningVariable. Para obtener más información, vea about_CommonParameters.

No se pueden canalizar objetos a este cmdlet.

Este cmdlet no devuelve ninguna salida.