Announcing the AzureRM to Az PowerShell Module Migration Toolkit

As many of you know, all versions of the AzureRM PowerShell module are outdated, but not out of support (yet). The Az PowerShell module is now the recommended PowerShell module for interacting with Azure.

We asked our customers what was keeping them from migrating from AzureRM to the Az PowerShell module. Most of the responses mentioned the amount of work invested in scripts based on AzureRM that would need to be overhauled. Many of these are non-trivial scripts to create things like entire environments in Azure.

We listened and we’re happy to announce the Az.Tools.Migration PowerShell module. The Az.Tools.Migration PowerShell module can automatically upgrade your PowerShell scripts and script modules from AzureRM to the Az PowerShell module.

Preparing your environment.

First, you’ll need to update your existing PowerShell scripts to the latest version of the AzureRM PowerShell module (6.13.1) if you haven’t already.

Install the Az.Tools.Migration PowerShell module from the PowerShell Gallery using the following command.

Install-Module -Name Az.Tools.Migration

Generate an Upgrade Plan.

You use the New-AzUpgradeModulePlan cmdlet to generate an upgrade plan for migrating your scripts and modules to the Az PowerShell module. This cmdlet doesn’t make any changes to your existing scripts. Use the FilePath parameter for targeting a specific script or the DirectoryPath parameter for targeting all scripts in a specific folder.

The following example generates a plan for all the scripts in the C:\Scripts folder. The OutVariable parameter is specified so the results are returned and simultaneously stored in a variable named Plan.

New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion 4.6.1 -DirectoryPath 'C:\Scripts' -OutVariable Plan

Before performing the upgrade, you need to view the results of the plan for any problems. The following example returns a list of scripts and the items in those scripts that will prevent them from being upgraded automatically.

$Plan | Where-Object PlanResult -ne ReadyToUpgrade | Format-List

These items will not be upgraded automatically without manually correcting the issues first. Known issues that can’t be upgraded automatically include any commands that use splatting.

Perform the Upgrade.

Once you’re satisfied with the results, the upgrade is performed with the Invoke-AzUpgradeModulePlan cmdlet. This cmdlet also doesn’t make any changes to your scripts. It performs the upgrade by creating a copy of each script targeted with “_az_upgraded” appended to the file names.

The following example upgrades all of the scripts from the previously generated plan.

Invoke-AzUpgradeModulePlan -Plan $Plan -FileEditMode SaveChangesToNewFiles -OutVariable Results