4.4 KiB
| title | description | author | ms.service | ms.topic | ms.custom | ms.author | ms.date |
|---|---|---|---|---|---|---|---|
| Automatically migrate PowerShell scripts from AzureRM to the Az PowerShell module | Learn how to automatically migrate PowerShell scripts from AzureRM to the Az PowerShell module. | mikefrobbins | azure-powershell | quickstart | devx-track-azurepowershell | mirobb | 09/11/2020 |
Quickstart: Automatically migrate PowerShell scripts from AzureRM to the Az PowerShell module
In this article, you'll learn how to use the Az.Tools.Migration PowerShell module to automatically upgrade your PowerShell scripts and script modules from AzureRM to the Az PowerShell module.
Report feedback and issues about the Az.Tools.Migration PowerShell module via
a GitHub issue in the
azure-powershell-migration repository.
Requirements
-
Update your existing PowerShell scripts to AzureRM PowerShell module version 6.13.1 or 6.13.2.
-
Install the Az.Tools.Migration PowerShell module.
Install-Module -Name Az.Tools.Migration
Step 1: 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. The upgrade plan details the specific file and offset
points that require changes when moving from AzureRM to the Az PowerShell cmdlets.
[!NOTE] The
New-AzUpgradeModulePlancmdlet doesn't execute the plan, it only generates the upgrade steps.
# Generate an upgrade plan for the specified PowerShell script and save it to a variable.
$Plan = New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion latest -FilePath 'C:\Scripts\my-azure-script.ps1'
# Generate an upgrade plan for all the scripts and module files in the specified folder and save it to a variable.
$Plan = New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion latest -DirectoryPath 'C:\Scripts'
Review the results of the upgrade plan.
# Show the entire upgrade plan
$Plan
Run the following command to filter the results to commands that have warnings or errors. This may be helpful on large result sets to quickly identify errors before performing the upgrade.
# Filter plan results to only warnings and errors
$Plan | Where-Object PlanResult -ne ReadyToUpgrade | Format-List
Step 2: Perform the upgrade
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).
[!CAUTION] 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.
[!WARNING] The
Invoke-AzUpgradeModulePlancmdlet is destructive when the-FileEditMode ModifyExistingFilesoption is specified! It modifies your scripts and functions in place according to the module upgrade plan generated by theNew-AzUpgradeModulePlancmdlet. For the non-destructive option specify-FileEditMode SaveChangesToNewFilesinstead.
# Execute the automatic upgrade plan and save the results to a variable.
$Results = Invoke-AzUpgradeModulePlan -Plan $Plan -FileEditMode SaveChangesToNewFiles
Review the results of the upgrade operation.
# Show the results for the entire upgrade operation
$Results
If any errors are returned, you can take a closer look at the error results with the following command:
# Filter results to show only errors
$Results | Where-Object 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.
- Currently, only Az PowerShell module version 10.3 is supported as a target.
Next steps
To learn more about the Az PowerShell module, see the Azure PowerShell documentation