How to migrate Azure PowerShell from AzureRM to the new Az Module

3 days ago, Microsoft released version 1.0.0 of the new Az Module. Az is a cross-platform PowerShell module to manage resources in Azure that is compatible with both WindowsPowerShell and PowerShell Core.

Why to migrate to Az?

Az is written from ground up in .NET Standard which allows us to use the module in PowerShell Core on Windows, MacOs or Linux platforms. It is the “new” module, all further functionality will be added to the Az module whereas AzureRM will only receive bug fixes.

How to migrate?

Scripts that use the previous AzureRM module won’t automatically work with Az. You can enable a compatibility mode to the AzureRM module using the Enable-AzureRmAlias cmdlet. This allows you to soft migrate existing scripts. Be sure to only enable the mode if you have uninstalled all versions of AzureRM! You can disable the compatiblity mode after you migrated all your scripts using the Disable-AzureRmAlias cmdlet.

You can also have both modules installed at the same time. In this case, don’t enable the compatibility mode! Instead, explicitly import either the Az or the AzureRM modules inside your scripts.

However, It is recommended to uninstall the old AzureRM module before using Az module:

Uninstall the AzureRM module

You can check whether you have any AzureRM module installed using the following cmdlet:

Get-Module -Name AzureRM -ListAvailable

get-module

To uninstall the module you can run the Uninstall-AzureRM cmdlet in an elevated PowerShell prompt.

You may get an error that the term Uninstall-AzureRM is not recognized as the name of a cmdlet:

Uninstall-AzureRM : The term ‘Uninstall-AzureRM’ is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

In this case, try to find and uninstall “Azure PowerShell” through the Windows system (Start -> Settings -> Apps, or appwiz.cpl). If this also doesn’t work, check this article: Uninstall the AzureRM module

Install the Az Azure PowerShell module

To install the module run the following cmdlet in an elevated session:

Install-Module -Name Az -AllowClobber

You may see the following prompt if this is the first time you use the PSGallery:

psgallery

Just Enter ‘Y’ – Yes or ‘A’ – Yes to All to continue.

You can verify the installation using:

Get-InstalledModule -Name Az -AllVersions

Use the new Az module

To use the new Az module, you first have to sign in using the Connect-AzAccount cmdlet. The interactive login now uses the device login so you have to copy and paste the token into https://aka.ms/devicelogin.

Once you have signed in to an Azure account, you can use the new cmdlets to access and manage your Azrue resoruces. Use Get-Command -Module Az* command to retrieve all available Az cmdlets:

get-command

 

 

 

Configure Azure Cloud Shell to use a profile hosted on GitHub

You may have noticed that you can run the Azure Cloud Shell without the portal as a separate component on https://shell.azure.com/

The shell is really handy since it can be used from everywhere. Today I want to show you how you can load a remote profile that is hosted on GitHub in the Azure Cloud Shell.

A PowerShell profile is used to add aliases, functions or variables to a session every time you start the shell.

The Azure Cloud Shell uses a fileshare stored on your storage account to persist files. This is also true for your profile. You can determine your profile path by entering:

$profile

You will see a path similar to this:

profile

This doesn’t mean that the profile exists, its just the path where Azure Cloud Shell tries to load your profile when you start it. You can determine whether the file actually exists using the Test-Path cmdlet:

Test-Path $profile

The cmdlet should return false if you didn’t already created a profile:

Capture

You could create a profile using the New-Item cmdlet and go to your file share to edit it. But you may like to have a history where you can compare the changes you made. You may also want to use the same profile for different accounts. So how can we connect a profile that is stored in a GitHub repository?

Lets start with adding the actual profile to our GitHub repository. My profile.ps1 contains a single function to print Hello World:

function Show-HelloWorld
{
    Write-Host "hello, world!"
}

Next we have to load the profile. For that purpose I have created another file called Set-Profile.ps1:

$profilePath = 'https://raw.githubusercontent.com/mjisaak/azure/master/profile.ps1'

$downloadString = '{0}?{1}' -f $profilePath, (New-Guid)
Invoke-Expression ((New-Object System.Net.WebClient).DownloadString($profilePath))

The $profilePath contains the URL to the previous created profile.ps1. I do append a query string to the path containg a random guid to prevent the web client from caching the file. This is particularly usefull when we update the profile.ps1 in the GitHub repository and want to load these changes without restarting the shell by dot sourcing the profile.
In line 4,  I download the profile.ps1 as a string and execute it using the Invoke-Expression cmdlet to load it to the runspace.

The last step we need to do is to set the content of the Set-Profile.ps1 to the actual PowerShell profile. We can do this by executing the following snippet in the Azure Cloud Shell:

(New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/mjisaak/azure/master/Set-Profile.ps1') |
  Set-Content $profile -Force

The snippet is using the web client again but instead of executing the code,  it pipes the string to the Set-Content cmdlet to override the profile. I can verfiy that by retrieving the content of $profile. This should output the content of my Set-Profile.ps1:

Capture4

Finally to load the profile we can either restart the PowerShell session or dot source the profile as mentioned earlier:

. $profile

And now we can use all the aliases, variables and function we have defined in the profile that is stored on GitHub:

helloworld