From c8b5bef0d1f7c86185feca0daa0a15b8f3d75851 Mon Sep 17 00:00:00 2001 From: "Mikey Lombardi (He/Him)" Date: Wed, 10 Jul 2024 15:37:56 -0500 Subject: [PATCH] (GH-11248) Clarify behavior for `Register-ArgumentCompleter` parameters (#11249) * (GH-11248) Clarify behavior for `Register-ArgumentCompleter` parameters Prior to this change, the `Register-ArgumentCompleter` reference didn't indicate that specifying the **CommandName** parameter without the **ParameterName** or **Native** parameters causes the command to behave as if the user specified the `-Native` switch. This change: - Clarifies that users should always specify the **ParameterName** parameter when registering an argument completer for a PowerShell command. - Resolves #11248 - Fixes AB#281953 * (MAINT) Clarify and update `Register-ArgumentCompleter` This change adds further clarification to various sections of the reference documentation for `Register-ArgumentCompleter`. It also addresses some style and formatting issues. --- .../Register-ArgumentCompleter.md | 175 ++++++++++++------ .../Register-ArgumentCompleter.md | 175 ++++++++++++------ .../Register-ArgumentCompleter.md | 175 ++++++++++++------ .../Register-ArgumentCompleter.md | 175 ++++++++++++------ 4 files changed, 468 insertions(+), 232 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md b/reference/5.1/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md index 6b3f21bf081b..ac3d2367be56 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 12/09/2022 +ms.date: 07/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/register-argumentcompleter?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Register-ArgumentCompleter @@ -36,6 +36,12 @@ The `Register-ArgumentCompleter` cmdlet registers a custom argument completer. A completer allows you to provide dynamic tab completion, at run time for any command that you specify. +When you call this command with the **CommandName** parameter and without the **ParameterName** or +**Native** parameters, the command runs as if you specified the **Native** parameter. This prevents +the argument completer from working for PowerShell command parameters. Always specify the +**ParameterName** parameter when you want to register an argument completer for PowerShell +commands. + ## EXAMPLES ### Example 1: Register a custom argument completer @@ -44,28 +50,35 @@ The following example registers an argument completer for the **Id** parameter o cmdlet. ```powershell -$scriptBlock = { - param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters) +$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 $scriptBlock + +Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $s ``` -The first command creates a script block which takes the required parameters which are passed in +The first command creates a script block that takes the required parameters, which are passed in when the user presses Tab. For more information, see the **ScriptBlock** parameter description. Within the script block, the available values for **Id** are retrieved using the `Get-TimeZone` cmdlet. The **Id** property for each Time Zone is piped to the `Where-Object` cmdlet. The -`Where-Object` cmdlet filters out any ids that do not start with the value provided by +`Where-Object` cmdlet filters out any ids that don't start with the value provided by `$wordToComplete`, which represents the text the user typed before they pressed Tab. The -filtered ids are piped to the `ForEach-Object` cmdlet which encloses each value in quotes, should -the value contain spaces. +filtered ids are piped to the `ForEach-Object` cmdlet, which encloses each value in quotes to handle +values that contain spaces. The second command registers the argument completer by passing the scriptblock, the **ParameterName** **Id** and the **CommandName** `Set-TimeZone`. @@ -77,41 +90,54 @@ cmdlet and only returns running services. ```powershell $s = { - param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters) - $services = Get-Service | Where-Object {$_.Status -eq "Running" -and $_.Name -like "$wordToComplete*"} + 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 + 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 ``` -The first command creates a script block which takes the required parameters which are passed in +The first command creates a script block that takes the required parameters, which are passed in when the user presses Tab. For more information, see the **ScriptBlock** parameter description. Within the script block, the first command retrieves all running services using the `Where-Object` cmdlet. The services are piped to the `ForEach-Object` cmdlet. The `ForEach-Object` cmdlet creates a new -[`[System.Management.Automation.CompletionResult]`](/dotnet/api/system.management.automation.completionresult) object -and populates it with the values of the current service (represented by the pipeline variable `$_`). +[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) +object and populates it with the name of the current service (represented by the pipeline variable +`$_.Name`). The **CompletionResult** object allows you to provide additional details to each returned value: - **completionText** (String) - The text to be used as the auto completion result. This is the value sent to the command. - **listItemText** (String) - The text to be displayed in a list, such as when the user presses - Ctrl+Space. This is used for display only and is not passed to the command - when selected. -- **resultType** ([CompletionResultType](/dotnet/api/system.management.automation.completionresulttype)) - The type of completion result. -- **toolTip** (String) - The text for the tooltip with details to be displayed about the object. - This is visible when the user selects an item after pressing Ctrl+Space. - -The last command demonstrates that stopped services can still be passed in manually to the -`Stop-Service` cmdlet. The tab completion is the only aspect affected. + Ctrl+Space. PowerShell uses this for display only. It isn't passed to the + command when selected. +- **resultType** + ([CompletionResultType](/dotnet/api/system.management.automation.completionresulttype)) - The + type of completion result. +- **toolTip** (String) - The text for the tooltip with details to display about the object. This is + visible when the user selects an item after pressing Ctrl+Space. ### Example 3: Register a custom Native argument completer @@ -123,28 +149,47 @@ example adds tab-completion for the `dotnet` Command Line Interface (CLI). ```powershell $scriptblock = { - param($wordToComplete, $commandAst, $cursorPosition) - dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object { - [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) - } + 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 ``` -The first command creates a script block which takes the required parameters which are passed in +The first command creates a script block that takes the required parameters, which are passed in when the user presses Tab. For more information, see the **ScriptBlock** parameter description. -Within the script block, the `dotnet complete` command is used to perform the tab completion. -The results are piped to the `ForEach-Object` cmdlet which use the **new** static method of the -[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) class -to create a new **CompletionResult** object for each value. +Within the script block, the `dotnet complete` command performs the tab completion. The results are +piped to the `ForEach-Object` cmdlet, which uses the **new** static method of the +[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) +class to create a **CompletionResult** object for each value. ## PARAMETERS ### -CommandName -Specifies the name of the commands as an array. +Specifies the name of one or more commands to register the argument completer for. This parameter +is mandatory for native commands. + +When you specify this parameter without the **ParameterName** or **Native** parameters, the command +behaves as if you had specified the **Native** parameter. When registering argument completers for +PowerShell commands, always specify the **ParameterName** parameter. + +If you don't specify this parameter, PowerShell registers the argument completer for the specified +**ParameterName** across all PowerShell commands. ```yaml Type: System.String[] @@ -160,7 +205,7 @@ Accept wildcard characters: False ### -Native -Indicates that the argument completer is for a native command where PowerShell cannot complete +Indicates that the argument completer is for a native command where PowerShell can't complete parameter names. ```yaml @@ -177,11 +222,16 @@ Accept wildcard characters: False ### -ParameterName -Specifies the name of the parameter whose argument is being completed. The parameter name specified -cannot be an enumerated value, such as the **ForegroundColor** parameter of the `Write-Host` cmdlet. +Specifies the name of the parameter the argument completer applies to. The type for specified +parameters can't be an enumeration, such as the **ForegroundColor** parameter of the `Write-Host` +cmdlet. For more information on enums, see [about_Enum](./About/about_Enum.md). +When registering an argument completer for PowerShell commands, always specify this parameter. When +you specify the **CommandName** parameter without the **ParameterName** or **Native** parameters, +the command behaves as if you specified the **Native** parameter. + ```yaml Type: System.String Parameter Sets: PowerShellSet @@ -201,35 +251,41 @@ the values that complete the input. The script block must unroll the values usin (`ForEach-Object`, `Where-Object`, etc.), or another suitable method. Returning an array of values causes PowerShell to treat the entire array as **one** tab completion value. +The script block can also return +[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) +objects for each value to enhance the user experience. Returning **CompletionResult** objects +enables you to define tooltips and custom list entries displayed when users press +Ctrl+Space to show the list of available completions. + The script block must accept the following parameters in the order specified below. The names of the parameters aren't important because PowerShell passes in the values by position. -- `$commandName` (Position 0) - This parameter is set to the name of the +- `$commandName` (Position 0, **String**) - This parameter is set to the name of the command for which the script block is providing tab completion. -- `$parameterName` (Position 1) - This parameter is set to the parameter +- `$parameterName` (Position 1, **String**) - This parameter is set to the parameter whose value requires tab completion. -- `$wordToComplete` (Position 2) - This parameter is set to value the user has provided before they - pressed Tab. Your script block should use this value to determine tab completion - values. -- `$commandAst` (Position 3) - This parameter is set to the Abstract Syntax +- `$wordToComplete` (Position 2, **String**) - This parameter is set to value the user has provided + before they pressed Tab. Your script block should use this value to determine tab + completion values. +- `$commandAst` (Position 3, **CommandAst**) - This parameter is set to the Abstract Syntax Tree (AST) for the current input line. For more information, see - [Ast Class](/dotnet/api/system.management.automation.language.ast). -- `$fakeBoundParameters` (Position 4) - This parameter is set to a hashtable containing the - `$PSBoundParameters` for the cmdlet, before the user pressed Tab. For more information, - see [about_Automatic_Variables](./About/about_Automatic_Variables.md). + [CommandAst Class](/dotnet/api/system.management.automation.language.commandast). +- `$fakeBoundParameters` (Position 4 **IDictionary**) - This parameter is set to a hashtable + containing the `$PSBoundParameters` for the cmdlet, before the user pressed Tab. For + more information, see [about_Automatic_Variables](./About/about_Automatic_Variables.md). When you specify the **Native** parameter, the script block must take the following parameters in the specified order. The names of the parameters aren't important because PowerShell passes in the values by position. -- `$wordToComplete` (Position 0) - This parameter is set to value the user has provided before they - pressed Tab. Your script block should use this value to determine tab completion - values. -- `$commandAst` (Position 1) - This parameter is set to the Abstract Syntax - Tree (AST) for the current input line. For more information, see - [Ast Class](/dotnet/api/system.management.automation.language.ast). -- `$cursorPosition` (Position 2) - This parameter is set to the position of the cursor when the user - pressed Tab. +- `$wordToComplete` (Position 0, **String**) - This parameter is set to value the user has provided + before they pressed Tab. Your script block should use this value to determine tab + completion values. +- `$commandAst` (Position 1, **CommandAst**) - This parameter is set to the Abstract Syntax Tree + (AST) for the current input line. For more information, see + [CommandAst Class](/dotnet/api/system.management.automation.language.commandast). +- `$cursorPosition` (Position 2, **Int32**) - This parameter is set to the position of the cursor + when the user pressed Tab. You can also provide an **ArgumentCompleter** as a parameter attribute. For more information, see [about_Functions_Advanced_Parameters](./About/about_Functions_Advanced_Parameters.md). @@ -250,7 +306,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](./About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](./About/about_CommonParameters.md). ## INPUTS @@ -267,3 +324,5 @@ This cmdlet returns no output. ## NOTES ## RELATED LINKS + +[about_Functions_Argument_Completion](./About/about_Functions_Argument_Completion.md) diff --git a/reference/7.2/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md b/reference/7.2/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md index d800c97323b7..b9d543ceeb83 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md +++ b/reference/7.2/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 12/09/2022 +ms.date: 07/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/register-argumentcompleter?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Register-ArgumentCompleter @@ -36,6 +36,12 @@ The `Register-ArgumentCompleter` cmdlet registers a custom argument completer. A completer allows you to provide dynamic tab completion, at run time for any command that you specify. +When you call this command with the **CommandName** parameter and without the **ParameterName** or +**Native** parameters, the command runs as if you specified the **Native** parameter. This prevents +the argument completer from working for PowerShell command parameters. Always specify the +**ParameterName** parameter when you want to register an argument completer for PowerShell +commands. + ## EXAMPLES ### Example 1: Register a custom argument completer @@ -44,28 +50,35 @@ The following example registers an argument completer for the **Id** parameter o cmdlet. ```powershell -$scriptBlock = { - param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters) +$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 $scriptBlock + +Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $s ``` -The first command creates a script block which takes the required parameters which are passed in +The first command creates a script block that takes the required parameters, which are passed in when the user presses Tab. For more information, see the **ScriptBlock** parameter description. Within the script block, the available values for **Id** are retrieved using the `Get-TimeZone` cmdlet. The **Id** property for each Time Zone is piped to the `Where-Object` cmdlet. The -`Where-Object` cmdlet filters out any ids that do not start with the value provided by +`Where-Object` cmdlet filters out any ids that don't start with the value provided by `$wordToComplete`, which represents the text the user typed before they pressed Tab. The -filtered ids are piped to the `ForEach-Object` cmdlet which encloses each value in quotes, should -the value contain spaces. +filtered ids are piped to the `ForEach-Object` cmdlet, which encloses each value in quotes to handle +values that contain spaces. The second command registers the argument completer by passing the scriptblock, the **ParameterName** **Id** and the **CommandName** `Set-TimeZone`. @@ -77,41 +90,54 @@ cmdlet and only returns running services. ```powershell $s = { - param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters) - $services = Get-Service | Where-Object {$_.Status -eq "Running" -and $_.Name -like "$wordToComplete*"} + 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 + 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 ``` -The first command creates a script block which takes the required parameters which are passed in +The first command creates a script block that takes the required parameters, which are passed in when the user presses Tab. For more information, see the **ScriptBlock** parameter description. Within the script block, the first command retrieves all running services using the `Where-Object` cmdlet. The services are piped to the `ForEach-Object` cmdlet. The `ForEach-Object` cmdlet creates a new -[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) object -and populates it with the name of the current service (represented by the pipeline variable `$_.Name`). +[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) +object and populates it with the name of the current service (represented by the pipeline variable +`$_.Name`). The **CompletionResult** object allows you to provide additional details to each returned value: - **completionText** (String) - The text to be used as the auto completion result. This is the value sent to the command. - **listItemText** (String) - The text to be displayed in a list, such as when the user presses - Ctrl+Space. This is used for display only and is not passed to the command - when selected. -- **resultType** ([CompletionResultType](/dotnet/api/system.management.automation.completionresulttype)) - The type of completion result. -- **toolTip** (String) - The text for the tooltip with details to be displayed about the object. - This is visible when the user selects an item after pressing Ctrl+Space. - -The last command demonstrates that stopped services can still be passed in manually to the -`Stop-Service` cmdlet. The tab completion is the only aspect affected. + Ctrl+Space. PowerShell uses this for display only. It isn't passed to the + command when selected. +- **resultType** + ([CompletionResultType](/dotnet/api/system.management.automation.completionresulttype)) - The + type of completion result. +- **toolTip** (String) - The text for the tooltip with details to display about the object. This is + visible when the user selects an item after pressing Ctrl+Space. ### Example 3: Register a custom Native argument completer @@ -123,28 +149,47 @@ example adds tab-completion for the `dotnet` Command Line Interface (CLI). ```powershell $scriptblock = { - param($wordToComplete, $commandAst, $cursorPosition) - dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object { - [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) - } + 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 ``` -The first command creates a script block which takes the required parameters which are passed in +The first command creates a script block that takes the required parameters, which are passed in when the user presses Tab. For more information, see the **ScriptBlock** parameter description. -Within the script block, the `dotnet complete` command is used to perform the tab completion. -The results are piped to the `ForEach-Object` cmdlet which use the **new** static method of the -[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) class -to create a new **CompletionResult** object for each value. +Within the script block, the `dotnet complete` command performs the tab completion. The results are +piped to the `ForEach-Object` cmdlet, which uses the **new** static method of the +[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) +class to create a **CompletionResult** object for each value. ## PARAMETERS ### -CommandName -Specifies the name of the commands as an array. +Specifies the name of one or more commands to register the argument completer for. This parameter +is mandatory for native commands. + +When you specify this parameter without the **ParameterName** or **Native** parameters, the command +behaves as if you had specified the **Native** parameter. When registering argument completers for +PowerShell commands, always specify the **ParameterName** parameter. + +If you don't specify this parameter, PowerShell registers the argument completer for the specified +**ParameterName** across all PowerShell commands. ```yaml Type: System.String[] @@ -160,7 +205,7 @@ Accept wildcard characters: False ### -Native -Indicates that the argument completer is for a native command where PowerShell cannot complete +Indicates that the argument completer is for a native command where PowerShell can't complete parameter names. ```yaml @@ -177,11 +222,16 @@ Accept wildcard characters: False ### -ParameterName -Specifies the name of the parameter whose argument is being completed. The parameter name specified -cannot be an enumerated value, such as the **ForegroundColor** parameter of the `Write-Host` cmdlet. +Specifies the name of the parameter the argument completer applies to. The type for specified +parameters can't be an enumeration, such as the **ForegroundColor** parameter of the `Write-Host` +cmdlet. For more information on enums, see [about_Enum](./About/about_Enum.md). +When registering an argument completer for PowerShell commands, always specify this parameter. When +you specify the **CommandName** parameter without the **ParameterName** or **Native** parameters, +the command behaves as if you specified the **Native** parameter. + ```yaml Type: System.String Parameter Sets: PowerShellSet @@ -201,35 +251,41 @@ the values that complete the input. The script block must unroll the values usin (`ForEach-Object`, `Where-Object`, etc.), or another suitable method. Returning an array of values causes PowerShell to treat the entire array as **one** tab completion value. +The script block can also return +[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) +objects for each value to enhance the user experience. Returning **CompletionResult** objects +enables you to define tooltips and custom list entries displayed when users press +Ctrl+Space to show the list of available completions. + The script block must accept the following parameters in the order specified below. The names of the parameters aren't important because PowerShell passes in the values by position. -- `$commandName` (Position 0) - This parameter is set to the name of the +- `$commandName` (Position 0, **String**) - This parameter is set to the name of the command for which the script block is providing tab completion. -- `$parameterName` (Position 1) - This parameter is set to the parameter +- `$parameterName` (Position 1, **String**) - This parameter is set to the parameter whose value requires tab completion. -- `$wordToComplete` (Position 2) - This parameter is set to value the user has provided before they - pressed Tab. Your script block should use this value to determine tab completion - values. -- `$commandAst` (Position 3) - This parameter is set to the Abstract Syntax +- `$wordToComplete` (Position 2, **String**) - This parameter is set to value the user has provided + before they pressed Tab. Your script block should use this value to determine tab + completion values. +- `$commandAst` (Position 3, **CommandAst**) - This parameter is set to the Abstract Syntax Tree (AST) for the current input line. For more information, see - [Ast Class](/dotnet/api/system.management.automation.language.ast). -- `$fakeBoundParameters` (Position 4) - This parameter is set to a hashtable containing the - `$PSBoundParameters` for the cmdlet, before the user pressed Tab. For more information, - see [about_Automatic_Variables](./About/about_Automatic_Variables.md). + [CommandAst Class](/dotnet/api/system.management.automation.language.commandast). +- `$fakeBoundParameters` (Position 4 **IDictionary**) - This parameter is set to a hashtable + containing the `$PSBoundParameters` for the cmdlet, before the user pressed Tab. For + more information, see [about_Automatic_Variables](./About/about_Automatic_Variables.md). When you specify the **Native** parameter, the script block must take the following parameters in the specified order. The names of the parameters aren't important because PowerShell passes in the values by position. -- `$wordToComplete` (Position 0) - This parameter is set to value the user has provided before they - pressed Tab. Your script block should use this value to determine tab completion - values. -- `$commandAst` (Position 1) - This parameter is set to the Abstract Syntax - Tree (AST) for the current input line. For more information, see - [Ast Class](/dotnet/api/system.management.automation.language.ast). -- `$cursorPosition` (Position 2) - This parameter is set to the position of the cursor when the user - pressed Tab. +- `$wordToComplete` (Position 0, **String**) - This parameter is set to value the user has provided + before they pressed Tab. Your script block should use this value to determine tab + completion values. +- `$commandAst` (Position 1, **CommandAst**) - This parameter is set to the Abstract Syntax Tree + (AST) for the current input line. For more information, see + [CommandAst Class](/dotnet/api/system.management.automation.language.commandast). +- `$cursorPosition` (Position 2, **Int32**) - This parameter is set to the position of the cursor + when the user pressed Tab. You can also provide an **ArgumentCompleter** as a parameter attribute. For more information, see [about_Functions_Advanced_Parameters](./About/about_Functions_Advanced_Parameters.md). @@ -250,7 +306,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](./About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](./About/about_CommonParameters.md). ## INPUTS @@ -267,3 +324,5 @@ This cmdlet returns no output. ## NOTES ## RELATED LINKS + +[about_Functions_Argument_Completion](./About/about_Functions_Argument_Completion.md) diff --git a/reference/7.4/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md b/reference/7.4/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md index d0597195746b..47b3873d96ea 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md +++ b/reference/7.4/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 12/09/2022 +ms.date: 07/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/register-argumentcompleter?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: Register-ArgumentCompleter @@ -36,6 +36,12 @@ The `Register-ArgumentCompleter` cmdlet registers a custom argument completer. A completer allows you to provide dynamic tab completion, at run time for any command that you specify. +When you call this command with the **CommandName** parameter and without the **ParameterName** or +**Native** parameters, the command runs as if you specified the **Native** parameter. This prevents +the argument completer from working for PowerShell command parameters. Always specify the +**ParameterName** parameter when you want to register an argument completer for PowerShell +commands. + ## EXAMPLES ### Example 1: Register a custom argument completer @@ -44,28 +50,35 @@ The following example registers an argument completer for the **Id** parameter o cmdlet. ```powershell -$scriptBlock = { - param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters) +$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 $scriptBlock + +Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $s ``` -The first command creates a script block which takes the required parameters which are passed in +The first command creates a script block that takes the required parameters, which are passed in when the user presses Tab. For more information, see the **ScriptBlock** parameter description. Within the script block, the available values for **Id** are retrieved using the `Get-TimeZone` cmdlet. The **Id** property for each Time Zone is piped to the `Where-Object` cmdlet. The -`Where-Object` cmdlet filters out any ids that do not start with the value provided by +`Where-Object` cmdlet filters out any ids that don't start with the value provided by `$wordToComplete`, which represents the text the user typed before they pressed Tab. The -filtered ids are piped to the `ForEach-Object` cmdlet which encloses each value in quotes, should -the value contain spaces. +filtered ids are piped to the `ForEach-Object` cmdlet, which encloses each value in quotes to handle +values that contain spaces. The second command registers the argument completer by passing the scriptblock, the **ParameterName** **Id** and the **CommandName** `Set-TimeZone`. @@ -77,41 +90,54 @@ cmdlet and only returns running services. ```powershell $s = { - param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters) - $services = Get-Service | Where-Object {$_.Status -eq "Running" -and $_.Name -like "$wordToComplete*"} + 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 + 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 ``` -The first command creates a script block which takes the required parameters which are passed in +The first command creates a script block that takes the required parameters, which are passed in when the user presses Tab. For more information, see the **ScriptBlock** parameter description. Within the script block, the first command retrieves all running services using the `Where-Object` cmdlet. The services are piped to the `ForEach-Object` cmdlet. The `ForEach-Object` cmdlet creates a new -[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) object -and populates it with the name of the current service (represented by the pipeline variable `$_.Name`). +[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) +object and populates it with the name of the current service (represented by the pipeline variable +`$_.Name`). The **CompletionResult** object allows you to provide additional details to each returned value: - **completionText** (String) - The text to be used as the auto completion result. This is the value sent to the command. - **listItemText** (String) - The text to be displayed in a list, such as when the user presses - Ctrl+Space. This is used for display only and is not passed to the command - when selected. -- **resultType** ([CompletionResultType](/dotnet/api/system.management.automation.completionresulttype)) - The type of completion result. -- **toolTip** (String) - The text for the tooltip with details to be displayed about the object. - This is visible when the user selects an item after pressing Ctrl+Space. - -The last command demonstrates that stopped services can still be passed in manually to the -`Stop-Service` cmdlet. The tab completion is the only aspect affected. + Ctrl+Space. PowerShell uses this for display only. It isn't passed to the + command when selected. +- **resultType** + ([CompletionResultType](/dotnet/api/system.management.automation.completionresulttype)) - The + type of completion result. +- **toolTip** (String) - The text for the tooltip with details to display about the object. This is + visible when the user selects an item after pressing Ctrl+Space. ### Example 3: Register a custom Native argument completer @@ -123,28 +149,47 @@ example adds tab-completion for the `dotnet` Command Line Interface (CLI). ```powershell $scriptblock = { - param($wordToComplete, $commandAst, $cursorPosition) - dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object { - [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) - } + 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 ``` -The first command creates a script block which takes the required parameters which are passed in +The first command creates a script block that takes the required parameters, which are passed in when the user presses Tab. For more information, see the **ScriptBlock** parameter description. -Within the script block, the `dotnet complete` command is used to perform the tab completion. -The results are piped to the `ForEach-Object` cmdlet which use the **new** static method of the -[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) class -to create a new **CompletionResult** object for each value. +Within the script block, the `dotnet complete` command performs the tab completion. The results are +piped to the `ForEach-Object` cmdlet, which uses the **new** static method of the +[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) +class to create a **CompletionResult** object for each value. ## PARAMETERS ### -CommandName -Specifies the name of the commands as an array. +Specifies the name of one or more commands to register the argument completer for. This parameter +is mandatory for native commands. + +When you specify this parameter without the **ParameterName** or **Native** parameters, the command +behaves as if you had specified the **Native** parameter. When registering argument completers for +PowerShell commands, always specify the **ParameterName** parameter. + +If you don't specify this parameter, PowerShell registers the argument completer for the specified +**ParameterName** across all PowerShell commands. ```yaml Type: System.String[] @@ -160,7 +205,7 @@ Accept wildcard characters: False ### -Native -Indicates that the argument completer is for a native command where PowerShell cannot complete +Indicates that the argument completer is for a native command where PowerShell can't complete parameter names. ```yaml @@ -177,11 +222,16 @@ Accept wildcard characters: False ### -ParameterName -Specifies the name of the parameter whose argument is being completed. The parameter name specified -cannot be an enumerated value, such as the **ForegroundColor** parameter of the `Write-Host` cmdlet. +Specifies the name of the parameter the argument completer applies to. The type for specified +parameters can't be an enumeration, such as the **ForegroundColor** parameter of the `Write-Host` +cmdlet. For more information on enums, see [about_Enum](./About/about_Enum.md). +When registering an argument completer for PowerShell commands, always specify this parameter. When +you specify the **CommandName** parameter without the **ParameterName** or **Native** parameters, +the command behaves as if you specified the **Native** parameter. + ```yaml Type: System.String Parameter Sets: PowerShellSet @@ -201,35 +251,41 @@ the values that complete the input. The script block must unroll the values usin (`ForEach-Object`, `Where-Object`, etc.), or another suitable method. Returning an array of values causes PowerShell to treat the entire array as **one** tab completion value. +The script block can also return +[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) +objects for each value to enhance the user experience. Returning **CompletionResult** objects +enables you to define tooltips and custom list entries displayed when users press +Ctrl+Space to show the list of available completions. + The script block must accept the following parameters in the order specified below. The names of the parameters aren't important because PowerShell passes in the values by position. -- `$commandName` (Position 0) - This parameter is set to the name of the +- `$commandName` (Position 0, **String**) - This parameter is set to the name of the command for which the script block is providing tab completion. -- `$parameterName` (Position 1) - This parameter is set to the parameter +- `$parameterName` (Position 1, **String**) - This parameter is set to the parameter whose value requires tab completion. -- `$wordToComplete` (Position 2) - This parameter is set to value the user has provided before they - pressed Tab. Your script block should use this value to determine tab completion - values. -- `$commandAst` (Position 3) - This parameter is set to the Abstract Syntax +- `$wordToComplete` (Position 2, **String**) - This parameter is set to value the user has provided + before they pressed Tab. Your script block should use this value to determine tab + completion values. +- `$commandAst` (Position 3, **CommandAst**) - This parameter is set to the Abstract Syntax Tree (AST) for the current input line. For more information, see - [Ast Class](/dotnet/api/system.management.automation.language.ast). -- `$fakeBoundParameters` (Position 4) - This parameter is set to a hashtable containing the - `$PSBoundParameters` for the cmdlet, before the user pressed Tab. For more information, - see [about_Automatic_Variables](./About/about_Automatic_Variables.md). + [CommandAst Class](/dotnet/api/system.management.automation.language.commandast). +- `$fakeBoundParameters` (Position 4 **IDictionary**) - This parameter is set to a hashtable + containing the `$PSBoundParameters` for the cmdlet, before the user pressed Tab. For + more information, see [about_Automatic_Variables](./About/about_Automatic_Variables.md). When you specify the **Native** parameter, the script block must take the following parameters in the specified order. The names of the parameters aren't important because PowerShell passes in the values by position. -- `$wordToComplete` (Position 0) - This parameter is set to value the user has provided before they - pressed Tab. Your script block should use this value to determine tab completion - values. -- `$commandAst` (Position 1) - This parameter is set to the Abstract Syntax - Tree (AST) for the current input line. For more information, see - [Ast Class](/dotnet/api/system.management.automation.language.ast). -- `$cursorPosition` (Position 2) - This parameter is set to the position of the cursor when the user - pressed Tab. +- `$wordToComplete` (Position 0, **String**) - This parameter is set to value the user has provided + before they pressed Tab. Your script block should use this value to determine tab + completion values. +- `$commandAst` (Position 1, **CommandAst**) - This parameter is set to the Abstract Syntax Tree + (AST) for the current input line. For more information, see + [CommandAst Class](/dotnet/api/system.management.automation.language.commandast). +- `$cursorPosition` (Position 2, **Int32**) - This parameter is set to the position of the cursor + when the user pressed Tab. You can also provide an **ArgumentCompleter** as a parameter attribute. For more information, see [about_Functions_Advanced_Parameters](./About/about_Functions_Advanced_Parameters.md). @@ -250,7 +306,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](./About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](./About/about_CommonParameters.md). ## INPUTS @@ -267,3 +324,5 @@ This cmdlet returns no output. ## NOTES ## RELATED LINKS + +[about_Functions_Argument_Completion](./About/about_Functions_Argument_Completion.md) diff --git a/reference/7.5/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md b/reference/7.5/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md index 57b0db5dc80a..6112c7469bce 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 12/09/2022 +ms.date: 07/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/register-argumentcompleter?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: Register-ArgumentCompleter @@ -36,6 +36,12 @@ The `Register-ArgumentCompleter` cmdlet registers a custom argument completer. A completer allows you to provide dynamic tab completion, at run time for any command that you specify. +When you call this command with the **CommandName** parameter and without the **ParameterName** or +**Native** parameters, the command runs as if you specified the **Native** parameter. This prevents +the argument completer from working for PowerShell command parameters. Always specify the +**ParameterName** parameter when you want to register an argument completer for PowerShell +commands. + ## EXAMPLES ### Example 1: Register a custom argument completer @@ -44,28 +50,35 @@ The following example registers an argument completer for the **Id** parameter o cmdlet. ```powershell -$scriptBlock = { - param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters) +$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 $scriptBlock + +Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $s ``` -The first command creates a script block which takes the required parameters which are passed in +The first command creates a script block that takes the required parameters, which are passed in when the user presses Tab. For more information, see the **ScriptBlock** parameter description. Within the script block, the available values for **Id** are retrieved using the `Get-TimeZone` cmdlet. The **Id** property for each Time Zone is piped to the `Where-Object` cmdlet. The -`Where-Object` cmdlet filters out any ids that do not start with the value provided by +`Where-Object` cmdlet filters out any ids that don't start with the value provided by `$wordToComplete`, which represents the text the user typed before they pressed Tab. The -filtered ids are piped to the `ForEach-Object` cmdlet which encloses each value in quotes, should -the value contain spaces. +filtered ids are piped to the `ForEach-Object` cmdlet, which encloses each value in quotes to handle +values that contain spaces. The second command registers the argument completer by passing the scriptblock, the **ParameterName** **Id** and the **CommandName** `Set-TimeZone`. @@ -77,41 +90,54 @@ cmdlet and only returns running services. ```powershell $s = { - param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters) - $services = Get-Service | Where-Object {$_.Status -eq "Running" -and $_.Name -like "$wordToComplete*"} + 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 + 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 ``` -The first command creates a script block which takes the required parameters which are passed in +The first command creates a script block that takes the required parameters, which are passed in when the user presses Tab. For more information, see the **ScriptBlock** parameter description. Within the script block, the first command retrieves all running services using the `Where-Object` cmdlet. The services are piped to the `ForEach-Object` cmdlet. The `ForEach-Object` cmdlet creates a new -[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) object -and populates it with the name of the current service (represented by the pipeline variable `$_.Name`). +[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) +object and populates it with the name of the current service (represented by the pipeline variable +`$_.Name`). The **CompletionResult** object allows you to provide additional details to each returned value: - **completionText** (String) - The text to be used as the auto completion result. This is the value sent to the command. - **listItemText** (String) - The text to be displayed in a list, such as when the user presses - Ctrl+Space. This is used for display only and is not passed to the command - when selected. -- **resultType** ([CompletionResultType](/dotnet/api/system.management.automation.completionresulttype)) - The type of completion result. -- **toolTip** (String) - The text for the tooltip with details to be displayed about the object. - This is visible when the user selects an item after pressing Ctrl+Space. - -The last command demonstrates that stopped services can still be passed in manually to the -`Stop-Service` cmdlet. The tab completion is the only aspect affected. + Ctrl+Space. PowerShell uses this for display only. It isn't passed to the + command when selected. +- **resultType** + ([CompletionResultType](/dotnet/api/system.management.automation.completionresulttype)) - The + type of completion result. +- **toolTip** (String) - The text for the tooltip with details to display about the object. This is + visible when the user selects an item after pressing Ctrl+Space. ### Example 3: Register a custom Native argument completer @@ -123,28 +149,47 @@ example adds tab-completion for the `dotnet` Command Line Interface (CLI). ```powershell $scriptblock = { - param($wordToComplete, $commandAst, $cursorPosition) - dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object { - [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) - } + 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 ``` -The first command creates a script block which takes the required parameters which are passed in +The first command creates a script block that takes the required parameters, which are passed in when the user presses Tab. For more information, see the **ScriptBlock** parameter description. -Within the script block, the `dotnet complete` command is used to perform the tab completion. -The results are piped to the `ForEach-Object` cmdlet which use the **new** static method of the -[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) class -to create a new **CompletionResult** object for each value. +Within the script block, the `dotnet complete` command performs the tab completion. The results are +piped to the `ForEach-Object` cmdlet, which uses the **new** static method of the +[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) +class to create a **CompletionResult** object for each value. ## PARAMETERS ### -CommandName -Specifies the name of the commands as an array. +Specifies the name of one or more commands to register the argument completer for. This parameter +is mandatory for native commands. + +When you specify this parameter without the **ParameterName** or **Native** parameters, the command +behaves as if you had specified the **Native** parameter. When registering argument completers for +PowerShell commands, always specify the **ParameterName** parameter. + +If you don't specify this parameter, PowerShell registers the argument completer for the specified +**ParameterName** across all PowerShell commands. ```yaml Type: System.String[] @@ -160,7 +205,7 @@ Accept wildcard characters: False ### -Native -Indicates that the argument completer is for a native command where PowerShell cannot complete +Indicates that the argument completer is for a native command where PowerShell can't complete parameter names. ```yaml @@ -177,11 +222,16 @@ Accept wildcard characters: False ### -ParameterName -Specifies the name of the parameter whose argument is being completed. The parameter name specified -cannot be an enumerated value, such as the **ForegroundColor** parameter of the `Write-Host` cmdlet. +Specifies the name of the parameter the argument completer applies to. The type for specified +parameters can't be an enumeration, such as the **ForegroundColor** parameter of the `Write-Host` +cmdlet. For more information on enums, see [about_Enum](./About/about_Enum.md). +When registering an argument completer for PowerShell commands, always specify this parameter. When +you specify the **CommandName** parameter without the **ParameterName** or **Native** parameters, +the command behaves as if you specified the **Native** parameter. + ```yaml Type: System.String Parameter Sets: PowerShellSet @@ -201,35 +251,41 @@ the values that complete the input. The script block must unroll the values usin (`ForEach-Object`, `Where-Object`, etc.), or another suitable method. Returning an array of values causes PowerShell to treat the entire array as **one** tab completion value. +The script block can also return +[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) +objects for each value to enhance the user experience. Returning **CompletionResult** objects +enables you to define tooltips and custom list entries displayed when users press +Ctrl+Space to show the list of available completions. + The script block must accept the following parameters in the order specified below. The names of the parameters aren't important because PowerShell passes in the values by position. -- `$commandName` (Position 0) - This parameter is set to the name of the +- `$commandName` (Position 0, **String**) - This parameter is set to the name of the command for which the script block is providing tab completion. -- `$parameterName` (Position 1) - This parameter is set to the parameter +- `$parameterName` (Position 1, **String**) - This parameter is set to the parameter whose value requires tab completion. -- `$wordToComplete` (Position 2) - This parameter is set to value the user has provided before they - pressed Tab. Your script block should use this value to determine tab completion - values. -- `$commandAst` (Position 3) - This parameter is set to the Abstract Syntax +- `$wordToComplete` (Position 2, **String**) - This parameter is set to value the user has provided + before they pressed Tab. Your script block should use this value to determine tab + completion values. +- `$commandAst` (Position 3, **CommandAst**) - This parameter is set to the Abstract Syntax Tree (AST) for the current input line. For more information, see - [Ast Class](/dotnet/api/system.management.automation.language.ast). -- `$fakeBoundParameters` (Position 4) - This parameter is set to a hashtable containing the - `$PSBoundParameters` for the cmdlet, before the user pressed Tab. For more information, - see [about_Automatic_Variables](./About/about_Automatic_Variables.md). + [CommandAst Class](/dotnet/api/system.management.automation.language.commandast). +- `$fakeBoundParameters` (Position 4 **IDictionary**) - This parameter is set to a hashtable + containing the `$PSBoundParameters` for the cmdlet, before the user pressed Tab. For + more information, see [about_Automatic_Variables](./About/about_Automatic_Variables.md). When you specify the **Native** parameter, the script block must take the following parameters in the specified order. The names of the parameters aren't important because PowerShell passes in the values by position. -- `$wordToComplete` (Position 0) - This parameter is set to value the user has provided before they - pressed Tab. Your script block should use this value to determine tab completion - values. -- `$commandAst` (Position 1) - This parameter is set to the Abstract Syntax - Tree (AST) for the current input line. For more information, see - [Ast Class](/dotnet/api/system.management.automation.language.ast). -- `$cursorPosition` (Position 2) - This parameter is set to the position of the cursor when the user - pressed Tab. +- `$wordToComplete` (Position 0, **String**) - This parameter is set to value the user has provided + before they pressed Tab. Your script block should use this value to determine tab + completion values. +- `$commandAst` (Position 1, **CommandAst**) - This parameter is set to the Abstract Syntax Tree + (AST) for the current input line. For more information, see + [CommandAst Class](/dotnet/api/system.management.automation.language.commandast). +- `$cursorPosition` (Position 2, **Int32**) - This parameter is set to the position of the cursor + when the user pressed Tab. You can also provide an **ArgumentCompleter** as a parameter attribute. For more information, see [about_Functions_Advanced_Parameters](./About/about_Functions_Advanced_Parameters.md). @@ -250,7 +306,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](./About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](./About/about_CommonParameters.md). ## INPUTS @@ -267,3 +324,5 @@ This cmdlet returns no output. ## NOTES ## RELATED LINKS + +[about_Functions_Argument_Completion](./About/about_Functions_Argument_Completion.md)