upgrade az version to 10, remove fixed version number in extension, breaking changes in cmdlet API (#118)

* upgrade to Az 10.X

* fix more

* fix test

* polish version

* polish changelog

* fix vscode extension

* polish how-to

* resolve path ro absolute

* update package-lock

* polish changelog

* psd1 as well

* better error handling

* add comments for version compare function

* bump major version

* delete preview announcement since module is already GAed

Author: VeryEarly

docs/how-to-update-az-module-spec.md

@@ -51,10 +51,6 @@ Have the following installed on your system:
    .\powershell-module\Scripts\New-AzCmdletSpec.ps1 -AzVersion $azModuleVersion -OutputDirectory (Join-Path -Path (Get-Location) -ChildPath 'powershell-module\Az.Tools.Migration\Resources\ModuleSpecs\Az\'$azModuleVersion)
    ```
 
-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 previous version. The previous version can be found under `\powershell-module\Az.Tools.Migration\Resources\ModuleSpecs\Az`. For example, search for '5.2.0' and replace with '5.6.0'. Please do not replace all because some files containing previous version, such as changelog, should not be replaced. 
-
 1. Remove the old module spec files from module resources:
    `powershell-module\Az.Tools.Migration\Resources\ModuleSpecs\Az\{old-version}`.
 

docs/quickstart-migrate-azurerm-to-az-automatically.md

@@ -14,12 +14,6 @@ ms.date: 09/11/2020
 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.
 
-> [!IMPORTANT]
-> The Az.Tools.Migration PowerShell module is currently in public preview. This preview version is
-> provided without a service level agreement. It's not recommended for production workloads. Certain
-> features might not be supported or might have constrained capabilities. For more information, see
-> [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
-
 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.
@@ -44,12 +38,12 @@ points that require changes when moving from AzureRM to the Az PowerShell cmdlet
 
 ```powershell
 #  Generate an upgrade plan for the specified PowerShell script and save it to a variable.
-$Plan = New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion 9.3.0 -FilePath 'C:\Scripts\my-azure-script.ps1'
+$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 9.3.0 -DirectoryPath 'C:\Scripts'
+$Plan = New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion latest -DirectoryPath 'C:\Scripts'
 ```
 
 Review the results of the upgrade plan.
@@ -106,7 +100,7 @@ $Results | Where-Object UpgradeResult -ne UpgradeCompleted | Format-List
 
 * 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 9.3.0 is supported as a target.
+* Currently, only Az PowerShell module version 10.3 is supported as a target.
 
 ## Next steps
 

powershell-module/Az.Tools.Migration/Az.Tools.Migration.psd1

@@ -3,7 +3,7 @@
     RootModule = 'Az.Tools.Migration.psm1'
 
     # Version number of this module.
-    ModuleVersion = '1.1.4'
+    ModuleVersion = '2.0.0'
 
     # Supported PSEditions
     CompatiblePSEditions = 'Core', 'Desktop'
@@ -108,7 +108,16 @@
             # IconUri = ''
 
             # ReleaseNotes of this module
-            ReleaseNotes = '* Upgrade Az version to 9.3.0'
+            ReleaseNotes = "* Supported AzureRM to Az 10.3 migration
+            * `Get-AzUpgradeAliasSpec`
+                * Parameter `ModuleVersion` now accept value 'latest' only [BreakingChange]
+            * `Get-AzUpgradeCmdletSpec`
+                * Parameter `ModuleName` removed` [BreakingChange]
+                * Added switch parameters `AzureRM` and `Az`
+                * Parameter `ModuleVersion` now accept value 'latest' only and has to be used with `Az` [BreakingChange]
+            * `New-AzUpgradeModulePlan`
+                * Parameter `ToAzVersion` now accept value 'latest' only [BreakingChange]
+                * Parameter `FilePath` now accept relative file path"
         }
     }
 

powershell-module/Az.Tools.Migration/Functions/Public/Find-AzUpgradeCommandReference.ps1

@@ -34,7 +34,7 @@ function Find-AzUpgradeCommandReference
         The following example finds AzureRM PowerShell command references in the specified directory and subfolders but with a pre-loaded module specification.
         This is helpful to avoid reloading the module specification if the Find-AzUpgradeCommandReference command needs to be executed several times.
 
-        $moduleSpec = Get-AzUpgradeCmdletSpec -ModuleName "AzureRM" -ModuleVersion "6.13.1"
+        $moduleSpec = Get-AzUpgradeCmdletSpec -AzureRM
         Find-AzUpgradeCommandReference -DirectoryPath 'C:\Scripts1' -AzureRmModuleSpec $moduleSpec
         Find-AzUpgradeCommandReference -DirectoryPath 'C:\Scripts2' -AzureRmModuleSpec $moduleSpec
         Find-AzUpgradeCommandReference -DirectoryPath 'C:\Scripts3' -AzureRmModuleSpec $moduleSpec
@@ -92,12 +92,13 @@ function Find-AzUpgradeCommandReference
     Process
     {
         $cmdStarted = Get-Date
+        $FilePath = (Resolve-Path $FilePath).Path
 
         if ($PSBoundParameters.ContainsKey('AzureRmModuleSpec') -eq $false)
         {
             # load the command specs
             Write-Verbose -Message "Loading cmdlet spec for AzureRM $AzureRmVersion"
-            $AzureRmModuleSpec = Get-AzUpgradeCmdletSpec -ModuleName "AzureRM" -ModuleVersion $AzureRmVersion
+            $AzureRmModuleSpec = Get-AzUpgradeCmdletSpec -AzureRM
         }
         else
         {

powershell-module/Az.Tools.Migration/Functions/Public/Get-AzUpgradeAliasSpec.ps1

@@ -11,8 +11,8 @@ function Get-AzUpgradeAliasSpec
         Specify the version of the module to import command aliases from.
 
     .EXAMPLE
-        PS C:\> Get-AzUpgradeAliasSpec -ModuleVersion "9.3.0"
-        Returns the cmdlet alias mappings table for Az 9.3.0.
+        PS C:\> Get-AzUpgradeAliasSpec -ModuleVersion latest
+        Returns the cmdlet alias mappings table for latest Az version
     #>
     [CmdletBinding()]
     Param
@@ -22,12 +22,16 @@ function Get-AzUpgradeAliasSpec
             HelpMessage="Specify the version of the module to import command definitions from.")]
         [System.String]
         [ValidateNotNullOrEmpty()]
+        [ValidateSet('latest')]
         $ModuleVersion
     )
     Process
     {
-        $aliasSpecFile = Join-Path -Path $MyInvocation.MyCommand.Module.ModuleBase `
-            -ChildPath "Resources\ModuleSpecs\Az\$ModuleVersion\CmdletAliases\Aliases.json"
+        $path = Join-Path -Path $MyInvocation.MyCommand.Module.ModuleBase -ChildPath "\Resources\ModuleSpecs\Az\$ModuleVersion"
+        $version = Get-ChildItem -Path $path -Name
+
+        $aliasSpecFile = Join-Path -Path $path `
+            -ChildPath "$version\CmdletAliases\Aliases.json"
 
         if ((Test-Path -Path $aliasSpecFile) -eq $false)
         {

powershell-module/Az.Tools.Migration/Functions/Public/Get-AzUpgradeCmdletSpec.ps1

@@ -14,41 +14,56 @@ function Get-AzUpgradeCmdletSpec
         Specify the version of the module to load command definitions from.
 
     .EXAMPLE
-        PS C:\> Get-AzUpgradeCmdletSpec -ModuleName "AzureRM" -ModuleVersion "6.13.1"
+        PS C:\> Get-AzUpgradeCmdletSpec -AzureRM
         Returns the dictionary containing cmdlet specification objects for AzureRM 6.13.1.
     #>
     [CmdletBinding()]
     Param
     (
         [Parameter(
             Mandatory=$true,
-            HelpMessage="Specify the name of the module to import command definitions from.")]
-        [System.String]
-        [ValidateNotNullOrEmpty()]
-        $ModuleName,
+            ParameterSetName = "AzureRM",
+            HelpMessage="Import command definitions from AzureRM modules.")]
+        [System.Management.Automation.SwitchParameter]
+        $AzureRM,
+
+        [Parameter(
+            Mandatory=$true,
+            ParameterSetName = "Az",
+            HelpMessage="Import command definitions from Az modules.")]
+        [System.Management.Automation.SwitchParameter]
+        $Az,
 
         [Parameter(
             Mandatory=$true,
+            ParameterSetName = "Az",
             HelpMessage="Specify the version of the module to import command definitions from.")]
         [System.String]
+        [ValidateSet('latest')]
         [ValidateNotNullOrEmpty()]
         $ModuleVersion
     )
     Process
     {
         $ModuleSpecFolder = Join-Path -Path $MyInvocation.MyCommand.Module.ModuleBase `
-            -ChildPath "Resources\ModuleSpecs\$ModuleName\$ModuleVersion"
+            -ChildPath "Resources\ModuleSpecs"
+        if ($PSBoundParameters.ContainsKey('AzureRM')) {
+            $ModuleSpecFolder = Join-Path -Path $ModuleSpecFolder -ChildPath "AzureRM\6.13.1"
+        } else {
+            $version = Get-ChildItem -Path "$ModuleSpecFolder/Az/$ModuleVersion" -Name
+            $ModuleSpecFolder = Join-Path -Path $ModuleSpecFolder -ChildPath "Az\$ModuleVersion\$version"
+        }
 
         if ((Test-Path -Path $ModuleSpecFolder) -eq $false)
         {
-            throw "No module spec files found for module: $ModuleName $ModuleVersion"
+            throw "No module spec files found for module: $ModuleName $version under $ModuleSpecFolder"
         }
 
         $ModuleSpecFiles = Get-ChildItem -Path $ModuleSpecFolder -File
 
         if ($ModuleSpecFiles -eq $null)
         {
-            throw "No module spec files found for module: $ModuleName $ModuleVersion"
+            throw "No module spec files found for module: $ModuleName $version under $ModuleSpecFolder"
         }
 
         $results = New-Object -TypeName 'System.Collections.Generic.Dictionary[System.String,CommandDefinition]' -ArgumentList (, [System.StringComparer]::OrdinalIgnoreCase)

powershell-module/Az.Tools.Migration/Functions/Public/Invoke-AzUpgradeModulePlan.ps1

@@ -23,7 +23,7 @@ function Invoke-AzUpgradeModulePlan
         The following example invokes the upgrade plan for a PowerShell module named "myModule" and saves the updated file contents into new files (leaving original files unmodified).
 
         # step 1: generate a plan and save it to a variable.
-        $plan = New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion 9.3.0 -DirectoryPath 'C:\Scripts\myModule'
+        $plan = New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion latest -DirectoryPath 'C:\Scripts\myModule'
 
         # step 2: write the plan to the console to review the upgrade steps, warnings, and errors.
         $plan
@@ -38,7 +38,7 @@ function Invoke-AzUpgradeModulePlan
         The following example invokes the upgrade plan for a PowerShell module named "myModule" and modifies the existing files in place.
 
         # step 1: generate a plan and save it to a variable.
-        $plan = New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion 9.3.0 -DirectoryPath 'C:\Scripts\myModule'
+        $plan = New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion latest -DirectoryPath 'C:\Scripts\myModule'
 
         # step 2: write the plan to the console to review the upgrade steps, warnings, and errors.
         $plan

powershell-module/Az.Tools.Migration/Functions/Public/New-AzUpgradeModulePlan.ps1

@@ -11,7 +11,7 @@ function New-AzUpgradeModulePlan
         Specifies the AzureRM module version used in your existing PowerShell scripts(s) or modules.
 
     .PARAMETER ToAzVersion
-        Specifies the Az module version to upgrade to. Currently, only Az version 9.3.0 is supported.
+        Specifies the Az module version to upgrade to. Currently, only Az version 10.3 is supported.
 
     .PARAMETER FilePath
         Specifies the path to a single PowerShell file.
@@ -34,32 +34,32 @@ function New-AzUpgradeModulePlan
     .EXAMPLE
         The following example generates a new Az module upgrade plan for the script file 'C:\Scripts\my-azure-script.ps1'.
 
-        New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion 9.3.0 -FilePath 'C:\Scripts\my-azure-script.ps1'
+        New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion latest -FilePath 'C:\Scripts\my-azure-script.ps1'
 
     .EXAMPLE
         The following example generates a new Az module upgrade plan for the script and module files located under C:\Scripts.
 
-        New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion 9.3.0 -DirectoryPath 'C:\Scripts'
+        New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion latest -DirectoryPath 'C:\Scripts'
 
     .EXAMPLE
         The following example generates a new Az module upgrade plan for the script and module files under C:\Scripts.
 
         $references = Find-AzUpgradeCommandReference -DirectoryPath 'C:\Scripts' -AzureRmVersion '6.13.1'
-        New-AzUpgradeModulePlan -ToAzVersion 9.3.0 -AzureRmCmdReference $references
+        New-AzUpgradeModulePlan -ToAzVersion latest -AzureRmCmdReference $references
 
     .EXAMPLE
         The following example generates a new Az module upgrade plan for the script and module files under several directories.
         Module specs are pre-loaded here to avoid re-loading the spec each time a plan is generated.
 
         # pre-load specifications
-        $armSpec = Get-AzUpgradeCmdletSpec -ModuleName "AzureRM" -ModuleVersion "6.13.1"
-        $azSpec = Get-AzUpgradeCmdletSpec -ModuleName "Az" -ModuleVersion "9.3.0"
-        $azAliases = Get-AzUpgradeAliasSpec -ModuleVersion "9.3.0"
+        $armSpec = Get-AzUpgradeCmdletSpec -AzureRM
+        $azSpec = Get-AzUpgradeCmdletSpec -Az -ModuleVersion latest
+        $azAliases = Get-AzUpgradeAliasSpec -ModuleVersion latest
 
         # execute a batch of module upgrades
-        $plan1 = New-AzUpgradeModulePlan -DirectoryPath 'C:\Scripts1' -FromAzureRmVersion '6.13.1' -ToAzVersion '9.3.0' -AzureRmModuleSpec $armSpec -AzModuleSpec $azSpec -AzAliasMappingSpec $azAliases
-        $plan2 = New-AzUpgradeModulePlan -DirectoryPath 'C:\Scripts2' -FromAzureRmVersion '6.13.1' -ToAzVersion '9.3.0' -AzureRmModuleSpec $armSpec -AzModuleSpec $azSpec -AzAliasMappingSpec $azAliases
-        $plan3 = New-AzUpgradeModulePlan -DirectoryPath 'C:\Scripts3' -FromAzureRmVersion '6.13.1' -ToAzVersion '9.3.0' -AzureRmModuleSpec $armSpec -AzModuleSpec $azSpec -AzAliasMappingSpec $azAliases
+        $plan1 = New-AzUpgradeModulePlan -DirectoryPath 'C:\Scripts1' -FromAzureRmVersion '6.13.1' -ToAzVersion latest -AzureRmModuleSpec $armSpec -AzModuleSpec $azSpec -AzAliasMappingSpec $azAliases
+        $plan2 = New-AzUpgradeModulePlan -DirectoryPath 'C:\Scripts2' -FromAzureRmVersion '6.13.1' -ToAzVersion latest -AzureRmModuleSpec $armSpec -AzModuleSpec $azSpec -AzAliasMappingSpec $azAliases
+        $plan3 = New-AzUpgradeModulePlan -DirectoryPath 'C:\Scripts3' -FromAzureRmVersion '6.13.1' -ToAzVersion latest -AzureRmModuleSpec $armSpec -AzModuleSpec $azSpec -AzAliasMappingSpec $azAliases
     #>
     [CmdletBinding()]
     Param
@@ -103,7 +103,7 @@ function New-AzUpgradeModulePlan
             Mandatory=$true,
             HelpMessage='Specify the Az module version to upgrade to.')]
         [System.String]
-        [ValidateSet('9.3.0')]
+        [ValidateSet('latest')]
         $ToAzVersion,
 
         [Parameter(Mandatory=$false)]
@@ -122,6 +122,10 @@ function New-AzUpgradeModulePlan
     {
         $cmdStarted = Get-Date
 
+        $FilePath = (Resolve-Path $FilePath).Path
+        $versionPath = Join-Path -Path $MyInvocation.MyCommand.Module.ModuleBase -ChildPath "\Resources\ModuleSpecs\Az\$ToAzVersion"
+        $version = Get-ChildItem -Path $versionPath -Name
+
         # if an existing set of command references was not provided
         # then call the Find cmdlet to search for those references.
 
@@ -166,8 +170,9 @@ function New-AzUpgradeModulePlan
 
         if ($PSBoundParameters.ContainsKey('AzModuleSpec') -eq $false)
         {
-            Write-Verbose -Message "Importing cmdlet spec for Az $ToAzVersion"
-            $AzModuleSpec = Get-AzUpgradeCmdletSpec -ModuleName "Az" -ModuleVersion $ToAzVersion
+
+            Write-Verbose -Message "Importing cmdlet spec for Az $version"
+            $AzModuleSpec = Get-AzUpgradeCmdletSpec -Az -ModuleVersion $ToAzVersion
         }
         else
         {
@@ -176,7 +181,7 @@ function New-AzUpgradeModulePlan
 
         if ($PSBoundParameters.ContainsKey('AzAliasMappingSpec') -eq $false)
         {
-            Write-Verbose -Message "Importing alias mapping spec for Az $ToAzVersion"
+            Write-Verbose -Message "Importing alias mapping spec for Az $version"
             $AzAliasMappingSpec = Get-AzUpgradeAliasSpec -ModuleVersion $ToAzVersion
         }
         else
@@ -344,7 +349,7 @@ function New-AzUpgradeModulePlan
             -Duration ((Get-Date) - $cmdStarted) `
             -Properties ([PSCustomObject]@{
                 ToAzureModuleName = "Az"
-                ToAzureModuleVersion = $ToAzVersion
+                ToAzureModuleVersion = $version
                 UpgradeStepsCount = $planSteps.Count
                 PlanWarnings = $planWarningSteps
                 PlanErrors = $planErrorSteps