Azure/PowerShell: Cmdlet Parameter and Result Complexity (Get-AzHost, Get-AzVM, New-AzVM)

Overview

The concept of cmdlet parameter sets was discussed in "PowerShell: Cmdlet Parameter Sets". The motivation for introducing this topic was to show the complexity of certain PowerShell cmdlets and in a future posts how to escape this complexity (foreshadow: Azure Resource Manager templates). An example of a further complexity is that a cmdlet can have different return values and can return single values or arrays. Azure cmdlets can take dozens of parameters and contain multiple parameter sets. Making cmdlets more complicated is that certain cmdlets uses parameters that are created by invoking several different cmdlets which extend the values associated with the parameter. For example the New-AzVM can create an Azure VM using a parameter of type PSVirtualMachine. The PSVirtualMachine parameters could have been setup by invoking multiple cmdlets (New-AzVMConfig, Set-AzVMOperatingSystem, Add-AzVMNetworkInterface, Set-AzVMOSDisk). Debugging an invalid parameter passed to a cmdlet such as New-AzVm can be a nightmare.

In order to better understand cmdlet parameter sets and there complexity consider the documentation of several Azure related cmdlets:

• Get-AzHost: retrieves a host or a list of all hosts if no host name is specified
• Get-AzVM: retrieves the properties of an Azure VM
• New-AzVM: creates an Azure VM

The documentation for each of these cmdlets is broken into sections where each shaded rectangle corresponds to a different parameter set. I am color blind so I have no idea if the shaded rectangles contain a color or are simply shades of gray. 

PowerShell cmdlets such as those referenced above return inconsistent types. For example, the Get-AzVM cmdlet can return either of the following types depending on the parameters specified:

PSVirtualMachine

PSVirtualMachineInstanceView

Even when a PowerShell cmdlet is documented to return a specific type or types this may not be the case. Cmdlets can return a single value or an array of values. 

Get-AzHost

The documentation for Get-AzHost shows two parameter sets each identified by shaded rectangles:

The output for each parameter set appears to be consistent as the return value is documented as follows:

Microsoft.Azure.Commands.Compute.Automation.Models.PSHost

If Get-AzHost returns one value the return type is PSHost. If Get-AzHost returns multiple types the return value is of type array.

The first parameter set contains the following unique parameters:

• ResourceGroupName
• HostGroupName

The second parameter set contains a unique parameter:

• ResourceId

The first parameter set contains a -Name parameter which when excludes retrieves a list of all hosts.

Get-AzVM

The documentation for the Get-AzVM cmdlet identifies four parameter sets as follows:

As mentioned above the Get-AzVM will return different types depending on the parameters specified to the cmdlet:

PSVirtualMachine

PSVirtualMachineInstanceView

The return values can be a single value or an array of values.

The first parameter set identifies all parameters as optional which means no parameter is an option and hence unique. When passed no parameters, Get-AzVM (the first parameter set) returns all virtual machines for a subscription. The second parameter set has positional parameters ResourceGroupName and Name or their named counterparts as required. DisplayHint is also a unique parameter for the second parameter set. The third parameter set has a unique parameter, Location. The fourth parameter set has a lone unique parameter, NextLink.

New-AzVM

The New-AzVM cmdlet defines the following multiple parameters sets and takes over a dozen potential parameters including complex types built up by invoking multiple setup cmdlets. 

The unique parameter for this New-AzVm parameter set is -Credential:

The unique parameter for this New-AzVM parameter set is -VM:

The data type passed to the -VM parameter is PSVirtualMachine. Setting up a PSVirtualMachine can involve invoking multiple cmdlets in order to assign additional settings to the PSVirtualMachine instance.

The unique parameter for this new-AzVM parameter set is -DiskFile:

New-AzVM and PSVirtualMachine Configuration

The following example from New-AzVM demonstrates the level of complexity that can be associated with setting up a cmdlet's parameters. The script marked in boldface shows how many PowerShell cmdlets have to be invoked simply (or not so simply) to set up the New-AzVM's -VM parameter value: