The new Azure PowerShell Az module

• Author
• Recent Posts

Timothy Warner

Timothy Warner is a Microsoft Cloud and Datacenter Management Most Valuable Professional (MVP) who is based in Nashville, TN. Check out his Azure and Windows Server video training at Pluralsight, and feel free to reach out to Tim via Twitter.

Latest posts by Timothy Warner (see all)

• Azure PowerShell vs. Azure CLI - Wed, Mar 15 2023
• Use Azure Storage for backup - Thu, Feb 23 2023
• Azure Data Studio vs. SQL Server Management (SSMS) - Wed, Feb 8 2023

Azure PowerShell has undergone quite a bit of change over the last handful of years. With the old Azure Service Management (ASM) application programming interfaces (APIs), we had a single, monolithic module named (appropriately enough) Azure.

Then Microsoft gave us the lovely Azure Resource Manager (ARM) APIs, and with them, their PowerShell developers published the AzureRM modules. A "bootstrapper" module named AzureRM orchestrated the delivery of a couple dozen decomposed, service-specific modules.

Well, today the "new normal" is cross-platform PowerShell thanks to .NET Core and PowerShell Core v6. To this end, in December 2018 Microsoft released the new Azure PowerShell Az module.

Why the change?

Microsoft wants PowerShell to be available on Windows, macOS, Linux, and even embedded platforms. As you know, .NET Standard supports applications that run on .NET Framework (Full) and .NET Core. The Az modules were written in .NET Standard, so you can install 'em on "full" .NET Framework boxes like Windows Server and Windows Client or .NET Core-equipped boxes like macOS and Linux.

So first and foremost, we have consistency in both the PowerShell language and the underlying .NET runtime. Second, we have command-naming consistency. You may have noticed that with the AzureRM modules, you still have the occasional Azure command (how annoying).

Specifically, Az runs on PowerShell v5.1 and PowerShell Core (v6x).

All the Az commands use simply 'Az' as their noun prefix, which should make typing and tab-completion easier to accomplish.

Understand also that Az is the only Azure PowerShell you will see in Azure Cloud Shell.

Finally, understand that Microsoft is no longer developing new cmdlets or features for the AzureRM modules, so like it or not, going forward you have no choice but to embrace the Az commands! Instead, Microsoft commits to providing bug fixes to the AzureRm commands through December 2020.

Upgrading to Az

While the AzureRM and Az modules can exist side by side on the same computer, Microsoft recommends uninstalling the AzureRM modules to avoid any possible conflicts. Moreover, you cannot run commands from both modules in the same PowerShell runspace.

You can uninstall AzureRM via the Apps & Features Settings panel in Windows 10 or by running the Uninstall-AzureRm Az command from an elevated console.

Note: You need to run Uninstall-AzureRm from PowerShell 5.x and 6.x consoles separately to ensure you remove every trace of AzureRM from your system. Also, keep in mind that Uninstall-AzureRm is an Az module, so you will have already had to install the Az modules.

Speaking of installing the Az modules, you can do so via PowershellGet and the PowerShell Gallery this way:

Find-Module -Name Az -Repository PSGallery | Install-Module -Verbose -Force

And yes, the Az module itself is a bootstrapper that orchestrates the download and installation of all the service-specific modules. Don't forget to run Update-Help to fetch the command documentation—you may need it!

Working with the Az commands

You should find that the Az modules and commands have feature parity with their AzureRM counterparts. However, and this is a big "however," they've renamed and consolidated some modules.

For instance, they now call the AzureRM.Profile module Az.Accounts. They've collapsed AzureRM.UsageAggregates and AzureRM.Consumption into Az.Billing. Check the docs for a full list of these name changes.

Open an administrative PowerShell Core console, and let's get authenticated to Azure. For this, we can use Connect-AzAccount or its aliases, Login-AzAccount or Add-AzAccount.

The Azure PowerShell interactive login process is now the same as with the Azure CLI v2.0; you need to open aka.ms/devicelogin, paste the one-time code, choose an account, and confirm you want to authenticate to get logged in. It's a bit annoying, but whatever.

Logging into Azure via the Az modules

If you have multiple subscriptions, you may need to set your context:

Set-AzContext -Subscription 'Microsoft Azure Sponsorship'

From there, it's all standard-issue PowerShell. Your learning curve will consist of mapping the old AzureRM commands to their Az counterparts. In most cases, this is easy:

• Get-AzureRmVM => Get-AzVm
• Get-AzureRmStorageAccount => Get-AzStorageAccount

However, not every command is a 1:1 translation like this. Let's address that issue next.

Refactoring your code

You likely have a fair amount of AzureRM code, and you worry about how much code rewriting you're looking at. What I suggest in the short term is that you rely upon the Enable-AzureRmAlias compatibility cmdlet. Look at the next figure to check out what's going on.

Enable AzureRmAlias creates aliases for all the AzureRM commands

So the idea is as long as you call Enable-AzureRmAlias first in your AzureRM automation scripts, they have a pretty good chance of running as-is on a system that has only the Az modules available.

You can also limit the aliasing to particular Az modules:

Enable-AzureRmAlias -Module Az.Compute

You can persist the aliasing across PowerShell sessions by scoping the command appropriately:

Enable-AzureRmAlias -Scope CurrentUser

Be careful about scoping the compatibility aliasing at the LocalMachine level if you share your system with other users who may require AzureRM modules in their local scope.

And, of course, at any time you can disable the command aliasing:

Disable-AzureRmAlias

Another code migration pattern to consider for Windows users is keeping the AzureRM modules installed in PowerShell Desktop and installing the Az modules in PowerShell Core. Then you can run your scripts in each environment as appropriate.

Wrap-up

The only constant in the Azure ecosystem is change. If you've worked with Azure for a while, you understand that the ground beneath you is almost always in flux. Yes, it is a pain to have to refactor your Azure PowerShell code when changes like this occur.

On the other hand, I would argue that it makes sense for you to stay close to your code in the first place. Shouldn't you be looking for opportunities to refactor and optimize your code anyway? Heh. Happy PowerShelling!