Updated docs for pwsh and markdown standardization (#46)
Co-authored-by: Mike F. Robbins <mikefrobbins@users.noreply.github.com>
This commit is contained in:
Mike F. Robbins
GitHub
Родитель
27157461fb
Коммит
cd4088ef64
|
|
@ -1,10 +1,13 @@
|
|||
# AzureRM to Az Migration
|
||||
# AzureRM to Az Migration Toolkit
|
||||
|
||||
Effortlessly migrate your PowerShell scripts from AzureRM to the [Az PowerShell module](https://docs.microsoft.com/powershell/azure/install-az-ps).
|
||||
|
||||
This repository includes a PowerShell module and a VSCode extension to automate the migration of
|
||||
your PowerShell scripts and modules from AzureRM to the Az PowerShell module.
|
||||
|
||||
The current version of the migration toolkit is aimed at AzureRM to Az migration. We are
|
||||
considering adding the additional capability to migrate between Az versions.
|
||||
|
||||
## Repository Structure
|
||||
|
||||
* common
|
||||
|
|
@ -20,9 +23,6 @@ your PowerShell scripts and modules from AzureRM to the Az PowerShell module.
|
|||
* vscode-extension
|
||||
* Code for the VSCode extension.
|
||||
|
||||
The current version of the migration toolkit is aimed at AzureRM to Az migration. We are
|
||||
considering adding the additional capability to migrate between Az versions.
|
||||
|
||||
## Feedback
|
||||
|
||||
We welcome issues and PRs. Feel free to open issues for suggestions of new features.
|
||||
|
|
|
|||
|
|
@ -1,50 +1,60 @@
|
|||
# How to Update Az Module Spec
|
||||
|
||||
The Az module command and alias specifications are stored in `powershell-module\Az.Tools.Migration\Resources\ModuleSpecs\Az\{version}`.
|
||||
The Az PowerShell module command and alias specifications are stored in
|
||||
`powershell-module\Az.Tools.Migration\Resources\ModuleSpecs\Az\{version}`.
|
||||
|
||||
Occasionally these should be updated to latest. This document describes how to update the spec to latest.
|
||||
Occasionally, these should be updated to latest. This document describes how to update the spec to latest.
|
||||
|
||||
## Requirements
|
||||
|
||||
* You have PowerShell Core 7.x or later installed on your system.
|
||||
* You have installed the `Az.Tools.Migration` module and it is available in your PSModulePath.
|
||||
* You have cloned this Git repository to your local computer.
|
||||
Have the following installed on your system:
|
||||
|
||||
* PowerShell 7.x or later.
|
||||
* `Az.Tools.Migration` module. This module must exist in a file system path specified in
|
||||
`$env:PSModulePath`.
|
||||
* Cloned the [azure-powershell-migration](https://github.com/Azure/azure-powershell-migration)
|
||||
GitHub repository to your local computer.
|
||||
|
||||
## Update Instructions
|
||||
|
||||
1. Open a PowerShell Core (7.x or later) prompt.
|
||||
1. Open a PowerShell 7.x or later prompt.
|
||||
|
||||
2. Install the desired target version of Az to your local user scope. For example, this would install it for v4.6.1.
|
||||
1. Install the desired target version of the Az PowerShell module to your local computer, specifying
|
||||
the `CurrentUser` scope. For example, the following installs v4.6.1 in the current user's scope.
|
||||
|
||||
```powershell
|
||||
Install-Module -Name Az -RequiredVersion 4.6.1 -Scope CurrentUser -AllowClobber -SkipPublisherCheck -Force
|
||||
```
|
||||
```powershell
|
||||
Install-Module -Name Az -RequiredVersion 4.6.1 -Scope CurrentUser -AllowClobber -Force
|
||||
```
|
||||
|
||||
3. Import the Az.Tools.Migration module.
|
||||
1. Import the Az.Tools.Migration PowerShell module.
|
||||
|
||||
```powershell
|
||||
Import-Module Az.Tools.Migration
|
||||
```
|
||||
```powershell
|
||||
Import-Module -Name Az.Tools.Migration
|
||||
```
|
||||
|
||||
4. Run the module spec generation script for the desired version.
|
||||
1. Run the module spec generation script for the desired version.
|
||||
|
||||
* Update the module repo path to where you have cloned the repository.
|
||||
* Ensure the Az module version variable is also set correctly to the desired version.
|
||||
* Update the module repo path to the file system location where you cloned the repository.
|
||||
* Ensure the Az PowerShell module version variable is set to the desired version.
|
||||
|
||||
```powershell
|
||||
# setup
|
||||
$moduleRepo = "C:\source\azure-powershell-migration"
|
||||
$azModuleVersion = "4.6.1"
|
||||
$outputDirectory = Join-Path -Path $moduleRepo -ChildPath "powershell-module\Az.Tools.Migration\Resources\ModuleSpecs\Az\$azModuleVersion"
|
||||
```powershell
|
||||
# setup
|
||||
$moduleRepo = 'C:\source\azure-powershell-migration'
|
||||
$azModuleVersion = '4.6.1'
|
||||
$outputDirectory = Join-Path -Path $moduleRepo -ChildPath "powershell-module\Az.Tools.Migration\Resources\ModuleSpecs\Az\$azModuleVersion"
|
||||
|
||||
# execute
|
||||
. $moduleRepo\powershell-module\Scripts\New-AzCmdletSpec.ps1 -AzVersion $azModuleVersion -OutputDirectory $outputDirectory
|
||||
```
|
||||
# execute
|
||||
. $moduleRepo\powershell-module\Scripts\New-AzCmdletSpec.ps1 -AzVersion $azModuleVersion -OutputDirectory $outputDirectory
|
||||
```
|
||||
|
||||
5. Update the Az version listed in documentation, function help, function parameter validation, and unit tests. The easiest way to do this is to do a search and replace on the old version. For example search for '4.4.0' and replace with '4.6.1'.
|
||||
1. Update the Az PowerShell module version listed in documentation, function help, function
|
||||
parameter validation, and unit tests. The easiest way to do this is to perform a search to find
|
||||
and replace the old version. For example, search for '4.4.0' and replace with '4.6.1'.
|
||||
|
||||
6. Remove the old module spec files from module resources: `powershell-module\Az.Tools.Migration\Resources\ModuleSpecs\Az\{old-version}`
|
||||
1. Remove the old module spec files from module resources:
|
||||
`powershell-module\Az.Tools.Migration\Resources\ModuleSpecs\Az\{old-version}`.
|
||||
|
||||
7. Run the unit tests to make sure all of the unit tests still pass. Usually a couple of tests will fail because the expected number of aliases or cmdlets from the specs has changed.
|
||||
1. Run the unit tests to make sure all unit tests pass. It's not uncommon for some tests to fail
|
||||
because the expected number of aliases or cmdlets from the specs has changed.
|
||||
|
||||
8. Submit a pull request to commit the new changes.
|
||||
1. Submit a pull request to commit the new changes.
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ ms.service: azure-powershell
|
|||
ms.topic: quickstart
|
||||
ms.custom: devx-track-azurepowershell
|
||||
ms.author: mirobb
|
||||
ms.date: 07/29/2020
|
||||
ms.date: 09/11/2020
|
||||
---
|
||||
|
||||
# Quickstart: Automatically migrate PowerShell scripts from AzureRM to the Az PowerShell module
|
||||
|
|
@ -50,8 +50,8 @@ Find-AzUpgradeCommandReference -FilePath 'C:\Scripts\test.ps1' -AzureRmVersion '
|
|||
Find-AzUpgradeCommandReference -DirectoryPath 'C:\Scripts' -AzureRmVersion '6.13.1'
|
||||
```
|
||||
|
||||
The output of `Find-AzUpgradeCommandReference` can be passed as a parameter to `New-AzUpgradeModulePlan` to
|
||||
generate a detailed list of required upgrade changes.
|
||||
The output of `Find-AzUpgradeCommandReference` can be passed as a parameter to
|
||||
`New-AzUpgradeModulePlan` to generate a detailed list of required upgrade changes.
|
||||
|
||||
## Generate an upgrade plan
|
||||
|
||||
|
|
@ -68,22 +68,23 @@ $Plan = New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion 4.6.1 -F
|
|||
```
|
||||
|
||||
```powershell
|
||||
# Generate an upgrade plan for the script and module files in the specified folder and save it to a variable.
|
||||
# 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 4.6.1 -DirectoryPath 'C:\Scripts'
|
||||
```
|
||||
|
||||
Review the results of the upgrade plan.
|
||||
|
||||
```powershell
|
||||
# shows the entire 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 the upgrade.
|
||||
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 result to only show warnings and errors
|
||||
$Plan | where PlanResult -ne ReadyToUpgrade | format-list
|
||||
# Filter plan results to only warnings and errors
|
||||
$Plan | Where-Object PlanResult -ne ReadyToUpgrade | Format-List
|
||||
```
|
||||
|
||||
## Perform the upgrade
|
||||
|
|
@ -96,8 +97,9 @@ The upgrade plan is executed when you run the `Invoke-AzUpgradeModulePlan` cmdle
|
|||
performs an in-place upgrade of the specified file or folders except for any errors
|
||||
that were identified by the `New-AzUpgradeModulePlan` cmdlet.
|
||||
|
||||
> [!WARNING] The `Invoke-AzUpgradeModulePlan` cmdlet is destructive! It modifies your scripts and
|
||||
> functions according to the module upgrade plan generated by the `New-AzUpgradeModulePlan` cmdlet.
|
||||
> [!WARNING]
|
||||
> The `Invoke-AzUpgradeModulePlan` cmdlet is destructive! It modifies your scripts and functions
|
||||
> according to the module upgrade plan generated by the `New-AzUpgradeModulePlan` cmdlet.
|
||||
|
||||
```powershell
|
||||
# Execute the automatic upgrade plan and save the results to a variable.
|
||||
|
|
@ -107,15 +109,15 @@ $Results = Invoke-AzUpgradeModulePlan -Plan $Plan
|
|||
Review the results of the upgrade operation.
|
||||
|
||||
```powershell
|
||||
# shows the entire upgrade operation result
|
||||
# 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 errors
|
||||
$Results | where UpgradeResult -ne UpgradeCompleted | format-list
|
||||
# Filter results to show only errors
|
||||
$Results | Where-Object UpgradeResult -ne UpgradeCompleted | Format-List
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче