3.6 KiB
Az.Tools.Migration
Az.Tools.Migration is a PowerShell module for automatically upgrading your PowerShell scripts and script modules from AzureRM to the Az PowerShell module.
Contents
Description
The Az.Tools.Migration PowerShell module contains cmdlets that perform the following actions:
- Detect AzureRM cmdlet references in PowerShell scripts and script modules.
- Generate an upgrade plan to convert AzureRM module references to Az module commands.
- Execute the upgrade plan to modify your PowerShell codebase.
Getting started
You can use either method to use this module:
- Install this module from the PowerShell gallery.
Install-Module -Name Az.Tools.Migration
- Clone this repository and import the module locally. Use this option if you want to make changes to the module and test it out.
git clone https://github.com/Azure/azure-powershell-migration.git
import-module './azure-powershell-migration/powershell-module/Az.Tools.Migration/Az.Tools.Migration.psd1'
Usage Instructions
Requirements
Update your existing PowerShell codebase to the latest version of the AzureRM PowerShell module. The Az.Tools.Migration module detects commands based on AzureRM 6.13.1.
Step 1: Backup your code
IMPORTANT: There is no undo operation. Always ensure that you have a backup copy of your PowerShell scripts and modules that you're attempting to upgrade.
Step 2: Generate an upgrade plan
Generate an upgrade plan for moving the AzureRM references in your codebase to the Az PowerShell module. This step doesn't execute the plan, it only generates the upgrade steps.
IMPORTANT: Review the warnings and errors in the plan results. The output may contain commands or parameters that couldn't be upgraded automatically. These items require manual intervention during the upgrade.
This step can optionally be run for a single file by specifying the FilePath
parameter instead of the
DirectoryPath
parameter.
# Generate an upgrade plan for the script and module files in the specified folder and save it to a variable.
$plan = New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion 5.6.0 -DirectoryPath 'C:\Scripts'
# shows the entire upgrade plan
$plan
# filter plan result to only show warnings and errors
$plan | where PlanResult -ne ReadyToUpgrade | format-list
Step 3: Execute the upgrade plan
The upgrade plan is executed when you run the Invoke-AzUpgradeModulePlan
cmdlet. This command performs
an upgrade of the specified file or folders except for any errors that were identified by the New-AzUpgradeModulePlan
cmdlet.
This command requires you to specify if the files should be modified in place or if new files should be saved alongside your original files (leaving originals unmodified).
# Execute the automatic upgrade plan and save the results to a variable.
# Specify 'ModifyExistingFiles' to the -FileEditMode parameter if you would like the files to be modified in place instead of having new files created.
$result = Invoke-AzUpgradeModulePlan -Plan $plan -FileEditMode SaveChangesToNewFiles
# shows the entire upgrade operation result
$result
# filter results to show errors
$results | where UpgradeResult -ne UpgradeCompleted | format-list
Limitations
- File I/O operations use default encoding. Unusual file encoding situations may cause problems.
- AzureRM cmdlets passed as arguments to Pester unit test mock statements aren't detected.