about_Functions_Argument_Completion
Descripción breve
La finalización de argumentos es una característica de PowerShell que proporciona sugerencias, habilita la detección y acelera la entrada de entrada de los valores de argumento.
Descripción larga
En este artículo se describen las distintas formas en que puede implementar completadores de argumentos para las funciones de PowerShell. Los completadores de argumentos proporcionan los valores posibles para un parámetro. Los valores disponibles se calculan en tiempo de ejecución cuando el usuario presiona la tecla Tab después del nombre del parámetro. Hay varias maneras de definir un completador de argumentos para un parámetro.
Nota:
Tab es el enlace de claves predeterminado en Windows. Este enlace de claves se puede cambiar mediante el módulo PSReadLine o la aplicación que hospeda PowerShell. El enlace de claves es diferente en plataformas que no son de Windows. Para más información, vea Acerca de PSReadLine.
Atributo ValidateSet
El atributo ValidateSet especifica un conjunto de valores válidos para un parámetro o variable y habilita la finalización de tabulaciones. PowerShell genera un error si un parámetro o valor de variable no coincide con un valor del conjunto. En el ejemplo siguiente, el valor del parámetro Fruit solo puede ser Apple, Banana o Pear.
Param(
[Parameter(Mandatory=$true)]
[ValidateSet('Apple', 'Banana', 'Pear')]
[string[]]
$Fruit
)
En el ejemplo siguiente, el valor de la variable $flavor debe ser Chocolate, Fresa o Vainilla. El ValidateSet atributo se puede usar en cualquier variable, no solo en parámetros.
[ValidateSet('Chocolate', 'Strawberry', 'Vanilla')]
[string]$flavor = 'Strawberry'
La validación se produce cada vez que se asigna esa variable incluso dentro del script.
Param(
[ValidateSet('hello', 'world')]
[string]$Message
)
$Message = 'bye'
En este ejemplo se devuelve el siguiente error en tiempo de ejecución:
MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.
Para obtener más información sobre la expansión de pestañas, consulte about_Tab_Expansion.
Valores ValidateSet dinámicos mediante clases
Puede usar una clase para generar dinámicamente los valores de ValidateSet en tiempo de ejecución. En el ejemplo siguiente, los valores válidos para la variable $Sound se generan a través de una clase denominada SoundNames que comprueba tres rutas de acceso del sistema de archivos para los archivos de sonido disponibles:
Class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
[string[]] GetValidValues() {
$SoundPaths = '/System/Library/Sounds/',
'/Library/Sounds',
'~/Library/Sounds'
$SoundNames = ForEach ($SoundPath in $SoundPaths) {
If (Test-Path $SoundPath) {
(Get-ChildItem $SoundPath).BaseName
}
}
return [string[]] $SoundNames
}
}
A continuación, la [SoundNames] clase se implementa como un valor ValidateSet dinámico como se indica a continuación:
Param(
[ValidateSet([SoundNames])]
[string]$Sound
)
Nota:
La IValidateSetValuesGenerator clase se introdujo en PowerShell 6.0.
Atributo ArgumentCompletions
El atributo ArgumentCompletions permite agregar valores de finalización de tabulación a un parámetro específico. Se debe definir un atributo ArgumentCompletions para cada parámetro que necesite finalización de tabulación. El atributo ArgumentCompletions es similar a ValidateSet. Ambos atributos toman una lista de valores que se van a presentar cuando el usuario presiona Tab después del nombre del parámetro. Sin embargo, a diferencia de ValidateSet, los valores no se validan y son más similares a las sugerencias. Por lo tanto, el usuario puede proporcionar cualquier valor, no solo los valores de la lista.
El atributo ArgumentCompletions no debe confundirse con el atributo ArgumentCompleter , que necesita un bloque de scripts para definir las opciones. los valores especificados están disponibles
La sintaxis es la siguiente:
function Test-ArgumentCompletions {
[CmdletBinding()]
param (
[Parameter(Mandatory=$true)]
[ArgumentCompletions('Fruits', 'Vegetables')]
$Type,
[Parameter()]
[ArgumentCompletions('Apple', 'Banana', 'Orange')]
$Fruit,
[Parameter()]
[ArgumentCompletions('Onion', 'Carrot', 'Lettuce')]
$Vegetable
)
}
Cada uno de los parámetros se proporciona una lista de opciones al atributo ArgumentCompletions para habilitar la finalización de tabulaciones.
Este atributo se introdujo en PowerShell 6.0.
Atributo ArgumentCompleter
El atributo ArgumentCompleter permite agregar valores de finalización de tabulación a un parámetro específico. Se debe definir un atributo ArgumentCompleter para cada parámetro que necesite finalización de tabulación.
Para agregar un atributo ArgumentCompleter , debe definir un bloque de script que determine los valores. El bloque de script debe tomar los parámetros siguientes en el orden especificado a continuación. Los nombres del parámetro no importan, ya que los valores se proporcionan de forma posicional.
La sintaxis es la siguiente:
function MyArgumentCompleter {
Param(
[Parameter(Mandatory)]
[ArgumentCompleter( {
param ( $commandName,
$parameterName,
$wordToComplete,
$commandAst,
$fakeBoundParameters )
# Perform calculation of tab completed values here.
} )]
$ParamName
)
}
Bloque de script ArgumentCompleter
Los parámetros de bloque de script se establecen en los valores siguientes:
$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, consulte la documentación del tipo AST .$fakeBoundParameters(Posición 4): este parámetro se establece en una tabla hash que contiene para$PSBoundParametersel cmdlet, antes de que el usuario presione tab. Para obtener más información, consulte about_Automatic_Variables.
El bloque de script ArgumentCompleter debe anular la inscripción de los valores mediante la canalización, como ForEach-Object, Where-Objectu 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.
En el ejemplo siguiente se agrega la finalización de tabulación al parámetro Value . Si solo se especifica el parámetro Value , se muestran todos los valores posibles o argumentos para Value . Cuando se especifica el parámetro Type , el parámetro Value solo muestra los valores posibles para ese tipo.
Además, el -like operador garantiza que si el usuario escribe el siguiente comando y usa la finalización de tabulación , solo se devuelve Apple .
Test-ArgumentCompleter -Type Fruits -Value A
function MyArgumentCompleter{
param ( $commandName,
$parameterName,
$wordToComplete,
$commandAst,
$fakeBoundParameters )
$possibleValues = @{
Fruits = @('Apple', 'Orange', 'Banana')
Vegetables = @('Onion', 'Carrot', 'Lettuce')
}
if ($fakeBoundParameters.ContainsKey('Type')) {
$possibleValues[$fakeBoundParameters.Type] | Where-Object {
$_ -like "$wordToComplete*"
}
} else {
$possibleValues.Values | ForEach-Object {$_}
}
}
function Test-ArgumentCompleter {
[CmdletBinding()]
param (
[Parameter(Mandatory=$true)]
[ValidateSet('Fruits', 'Vegetables')]
$Type,
[Parameter(Mandatory=$true)]
[ArgumentCompleter({ MyArgumentCompleter @args })]
$Value
)
}
Completadores de argumentos basados en clases
A partir de PowerShell 7.2, se ha agregado una nueva característica que permite definir implementaciones más genéricas de completadores de argumentos con parámetros.
Al derivar de ArgumentCompleterAttribute, es posible crear completos genéricos que se pueden reutilizar, por ejemplo:
[DirectoryCompleter(ContainingFile="pswh.exe", Depth=2)]
[DateCompleter(WeekDay='Monday', From="LastYear")]
[GitCommits(Branch='release')]
Los atributos derivados deben implementar la IArgumentCompleterFactory interfaz y usar valores de propiedad para crear un completor especializado.
using namespace System.Collections
using namespace System.Collections.Generic
using namespace System.Management.Automation
using namespace System.Management.Automation.Language
class NumberCompleter : IArgumentCompleter {
[int] $From
[int] $To
[int] $Step
NumberCompleter([int] $from, [int] $to, [int] $step) {
if ($from -gt $to) {
throw [ArgumentOutOfRangeException]::new("from")
}
$this.From = $from
$this.To = $to
$this.Step = $step -lt 1 ? 1 : $step
}
[IEnumerable[CompletionResult]] CompleteArgument(
[string] $CommandName,
[string] $parameterName,
[string] $wordToComplete,
[CommandAst] $commandAst,
[IDictionary] $fakeBoundParameters) {
$resultList = [List[CompletionResult]]::new()
$local:to = $this.To
$local:step = $this.Step
for ($i = $this.From; $i -lt $to; $i += $step) {
$resultList.Add([CompletionResult]::new($i.ToString()))
}
return $resultList
}
}
class NumberCompletionsAttribute : ArgumentCompleterAttribute, IArgumentCompleterFactory {
[int] $From
[int] $To
[int] $Step
NumberCompletionsAttribute([int] $from, [int] $to, [int] $step) {
$this.From = $from
$this.To = $to
$this.Step = $step
}
[IArgumentCompleter] Create() { return [NumberCompleter]::new($this.From, $this.To, $this.Step) }
}
El uso de PowerShell sería:
function Add{
param(
[NumberCompletions(0, 100, 5)]
[int] $X,
[NumberCompletions(0, 100, 5)]
[int] $Y
)
$X + $Y
}
Register-ArgumentCompleter
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.
Para más información, vea Register-ArgumentCompleter.
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de