Automatisches Migrieren von PowerShell-Skripts von AzureRM zum Az PowerShell-Modul

Artikel
11/07/2024

In diesem Artikel erfahren Sie, wie Sie das PowerShell-Modul „Az.Tools.Migration“ verwenden, um Ihre PowerShell-Skripts und Skriptmodule automatisch von AzureRM auf das Az PowerShell-Modul zu aktualisieren. Weitere Migrationsoptionen finden Sie unter Migrieren von Azure PowerShell von AzureRM zum Az-Modul.

Warnung

Das AzureRM PowerShell-Modul ist seit dem 29. Februar 2024 offiziell veraltet. Benutzern wird empfohlen, von AzureRM zum Az PowerShell-Modul zu migrieren, um weiterhin Support und Updates zu erhalten.

Obwohl das AzureRM-Modul möglicherweise weiterhin funktioniert, wird es nicht mehr gewartet, und es wird kein Support mehr angeboten. Die weitere Nutzung erfolgt daher nach Ermessen und Risiko des Benutzers. Weitere Informationen zum Übergang zum Az-Modul finden Sie in unseren Migrationsressourcen.

Anforderungen

Aktualisieren Sie Ihre vorhandenen PowerShell-Skripts auf die aktuelle Version des AzureRM PowerShell-Moduls (6.13.1).
Installieren Sie das PowerShell-Modul „Az.Tools.Migration“.
```
Install-Module -Name Az.Tools.Migration
```

Schritt 1: Generieren eines Upgradeplans

Verwenden Sie das Cmdlet New-AzUpgradeModulePlan, um einen Upgradeplan für die Migration Ihrer Skripts und Module zum Az PowerShell-Modul zu generieren. Dieses Cmdlet nimmt keine Änderungen an Ihren vorhandenen Skripts vor. Verwenden Sie den Parameter FilePath für ein bestimmtes Skript oder den Parameter DirectoryPath für alle Skripts in einem bestimmten Ordner.

Hinweis

Durch das Cmdlet New-AzUpgradeModulePlan wird der Plan nicht ausgeführt. Es werden lediglich die Upgradeschritte generiert.

Im folgenden Beispiel wird ein Plan für alle Skripts im Ordner C:\Scripts generiert. Der Parameter OutVariable wird angegeben, sodass die Ergebnisse zurückgegeben und gleichzeitig in einer Variablen mit dem Namen Plan gespeichert werden.

# 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 latest -DirectoryPath 'C:\Scripts' -OutVariable Plan

Wie in der folgenden Ausgabe gezeigt, enthält der Upgradeplan die spezifische Datei sowie die Punkte, die Änderungen erfordern, wenn Sie von AzureRM auf die Az PowerShell-Cmdlets umstellen.

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
...

Vor der Durchführung des Upgrades müssen Sie die Ergebnisse des Plans auf Probleme überprüfen. Im folgenden Beispiel wird eine Liste der Skripts und der Elemente in diesen Skripts zurückgegeben, die das automatische Upgrade verhindern.

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

Für die in der folgenden Ausgabe angezeigten Elemente wird erst dann ein automatisches Upgrade durchgeführt, wenn die Probleme manuell behoben wurden.

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            :

Schritt 2: Durchführen des Upgrades

Achtung

Der Vorgang kann nicht rückgängig gemacht werden. Achten Sie immer darauf, dass Sie über eine Sicherungskopie der PowerShell-Skripts und -Module verfügen, für die Sie ein Upgrade durchführen möchten.

Wenn Sie mit dem Plan zufrieden sind, wird das Upgrade mit dem Cmdlet Invoke-AzUpgradeModulePlan durchgeführt. Geben Sie SaveChangesToNewFiles für den Parameterwert FileEditMode an, um zu verhindern, dass Änderungen an den ursprünglichen Skripts vorgenommen werden. Bei Verwendung dieses Modus wird das Upgrade durchgeführt, indem eine Kopie jedes Skripts erstellt und an die Dateinamen jeweils _az_upgraded angefügt wird.

Warnung

Bei Angabe der Option -FileEditMode ModifyExistingFiles ist das Cmdlet Invoke-AzUpgradeModulePlan destruktiv. Ihre Skripts und Funktionen werden in diesem Fall direkt gemäß dem Modulupgradeplan geändert, der durch das Cmdlet New-AzUpgradeModulePlan generiert wurde. Alternativ können Sie die nicht destruktive Option -FileEditMode SaveChangesToNewFiles angeben.

# 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
...

Sollten Fehler zurückgegeben werden, können Sie sich die Fehlerergebnisse mithilfe des folgenden Befehls genauer ansehen:

# 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            :

Einschränkungen

Bei Datei-E/A-Vorgängen wird die Standardcodierung verwendet. Ungewöhnliche Dateicodierungen können zu Problemen führen.
AzureRM-Cmdlets, die als Argumente an simulierte Anweisungen für Pester-Komponententests übergeben werden, werden nicht erkannt.

Melden von Problemen

Wenn Sie Feedback geben oder Probleme im Zusammenhang mit dem PowerShell-Modul „Az.Tools.Migration“ melden möchten, können Sie ein GitHub-Problem im Repository azure-powershell-migration erstellen.

Nächste Schritte

Weitere Informationen zum Az PowerShell-Modul finden Sie in der Azure PowerShell-Dokumentation.

Freigeben über