Migrieren von Azure PowerShell von AzureRM zum Az-ModulMigrate Azure PowerShell from AzureRM to Az

Das Az-Modul bietet die gleichen Features wie AzureRM, verwendet aber kürzere und konsistentere Cmdlet-Namen.The Az module has feature parity with AzureRM, but uses shorter and more consistent cmdlet names. Für die AzureRM-Cmdlets geschriebene Skripts funktionieren nicht automatisch auch mit dem neuen Modul.Scripts written for the AzureRM cmdlets won't automatically work with the new module. Zur Vereinfachung des Übergangs bietet Az Tools, die es Ihnen ermöglichen, Ihre bereits vorhandenen Skripts mit AzureRM auszuführen.To make the transition easier, Az offers tools to allow you to run your existing scripts using AzureRM. Eine Migration zu einem neuen Befehlssatz ist immer unangenehm. Dieser Artikel hilft Ihnen jedoch dabei, den Umstieg auf das neue Modul in die Wege zu leiten.No migration to a new command set is ever convenient, but this article will help you get started on transitioning to the new module.

Die vollständige Liste mit grundlegenden Änderungen zwischen AzureRM und Az finden Sie unter Vollständige Änderungen von AzureRM zu Az.To see the full list of breaking changes between AzureRM and Az, see the full changes from AzureRM to Az.

Vergewissern, dass vorhandene Skripts mit der neuesten AzureRM-Version funktionierenEnsure existing scripts work with the latest AzureRM release

Überprüfen Sie, welche Versionen von AzureRM auf Ihrem System installiert sind, bevor Sie Migrationsschritte ausführen.Before taking any migration steps, check which versions of AzureRM are installed on your system. So können Sie sicherstellen, dass für Skripts bereits das aktuelle Release verwendet wird, und Sie können ermitteln, welche Versionen von AzureRM deinstalliert werden müssen.Doing so allows you to make sure scripts are already running on the latest release, and let you know which versions of AzureRM must be uninstalled.

Führen Sie den folgenden Befehl aus, um zu überprüfen, welche Versionen von AzureRM bei Ihnen installiert sind:To check which version(s) of AzureRM you have installed, run the command:

Get-InstalledModule -Name AzureRM -AllVersions

Die aktuellste verfügbare Version von AzureRM ist 6.13.1.The latest available release of AzureRM is 6.13.1. Wenn diese Version nicht installiert ist, müssen Ihre vorhandenen Skripts möglicherweise zusätzlich geändert werden, um mit dem Az-Modul über das hinaus zu arbeiten, was hier und in der Breaking Changes-Liste beschrieben ist.If you don't have this version installed, your existing scripts may need additional modification to work with the Az module beyond what's described here and in the breaking changes list.

Wenn Ihre Skripts nicht mit AzureRM 6.13.1 funktionieren, aktualisieren Sie sie gemäß dem Leitfaden zur Migration von AzureRM 5.x zu 6.x.If your scripts don't work with AzureRM 6.13.1, update them according to the AzureRM 5.x to 6.x migration guide. Wenn Sie eine frühere Version des AzureRM-Moduls verwenden, gibt es für jede Hauptversion Migrationsleitfäden.If you use an earlier version of the AzureRM module, there are migration guides available for each major version.

Deinstallieren von AzureRMUninstall AzureRM

Es wird nicht garantiert, dass das Az-Modul mit allen bestehenden AzureRM-Installationen in PowerShell 5.1 für Windows kompatibel ist.The Az module is not guaranteed to be compatible with any existing AzureRM installs in PowerShell 5.1 for Windows. Bevor Sie das Az-Modul installieren, deinstallieren Sie AzureRM.Before you install the Az module, uninstall AzureRM.

Wichtig

Wenn Sie nicht bereit sind, das AzureRM-Modul aus Ihrem System zu entfernen, können Sie stattdessen das Az-Modul für PowerShell Core 6.x oder höher installieren.If you're not ready to remove the AzureRM module from your system, you can install the Az module for PowerShell Core 6.x or later instead. PowerShell Core und PowerShell 5.1 für Windows verwenden unterschiedliche Modulbibliotheken, sodass keine Konflikte auftreten.PowerShell Core and PowerShell 5.1 for Windows use different module libraries, so there will be no conflicts. Sie können in PowerShell Core weiterhin Aliase aktivieren.You can still enable aliases in PowerShell Core.

Installieren des Az-Moduls von Azure PowerShellInstall the Azure PowerShell Az module

Der erste Schritt besteht darin, das Az-Modul auf Ihrer Plattform zu installieren.The first step is to install the Az module on your platform. Wenn Sie Az installieren, ist es ratsam, AzureRM zu deinstallieren.When you install Az, it's recommended that you uninstall AzureRM. In den folgenden Schritten erfahren Sie, wie Sie Ihre bereits vorhandenen Skripts weiterhin ausführen und die Kompatibilität mit älteren Cmdlet-Namen sicherstellen können.In the following steps, you'll learn how to keep running your existing scripts and enable compatibility for old cmdlet names.

Befolgen Sie zur Installation des Az-Moduls von Azure PowerShell die Anweisungen unter Installieren des Az-Moduls.To install the Azure PowerShell Az module, follow the instructions in Install the Az module.

Hinweis

An dieser Stelle sollten Sie vielleicht das im Az-Modul bereitgestellte Cmdlet Uninstall-AzureRM ausführen, nur um sicherzustellen, dass alle Versionen von AzureRM deinstalliert wurden und somit keine Konflikte verursachen.At this point, you might want to run the Uninstall-AzureRM cmdlet provided in the Az module, just to make sure that all versions of AzureRM have been uninstalled and won't cause conflicts.

Aktivieren von AzureRM-KompatibilitätsaliasenEnable AzureRM compatibility aliases

Wenn Sie AzureRM deinstalliert haben und Ihre Skripts mit der neuesten Version von AzureRM funktionieren, ist der nächste Schritt das Aktivieren des Kompatibilitätsmodus für das Az-Modul.With AzureRM uninstalled and your scripts working with the latest AzureRM version, the next step is to enable the compatibility mode for the Az module. Die Kompatibilität wird mithilfe des folgenden Befehls aktiviert:Compatibility is enabled with the command:

Enable-AzureRmAlias -Scope CurrentUser

Aliase ermöglichen die Verwendung alter Cmdlet-Namen bei installiertem Az-Modul.Aliases enable the ability to use old cmdlet names with the Az module installed. Diese Aliase werden in das Profil für den ausgewählten Bereich geschrieben.These aliases are written to the profile for the selected scope. Sollte kein Profil vorhanden sein, wird eines erstellt.If no profile exists, one is created. Wenn Sie einen -Scope verwenden, der umfangreicher als CurrentUser ist, sind die entsprechenden Berechtigungen erforderlich, um die entsprechende Profildatei zu erstellen oder zu aktualisieren.When using a -Scope broader than CurrentUser, the appropriate permissions are required to create or update the corresponding profile file.

Wichtig

Nur Cmdlet-Namen werden mit einem Alias versehen – dies gilt nicht für Modulnamen!Only cmdlet names are aliased - module names aren't! Wenn Sie #Requires, Import-Module, Abhängigkeitslisten in einer .psd1 oder vollqualifizierte Cmdlet-Namen verwenden, stellen Sie sicher, dass Sie diese an dieser Stelle migrieren, indem Sie dem in der Breaking Changes-Liste zu Modulnamen beschriebenen Prozess folgen.If you're using #Requires, Import-Module, dependency lists in a .psd1, or fully-qualified cmdlet names, make sure that you migrate them at this point by following the process outlined in the breaking changes list regarding module names.

Warnung

Sie können für diesen Befehl zwar einen anderen Bereich (-Scope) verwenden, aber dies wird nicht empfohlen.You can use a different -Scope for this command, but it's not recommended. Da Aliase in das Benutzerprofil für den ausgewählten Bereich geschrieben werden, empfiehlt es sich, sie auf einen möglichst kleinen Bereich zu beschränken.Aliases are written to the user profile for the selected scope, so keep enabling them to as limited a scope as possible. Eine systemweite Aktivierung von Aliasen kann zu Problemen für andere Benutzer führen, die AzureRM in ihrem lokalen Bereich installiert haben.Enabling aliases system-wide can cause issues for other users who have AzureRM installed in their local scope.

Führen Sie Ihre Skripts nach der Aktivierung des Aliasmodus erneut aus, um sich zu vergewissern, dass sie weiterhin wie erwartet funktionieren.Once the alias mode is enabled, run your scripts again to confirm that they still function as expected. Einige Parameternamen wurden geändert, hinzugefügt oder für das Az-Modul vorgeschrieben.Some parameter names have been changed, added, or made required by the Az module. Die Ausgabetypen von Cmdlets wurden möglicherweise ebenfalls geändert.Output types of cmdlets may have changed as well. Diese Änderungen werden in der Breaking Changes-Liste beschrieben.These changes are detailed in the breaking changes list.

Aktualisieren von Cmdlets, Modulen und ParameternUpdate cmdlets, modules, and parameters

Wenn Skripts aktualisiert wurden und mit Aliasen ausgeführt werden, können Sie sich die Zeit nehmen, sie zu aktualisieren, um die neuen Cmdlets zu verwenden und andere Änderungen zu nutzen, z. B. neue Features.With scripts updated and running under aliases, you can take your time to update them to use the new cmdlets and take advantage of other changes like new features. Für die meisten Skripts müssen Sie nur die Cmdlet-Namen gemäß dem neuen Cmdlet-Namensschema in Az aktualisieren.For most scripts, you will only need to update cmdlet names, following the new cmdlet naming scheme in Az. Es gibt möglicherweise auch einige andere vorzunehmende Änderungen, damit die Skripts gemäß ihrer Aufgabe und der verwendeten Azure PowerShell-Features funktionieren.There may also be some other changes that you need to make in order to have your scripts work, depending on what they do and which Azure PowerShell features they take advantage of.

So wurden z. B. die Blob Storage-Cmdlets vollständig überarbeitet, um ein neues asynchrones Modell zu verwenden, sodass die Skripts, die diese Cmdlets verwenden, einen höheren Aufwand für die Aktualisierung erfordern als solche, bei denen die einzigen relevanten Änderungen die Cmdlet-Namen darstellen.For example, the Blob Storage cmdlets have been completely reworked to use a new asynchronous model, so scripts using them will take more work to update than those where the only relevant changes were cmdlet names.

Auch wenn Sie bis zu diesem Zeitpunkt nur kleine, einfache Änderungen an Ihren Skripts vornehmen mussten – oder sie sogar ohne zusätzliche Änderungen funktionieren, wenn Aliase aktiviert sind – lesen Sie die vollständige Liste der Breaking Changes in Az 1.0.0, um sicherzustellen, dass Sie sich nicht auf ein „transparentes“ Verhalten der Aliase verlassen, das verschwinden könnte, nachdem Sie Cmdlet-Namen geändert und Aliase deaktiviert haben.Even if you've only had to make small, simple changes to your scripts up to this point - or they even work without additional modification when aliases are enabled - read the full list of breaking changes in Az 1.0.0 to make sure that you're not relying on 'transparent' behavior of aliases which could disappear after you change cmdlet names and disable aliases.

Deaktivieren von AliasenDisable aliases

Sobald Sie die Migration abgeschlossen haben und nicht mehr auf das Aliasverhalten angewiesen sind, wird empfohlen, Aliase zu deaktivieren.Once you've completed your migration and are no longer relying on aliasing behavior, it's recommended that you disable aliases. Dies erfolgt mit dem Cmdlet Disable-AzureRmAlias.This is done with the Disable-AzureRmAlias cmdlet.

Wichtig

Wenn Sie dieses Cmdlet ausführen, stellen Sie sicher, dass Sie es für jeden -Scope aufrufen, für den Enable-AzureRmAlias aufgerufen wurde, ansonsten kann es auf Ihrem System noch Skripts geben, die sich auf das Aliasverhalten verlassen.When running this cmdlet, make sure that you invoke it for each -Scope that Enable-AzureRmAlias was invoked for, otherwise there may still be scripts on your system relying on the aliasing behavior.