I think we all can agree that TAB completion is very useful and time saving feature that a lot of native PowerShell functions offer. But did you know that you can make this useful feature available even for your own custom functions?

In this post, I will show you two ways to make this work 👍

PS: By TAB completion I mean pressing TAB key to get available parameter values

1. TAB completion defined globally for list of functions

The key here is to use Register-ArgumentCompleter PowerShell function.

Be noted that effect of using Register-ArgumentCompleter won't outlast console closure. To make it "permanent" place the code into your PowerShell profile script.

Register-ArgumentCompleter has three important parameters:

• 1.CommandName
  • List of functions/cmdlets this TAB completion will be applied to
• 2.ParameterName
  • CommandName parameter name this TAB completion will be applied to
• 3.ScriptBlock
  • Special crafted scriptBlock, whose output will be shown as TAB completion

Basic example

# some dumb function with at least one parameter (fullName in this example)
function Open-DesktopFile {
    param ($fullName)

    # open given file
    & $fullName
}

# scriptblock for Register-ArgumentCompleter
$openDesktopSb = {
    param ($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParams)

    $DesktopPath = [Environment]::GetFolderPath("Desktop")

    Get-ChildItem -Path $DesktopPath -File | Where-Object { $_.Name -like "*$WordToComplete*" } | Select-Object -ExpandProperty FullName | ForEach-Object { "'$_'" }
}

# activate `TAB` completion for 'Open-DesktopFile' functions parameter 'fullName'
# what pressing of `TAB` returns, is defined in openDesktopSb scriptblock
Register-ArgumentCompleter -CommandName Open-DesktopFile -ParameterName fullName -ScriptBlock $openDesktopSb

# now call Open-DesktopFile -fullName (and hit `TAB` key to fill it)

Silly example above shows basic scriptBlock for filling path to quoted files on your desktop.

As you can see, the Register-ArgumentCompleter scriptBlock operates with five automatically filled parameters: $commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParams (their names doesn't matter, just their position!)

• commandName
  • contains name of the function to which this completion will be applied to
• parameterName
  • contains name of the parameter to which TAB will be applied to
• wordToComplete
  • contains string user have entered (if any)
• commandAst
  • contains AST object of the current input line
• fakeBoundParams
  • contains hashtable containing the $PSBoundParameters for the commandName function, before the user pressed TAB

PS: scriptBlock will be run with each hit of TAB key! So make it as resource efficient as you can.

Example of leveraging fakeBoundParams parameter

• We all use Get-WmiObject and Get-CimInstance cmdlets, but wouldn't be nice to have TAB completion for Class name? Moreover for different Namespaces? 😉

$wmiClassSb = {
    param ($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParams)

    if ($fakeBoundParams.Namespace) {
        # use user entered namespace if available
        $Namespace = $FakeBoundParams.Namespace
    } else {
        # use default namespace
        $Namespace = "ROOT\cimv2"
    }

    Get-WmiObject -List -namespace $Namespace | ? {$_.Name -like "*$WordToComplete*"} | select -exp name
}

# make `TAB` completion work for Class parameter of Get-WmiObject, Get-CimInstance commands
Register-ArgumentCompleter -CommandName Get-WmiObject, Get-CimInstance -ParameterName Class -ScriptBlock $wmiClassSb

The result will look like this

2. TAB completion defined in function param() section

• As you already know, parameters defined in PowerShell param() block, can have various attributes like type, validation etc. One of this attributes is ArgumentCompleter and is used to define TAB completion
  • The usage is like this:

function Invoke-Greeting {
    param (
        [ArgumentCompleter( {
                param ($Command, $Parameter, $WordToComplete, $CommandAst, $FakeBoundParams)

                Get-LocalUser | Where-Object { $_.Name -like "*$WordToComplete*" }
            })]
        [string] $userName
    )

    "Say hi to $userName"
}

# to test this out, call Invoke-Greeting and just hit TAB to show local user names

• So for specific parameter ($userName in this case) you define [ArgumentCompleter({ <scriptBlock> })]
  • The <scriptBlock> has same format as for Register-ArgumentCompleter function, so check first section of this post for more details

And the result will look like this

Various examples just for inspiration

Search AD computer by its name or description

• very handy if you have a lot of servers, and you save their purpose to their description attribute!

  $computerSB = {
       param ($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter)
  
       $searcher = New-Object System.DirectoryServices.DirectorySearcher (([adsi]"LDAP://OU=Computer_Accounts,DC=contoso,DC=com"), '(objectCategory=computer)', ('name', 'description'))
       ($searcher.findall() | ? { $_.properties.name -match $wordToComplete -or $_.properties.description -match $wordToComplete }).properties.name | Sort-Object | % { "'$_'" }
       $searcher.Dispose()
   }
  
   # TAB completion of AD computer names in computerName parameter of any command from module Scripts, ..
   Register-ArgumentCompleter -CommandName ((Get-Command -Module Scripts).name) -ParameterName computerName -ScriptBlock $computerSB
   Register-ArgumentCompleter -CommandName Enter-PSSession, Invoke-Command -ParameterName computername -ScriptBlock $computerSB
   # TAB completion of AD computer names in identity parameter of commands with "computer" in their name from module ActiveDirectory
   Register-ArgumentCompleter -CommandName ((Get-Command -Module ActiveDirectory -Noun *computer*).name) -ParameterName identity -ScriptBlock $computerSB
  

  Similarly if you have functions related to server or clients, you can limit the completion like this

   $serverSB = {
       param ($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter)
  
       $searcher = New-Object System.DirectoryServices.DirectorySearcher (([adsi]"LDAP://OU=Servers,OU=Computer_Accounts,DC=contoso,DC=com"), '(objectCategory=computer)', ('name', 'description'))
       ($searcher.findall() | ? { $_.properties.name -match $wordToComplete -or $_.properties.description -match $wordToComplete }).properties.name | Sort-Object | % { "'$_'" }
       $searcher.Dispose()
   }
  
   Register-ArgumentCompleter -CommandName Invoke-MSTSC -ParameterName computerName -ScriptBlock $serverSB
  
   $clientSB = {
       param ($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter)
  
       $searcher = New-Object System.DirectoryServices.DirectorySearcher (([adsi]"LDAP://OU=Clients,OU=Computer_Accounts,DC=contoso,DC=com"), '(objectCategory=computer)', ('name', 'description'))
       ($searcher.findall() | ? { $_.properties.name -match $wordToComplete -or $_.properties.description -match $wordToComplete }).properties.name | Sort-Object | % { "'$_'" }
       $searcher.Dispose()
   }
  
   Register-ArgumentCompleter -CommandName Assign-Computer -ParameterName computerName -ScriptBlock $clientSB
  

Or what about replacing name for samaccountname in identity parameter of all functions from ActiveDirectory module (that contains 'User' in noun part)?

    $userSB = {
        param ($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter)

        $searcher = New-Object System.DirectoryServices.DirectorySearcher (([adsi]"LDAP://OU=User_Accounts,DC=contoso,DC=com"), '(objectCategory=user)', ('name', 'samaccountname'))
        ($searcher.findall() | ? { $_.properties.name -match $wordToComplete }).properties.samaccountname | Sort-Object | % { "'$_'" }
        $searcher.Dispose()
    }

    Register-ArgumentCompleter -CommandName ((Get-Command -Module ActiveDirectory -Noun *user*).name) -ParameterName identity -ScriptBlock $userSB

Summary

As you can see, you have two options to define TAB completion. Inside the function param() block using [ArgumentCompleter()] or globally using Register-ArgumentCompleter. In general I use the latter option in my PowerShell profile script mainly for built-in functions and the first one, for my own custom functions. In either way, its very handy, time saving and cool feature! 😉

Do you have any other cool examples of TAB completion?