Skip Navigation

Completers in Azure PowerShell

Posted on February 4, 2019

Software Engineer, Microsoft Azure

Since version 3.0, PowerShell has supported applying argument completers to cmdlet parameters. These argument completers allow you to tab through a set of values that are valid for the parameter. However, unlike ValidateSet which enforces that only the provided values are passed to the cmdlet, argument completers do not restrict the values that can be passed to the string parameter. Additionally, argument completers can be either a static or a dynamic set of strings. Using this feature, we have added argument completers to the Azure PowerShell modules which allow you to select valid parameter values without needing to make additional calls to Azure. These completers make the required calls to Azure to obtain the valid parameter values.

To best capture the functionality of the completers, I have modified the key binding for “Tab” in the examples below to display all the possible values at once. If you want to replicate this setup, simply run: “Set-PSReadLineKeyHandler -Key Tab -Function Complete.”

Location completer

The first completer that we created was the Location completer. Since each resource type has a distinct list of available Azure regions, we wanted to create an easy, quick way to select a valid region when creating a resource. Thus, for every parameter in our modules which accepts an Azure region (which in most cases is called Location), we added an argument completer that returns only the regions in which the resource type can be created. In the example below, you can see the result of pressing tab immediately after -Location for the New-AzResourceGroup cmdlet.

The Location completer was the first completer created.

In addition to listing out all available regions that a Resource Group can be created in, the Location completer allows you to filter the results by a typing in the first few characters of the region you are looking for.

The Location completer also allows you to filter the results by typing in the first few characters of a region you are looking for.

Resource Group Name completer

The second completer that we added to the PowerShell modules is the Resource Group Name completer. This completer was applied to all parameters which accept an existing resource group and returns all resource groups in the current subscription. Similar to the Location completer, you can filter the results by typing the first few characters of the resource group before pressing tab.

Resource group name completer

Resource Name completer

The third completer that we added to the PowerShell modules is the Resource Name completer. This completer returns the list of names of all resources that match the resource type required by the parameter. Additionally, this argument completer will filter by the resource group name if it is already provided to the cmdlet invocation. For example, in the screenshot below, when we tab after typing “Get-AzVM -Name test,” we see all four VMs in the current subscription that starts with “test.” Then, when we tab after typing “Get-AzVM -ResourceGroupName maddie1 -Name test,” we only see the two VMs that are contained in the “maddie1” resource group.

Resource name completer

Not only does the Resource Name completer filter by the resource group name, but, for all subresources, it also filters by the parent resources, if they are provided to the cmdlet invocation. The results will be filtered by each of the parent resources provided. In the example below, you can see the results of tab completion over “maddiessqldatabase” for various combinations of parameters being provided.

The results of tab completion over “maddiessqldatabase” for various combinations of parameters being provided.

At the moment, this completer has only been applied to the Compute, Network, KeyVault, and SQL modules. If you enjoy this feature and would like to see it applied to more modules, please let us know by sending us feedback using the Send-Feedback cmdlet.

Resource Id completer

The final completer that we added to the Az modules is a Resource Id completer. This completer returns all resource Ids in the current subscription, filtered for the resource type that the parameter requires. The Resource Id completer allows you to filter the results by a typing in a few characters, using '*<characters>*' wildcard pattern. This completer was applied to all parameters in our cmdlets that accept an Azure resource Id.

Resource Id completer

Try it out

To try out Azure PowerShell for yourself, install our Az module via the PowerShell Gallery. For more information about our new Az module, please check out our Az announcement blog. We look forward to getting your feedback, suggestions or issues via the built-in “Send-Feedback” cmdlet. Alternatively, you can always open an issue in our GitHub repository.