107 строки
4.4 KiB
Markdown
107 строки
4.4 KiB
Markdown
---
|
|
title: Automatically migrate PowerShell scripts from AzureRM to the Az PowerShell module
|
|
description: Learn how to automatically migrate PowerShell scripts from AzureRM to the Az PowerShell module.
|
|
author: mikefrobbins
|
|
ms.service: azure-powershell
|
|
ms.topic: quickstart
|
|
ms.custom: devx-track-azurepowershell
|
|
ms.author: mirobb
|
|
ms.date: 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](https://github.com/Azure/azure-powershell-migration/issues) in the
|
|
`azure-powershell-migration` repository.
|
|
|
|
## Requirements
|
|
|
|
* Update your existing PowerShell scripts to AzureRM PowerShell module version [6.13.1](https://github.com/Azure/azure-powershell/releases/tag/v6.13.1-November2018) or [6.13.2](https://github.com/Azure/azure-powershell/releases/tag/v6.13.2-March2021).
|
|
* Install the Az.Tools.Migration PowerShell module.
|
|
|
|
```powershell
|
|
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-AzUpgradeModulePlan` cmdlet doesn't execute the plan, it only generates the upgrade steps.
|
|
|
|
```powershell
|
|
# 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'
|
|
```
|
|
|
|
```powershell
|
|
# 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.
|
|
|
|
```powershell
|
|
# 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.
|
|
|
|
```powershell
|
|
# 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-AzUpgradeModulePlan` cmdlet is destructive when the `-FileEditMode ModifyExistingFiles` option is specified! It modifies your scripts and functions
|
|
> in place according to the module upgrade plan generated by the `New-AzUpgradeModulePlan` cmdlet. For the non-destructive option specify `-FileEditMode SaveChangesToNewFiles` instead.
|
|
|
|
```powershell
|
|
# 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.
|
|
|
|
```powershell
|
|
# 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:
|
|
|
|
```powershell
|
|
# 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](https://docs.microsoft.com/powershell/azure/) |