Démarrage rapide : Effectuer une migration automatique des scripts PowerShell entre le module AzureRM et le module Az PowerShell

Article
03/08/2023
4 minutes de lecture

Dans cet article, vous allez apprendre à utiliser le module PowerShell Az.Tools.Migration pour mettre automatiquement à niveau vos scripts et vos modules de script PowerShell entre le module AzureRM et le module Az PowerShell. Pour plus d’options de migration, consultez Migrer Azure PowerShell depuis AzureRM vers Az.

Attention

Étant donné que les modules Az PowerShell ont maintenant toutes les fonctionnalités des modules AzureRM PowerShell et plus encore, nous allons mettre hors service les modules AzureRM PowerShell le 29 février 2024.

Pour éviter les interruptions de service, mettez à jour vos scripts qui utilisent les modules AzureRM PowerShell pour utiliser les modules Az PowerShell avant le 29 février 2024. Pour mettre à jour automatiquement vos scripts, suivez le Guide de démarrage rapide.

Spécifications

Mettez à jour vos scripts PowerShell existants vers la dernière version du module PowerShell AzureRM (6.13.1).
Installez le module PowerShell Az.Tools.Migration.
```
Install-Module -Name Az.Tools.Migration
```

Étape 1 : Générer un plan de mise à niveau

Utilisez l’applet de commande New-AzUpgradeModulePlan afin de générer un plan de mise à niveau pour la migration de vos scripts et de vos modules vers le module PowerShell Az. Cette applet de commande n’apporte aucune modification à vos scripts existants. Utilisez le paramètre FilePath pour cibler un script spécifique ou le paramètre DirectoryPath pour cibler tous les scripts d’un dossier spécifique.

Notes

L’applet de commande New-AzUpgradeModulePlan n’exécute pas le plan, mais génère uniquement les étapes de mise à niveau.

L’exemple suivant génère un plan pour tous les scripts dans le dossier C:\Scripts . Le paramètre OutVariable est spécifié afin que les résultats soient retournés et stockés simultanément dans une variable nommée Plan .

# Generate an upgrade plan for all the scripts and module files in the specified folder and save it to a variable.
New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion 8.0.0 -DirectoryPath 'C:\Scripts' -OutVariable Plan

Comme illustré dans la sortie suivante, le plan de mise à niveau donne le détail de ce qui devra être modifié lors du passage des applets de commande d’AzureRM à celles d’Az PowerShell.

Order Location                                                   UpgradeType     PlanResult             Original
----- --------                                                   -----------     ----------             --------
1     compute-create-dockerhost.ps1:59:24                        CmdletParameter ReadyToUpgrade         ExtensionName
2     compute-create-dockerhost.ps1:59:1                         Cmdlet          ReadyToUpgrade         Set-AzureRmVM...
3     compute-create-dockerhost.ps1:54:1                         Cmdlet          ReadyToUpgrade         New-AzureRmVM
4     compute-create-dockerhost.ps1:51:1                         Cmdlet          ReadyToUpgrade         Add-AzureRmVM...
5     compute-create-dockerhost.ps1:47:1                         Cmdlet          ReadyToUpgrade         Add-AzureRmVM...
6     compute-create-dockerhost.ps1:46:1                         Cmdlet          ReadyToUpgrade         Set-AzureRmVM...
7     compute-create-dockerhost.ps1:45:1                         Cmdlet          ReadyToUpgrade         Set-AzureRmVM...
8     compute-create-dockerhost.ps1:44:13                        Cmdlet          ReadyToUpgrade         New-AzureRmVM...
9     compute-create-dockerhost.ps1:40:8                         Cmdlet          ReadyToUpgrade         New-AzureRmNe...
10    compute-create-dockerhost.ps1:36:8                         Cmdlet          ReadyToUpgrade         New-AzureRmNe...
11    compute-create-dockerhost.ps1:31:16                        Cmdlet          ReadyToUpgrade         New-AzureRmNe...
12    compute-create-dockerhost.ps1:26:15                        Cmdlet          ReadyToUpgrade         New-AzureRmNe...
13    compute-create-dockerhost.ps1:22:8                         Cmdlet          ReadyToUpgrade         New-AzureRmPu...
14    compute-create-dockerhost.ps1:18:9                         Cmdlet          ReadyToUpgrade         New-AzureRmVi...
15    compute-create-dockerhost.ps1:15:17                        Cmdlet          ReadyToUpgrade         New-AzureRmVi...
16    compute-create-dockerhost.ps1:12:1                         Cmdlet          ReadyToUpgrade         New-AzureRmRe...
17    compute-create-windowsvm-quick.ps1:18:3                    CmdletParameter ReadyToUpgrade         ImageName
18    compute-create-windowsvm-quick.ps1:14:1                    Cmdlet          ReadyToUpgrade         New-AzureRmVM
19    compute-create-windowsvm-quick.ps1:11:1                    Cmdlet          ReadyToUpgrade         New-AzureRmRe...
20    compute-create-wordpress-mysql.ps1:59:24                   CmdletParameter ReadyToUpgrade         ExtensionName
...

Avant d’effectuer la mise à niveau, vous devez afficher les résultats du plan pour voir les problèmes. L’exemple suivant retourne une liste de scripts et les éléments de ces scripts qui les empêcheront d’être automatiquement mis à niveau.

# Filter plan results to only warnings and errors
$Plan | Where-Object PlanResult -ne ReadyToUpgrade | Format-List

Les éléments montrés dans la sortie suivante ne sont pas mis à niveau automatiquement sans d’abord corriger manuellement les problèmes.

Order                  : 42
UpgradeType            : CmdletParameter
PlanResult             : ErrorParameterNotFound
PlanSeverity           : Error
PlanResultReason       : Parameter was not found in Get-AzResource or it's aliases.
SourceCommand          : CommandReference
SourceCommandParameter : CommandReferenceParameter
Location               : devtestlab-add-marketplace-image-to-lab.ps1:14:74
FullPath               : C:\Scripts\devtestlab-add-marketplace-image-to-lab.ps1
StartOffset            : 556
Original               : ResourceNameEquals
Replacement            :

Étape 2 : Effectuer la mise à niveau

Attention

Aucune annulation n’est possible. Avant de mettre à niveau vos scripts et vos modules PowerShell, assurez-vous toujours que vous disposez d’une copie de sauvegarde.

Une fois que vous êtes satisfait du plan, la mise à niveau est effectuée avec l’applet de commande Invoke-AzUpgradeModulePlan . Spécifiez SaveChangesToNewFiles pour la valeur de paramètre FileEditMode afin d’empêcher que des modifications ne soient apportées à vos scripts d’origine. Lorsque vous utilisez ce mode, la mise à niveau s’effectue en créant une copie de chaque script ciblé avec _az_upgraded ajouté aux noms de fichiers.

Avertissement

L’applet de commande Invoke-AzUpgradeModulePlan est destructrice si l’option -FileEditMode ModifyExistingFiles est spécifiée. Elle modifie vos scripts et vos fonctions en place selon le plan de mise à niveau de module généré par l’applet de commande New-AzUpgradeModulePlan. Pour choisir l’option non destructrice, spécifiez -FileEditMode SaveChangesToNewFiles à la place.

# Execute the automatic upgrade plan and save the results to a variable.
Invoke-AzUpgradeModulePlan -Plan $Plan -FileEditMode SaveChangesToNewFiles -OutVariable Results

Order Location                                                   UpgradeType     UpgradeResult    Original
----- --------                                                   -----------     -------------    --------
1     compute-create-dockerhost.ps1:59:24                        CmdletParameter UpgradeCompleted ExtensionName
2     compute-create-dockerhost.ps1:59:1                         Cmdlet          UpgradeCompleted Set-AzureRmVMExtens...
3     compute-create-dockerhost.ps1:54:1                         Cmdlet          UpgradeCompleted New-AzureRmVM
4     compute-create-dockerhost.ps1:51:1                         Cmdlet          UpgradeCompleted Add-AzureRmVMSshPub...
5     compute-create-dockerhost.ps1:47:1                         Cmdlet          UpgradeCompleted Add-AzureRmVMNetwor...
6     compute-create-dockerhost.ps1:46:1                         Cmdlet          UpgradeCompleted Set-AzureRmVMSource...
7     compute-create-dockerhost.ps1:45:1                         Cmdlet          UpgradeCompleted Set-AzureRmVMOperat...
8     compute-create-dockerhost.ps1:44:13                        Cmdlet          UpgradeCompleted New-AzureRmVMConfig
9     compute-create-dockerhost.ps1:40:8                         Cmdlet          UpgradeCompleted New-AzureRmNetworkI...
10    compute-create-dockerhost.ps1:36:8                         Cmdlet          UpgradeCompleted New-AzureRmNetworkS...
11    compute-create-dockerhost.ps1:31:16                        Cmdlet          UpgradeCompleted New-AzureRmNetworkS...
12    compute-create-dockerhost.ps1:26:15                        Cmdlet          UpgradeCompleted New-AzureRmNetworkS...
13    compute-create-dockerhost.ps1:22:8                         Cmdlet          UpgradeCompleted New-AzureRmPublicIp...
14    compute-create-dockerhost.ps1:18:9                         Cmdlet          UpgradeCompleted New-AzureRmVirtualN...
15    compute-create-dockerhost.ps1:15:17                        Cmdlet          UpgradeCompleted New-AzureRmVirtualN...
16    compute-create-dockerhost.ps1:12:1                         Cmdlet          UpgradeCompleted New-AzureRmResource...
17    compute-create-windowsvm-quick.ps1:18:3                    CmdletParameter UpgradeCompleted ImageName
18    compute-create-windowsvm-quick.ps1:14:1                    Cmdlet          UpgradeCompleted New-AzureRmVM
19    compute-create-windowsvm-quick.ps1:11:1                    Cmdlet          UpgradeCompleted New-AzureRmResource...
20    compute-create-wordpress-mysql.ps1:59:24                   CmdletParameter UpgradeCompleted ExtensionName
...

Si des erreurs sont retournées, vous pouvez les examiner de plus près à l’aide de la commande suivante :

# Filter results to show only errors
$Results | Where-Object UpgradeResult -ne UpgradeCompleted | Format-List

Order                  : 42
UpgradeType            : CmdletParameter
UpgradeResult          : UnableToUpgrade
UpgradeSeverity        : Error
UpgradeResultReason    : Parameter was not found in Get-AzResource or it's aliases.
SourceCommand          : CommandReference
SourceCommandParameter : CommandReferenceParameter
Location               : devtestlab-add-marketplace-image-to-lab.ps1:14:74
FullPath               : C:\Scripts\devtestlab-add-marketplace-image-to-lab.ps1
StartOffset            : 556
Original               : ResourceNameEquals
Replacement            :

Limites

Les opérations d’E/S de fichier utilisent l’encodage par défaut. Les situations inhabituelles d’encodage de fichier peuvent entraîner des problèmes.
Les applets de commande AzureRM qui sont passées comme des arguments aux instructions fictives de test unitaire Pester ne seront pas détectées.

Comment signaler des problèmes

Vous pouvez nous envoyer vos commentaires et nous signaler des problèmes au sujet du module PowerShell Az.Tools.Migration en créant un problème GitHub dans le dépôt azure-powershell-migration.

Étapes suivantes

Pour plus d’informations sur le module Az PowerShell, consultez la Documentation Azure PowerShell.