Register-ArgumentCompleter

PowerShell Cmdlet Deep Dive: Register-ArgumentCompleter

Welcome back to Wahmans PowerShell Blog! Today we’re diving into a powerful yet often underutilized cmdlet: Register-ArgumentCompleter. This handy tool allows you to create custom auto-completions for your PowerShell commands — aka IntelliSense on steroids!

What is Register-ArgumentCompleter?

According to Microsoft Docs:

Register-ArgumentCompleter registers a custom argument completer.

It means you can define what options should be suggested when a user hits Tab while providing arguments to a command. And yes — that’s as cool and useful as it sounds!

Why Use Register-ArgumentCompleter?

• Simplifies command usage
• Reduces input errors
• Makes your scripts more user-friendly
• Can integrate dynamic data into completion (e.g., from APIs, databases)

Let’s Explore with Some Examples

Example 1 – Beginner Level: Static Completion for a Custom Function

Let’s say you have a function that accepts an argument called -Environment. You want to offer static options like Dev, Test, Prod when tab completing.

function Invoke-Deploy {
    param(
        [string]$Environment
    )
    "Deploying to $Environment"
}

Register-ArgumentCompleter -CommandName Invoke-Deploy -ParameterName Environment -ScriptBlock {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)

    'Dev','Test','Prod' | ForEach-Object {
        [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
    }
}

Usage: Try typing Invoke-Deploy -Environment and then press Tab.

Example 2 – Intermediate: Completing Files with Specific Extension

This time we want to suggest all .log files from a directory for a parameter.

function Invoke-LogViewer {
    param(
        [string]$LogFile
    )
    Get-Content $LogFile
}

Register-ArgumentCompleter -CommandName Invoke-LogViewer -ParameterName LogFile -ScriptBlock {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)

    Get-ChildItem -Path . -Filter "*.log" | ForEach-Object {
        [System.Management.Automation.CompletionResult]::new($_.Name, $_.Name, 'ParameterValue', $_.FullName)
    }
}

Example 3 – Advanced: Dynamic Values from a Web API

Need parameter values loaded dynamically from a remote server? Here’s how you could load values from a JSON endpoint:

function Invoke-ProcessCustomer {
    param(
        [string]$CustomerName
    )
    "Processing $CustomerName"
}

Register-ArgumentCompleter -CommandName Invoke-ProcessCustomer -ParameterName CustomerName -ScriptBlock {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)

    $customers = Invoke-RestMethod -Uri 'https://api.example.com/customers' -ErrorAction SilentlyContinue
    $customers.names | ForEach-Object {
        [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
    }
}

Note: Always include error handling when dealing with external sources.

Example 4 – Expert Level: Multi-Parameter Context-Aware Completion

Now we’ll build a completer that returns different options based on what’s already typed in other parameters. Imagine choosing available VM sizes depending on region.

function New-AzureVM {
    param(
        [string]$Region,
        [string]$VmSize
    )
    "Creating VM in $Region with size $VmSize"
}

Register-ArgumentCompleter -CommandName New-AzureVM -ParameterName VmSize -ScriptBlock {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)

    $region = $fakeBoundParameters['Region']
    if ($region -eq 'westeurope') {
        $sizes = 'Standard_B1s','Standard_B2s'
    } elseif ($region -eq 'eastus') {
        $sizes = 'Standard_DS1','Standard_DS2'
    } else {
        $sizes = 'Standard_A1'
    }

    $sizes | ForEach-Object {
        [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
    }
}

This adds beautiful interactivity and context for scripts with multiple interrelated parameters.

Wrap Up

Custom tab completions with Register-ArgumentCompleter can drastically improve tool usability, especially for scripts integrated into DevOps pipelines or shared across teams. They’re easy to implement and highly flexible.

Hope you enjoyed today’s post! Let me know how you’re using this cmdlet in your workflows.

Happy scripting, and I will see you in the next post!