Installieren von PowerShell Az- und Azure Stack-Modulen für Azure Stack Hub

Azure Stack Hub-Version	AzureStack PowerShell-Version
2102	2.1.1
2108	2.2.0
2206	2.3.0
2301+	2.4.0

Weitere Informationen zu AzureStack-Modulen finden Sie unter PSGallery.

In diesem Artikel wird erläutert, wie Sie mithilfe von PowerShellGet das Azure PowerShell Az-Modul und kompatible Azure Stack Hub-Administratormodule installieren. Die Az-Module können auf Windows-, macOS- und Linux-Plattformen installiert werden.

Sie können die Az-Module für Azure Stack Hub auch in einem Docker-Container ausführen. Anleitungen finden Sie unter Verwenden von Docker zum Ausführen von PowerShell für Azure Stack Hub.

Wenn Sie das PowerShell Resource Modules-Modul (AzureRM-Modul) für Azure Stack Hub installieren möchten, lesen Sie die Informationen unter Installieren des PowerShell AzureRM-Moduls für Azure Stack Hub.

Wichtig

Es werden keine neuen Modulreleases für Azure-Ressourcenmodule verfügbar sein. Für die Azure Resource Modules-Module wird nur noch Support für kritische Hotfixes bereitgestellt. In Zukunft gibt es nur noch Az-Releases für Azure Stack Hub.

Sie können API-Profile verwenden, um die kompatiblen Endpunkte für die Azure Stack Hub-Ressourcenanbieter anzugeben.

API-Profile bieten eine Möglichkeit, Versionsunterschiede zwischen Azure und Azure Stack Hub zu verwalten. Ein API-Versionsprofil ist eine Gruppe von Azure Resource Manager-PowerShell-Modulen mit spezifischen API-Versionen. Jede Cloudplattform verfügt über eine Gruppe von unterstützten API-Versionsprofilen. Azure Stack Hub unterstützt beispielsweise eine bestimmte Profilversion, z. B. 2020-09-01-hybrid. Wenn Sie ein Profil installieren, werden die Azure Resource Manager-PowerShell-Module installiert, die dem angegebenen Profil entsprechen.

Sie können mit Azure Stack Hub kompatible PowerShell Az-Module in einem Szenario mit Internetverbindung, mit teilweiser Internetverbindung oder ohne Internetverbindung installieren. Dieser Artikel leitet Sie durch die detaillierten Anweisungen für diese Szenarien.

1. Überprüfen der Voraussetzungen

AZ-Module werden in Azure Stack Hub mit Update 2002 oder höher unterstützt, wenn die aktuellen Hotfixes installiert sind. Weitere Informationen finden Sie in den Versionshinweisen zu Azure Stack Hub.

Die Azure PowerShell-Az-Module können mit PowerShell 5.1 oder höher unter Windows oder mit PowerShell Core 6.x und höher auf allen Plattformen verwendet werden. Sie sollten die letzte Version von PowerShell Core installieren, die für Ihr Betriebssystem verfügbar ist. Bei der Ausführung in PowerShell Core gibt es keine anderen Anforderungen an Azure PowerShell.

Führen Sie den Befehl aus, um Ihre PowerShell-Version zu überprüfen:

$PSVersionTable.PSVersion

Voraussetzungen für Windows

So verwenden Sie Azure PowerShell in PowerShell 5.1 unter Windows:

1. Führen Sie bei Bedarf ein Update auf Windows PowerShell 5.1 aus. Unter Windows 10 ist PowerShell 5.1 bereits installiert.

2. Installieren Sie .NET Framework 4.7.2 oder höher.

3. Vergewissern Sie sich, dass die aktuelle Version von PowerShellGet installiert ist. Führen Sie die folgenden Cmdlets in einer Eingabeaufforderung mit erhöhten Rechten aus:

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   
   powershell -noprofile
   $PSVersionTable
   Uninstall-Module PowershellGet -AllVersions -Force -Confirm:$false
   Get-module PowershellGet
   Find-module PowershellGet
   Install-Module PowershellGet -MinimumVersion 2.2.3 -Force
   

2. Voraussetzungen für Linux und Mac

Mindestens PowerShell Core 6.x erforderlich. Anweisungen finden Sie unter diesem Link.

3. Deinstallieren vorhandener Versionen der Azure Stack Hub-PowerShell-Module

Deinstallieren Sie vor der Installation der erforderlichen Version unbedingt alle zuvor installierten Azure Resource Manager- oder Az-PowerShell-Module für Azure Stack Hub. Deinstallieren Sie die Module mit einer der folgenden zwei Methoden:

1. Schließen Sie alle aktiven PowerShell-Sitzungen, und führen Sie die folgenden Cmdlets aus, um die vorhandenen Azure Resource Manager- und Az PowerShell-Module zu deinstallieren:

   Get-Module -Name Azure* -ListAvailable | Uninstall-Module -Force -Verbose -ErrorAction Continue
   Get-Module -Name Azs.* -ListAvailable | Uninstall-Module -Force -Verbose -ErrorAction Continue
   Get-Module -Name Az.* -ListAvailable | Uninstall-Module -Force -Verbose -ErrorAction Continue
   

   Wenn eine Fehlermeldung wie „Das Modul wird bereits verwendet“ auftritt, schließen Sie die PowerShell-Sitzungen, die die Module verwenden, und führen Sie das obige Skript erneut aus.

2. Wenn Uninstall-Module nicht erfolgreich war, löschen Sie alle Ordner, die mit Azure, Az oder Azs. beginnen, aus den $env:PSModulePath-Speicherorten. Für Windows PowerShell können die Speicherorte C:\Program Files\WindowsPowerShell\Modules und C:\Users\{yourusername}\Documents\WindowsPowerShell\Modules verwendet werden. Für PowerShell Core können die Speicherorte C:\Program Files\PowerShell\7\Modules und C:\Users\{yourusername}\Documents\PowerShell\Modules verwendet werden. Durch Löschen dieser Ordner werden alle vorhandenen Azure PowerShell-Module entfernt.

4. Verbunden: Installieren mit Internetverbindung

Das Azure Stack Az-Modul kann auf einem Windows-Computer mit PowerShell 5.1 oder höher oder auf einer Linux- bzw. macOS-Plattform mit PowerShell 6.x oder höher verwendet werden. Die Verwendung der PowerShellGet-Cmdlets ist die bevorzugte Installationsmethode. Die Funktionsweise dieser Methode ist auf den unterstützten Plattformen gleich.

1. Führen Sie den folgenden Befehl in einer PowerShell-Sitzung aus, um PowerShellGet mindestens auf Version 2.2.3 zu aktualisieren

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   Install-Module PowerShellGet -MinimumVersion 2.2.3 -Force
   

2. Schließen Sie die PowerShell-Sitzung, und öffnen Sie eine neue PowerShell-Sitzung, damit das Update wirksam werden kann.

3. Führen Sie folgendes aus, um Az-Module zu installieren.

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   Install-Module -Name Az.BootStrapper -Force
   Install-AzProfile -Profile 2020-09-01-hybrid -Force
   

4. Installieren Sie AzureStack PowerShell-Module.

   Install-Module -Name AzureStack -RequiredVersion 2.4.0
   

Warnung

Die Module Azure Resource Manager (AzureRM) und Az können für PowerShell 5.1 für Windows nicht gleichzeitig installiert sein. Wenn Azure Resource Manager weiterhin auf Ihrem System verfügbar sein soll, installieren Sie das Az-Modul für PowerShell Core 6.x oder höher. Installieren Sie dazu PowerShell Core 6.x oder höher, und befolgen Sie dann diese Anweisungen in einem PowerShell Core-Terminal.

5. Nicht verbunden: Installieren ohne Internetverbindung

In einem Szenario ohne Internetverbindung müssen Sie zuerst die PowerShell-Module auf einen Computer mit Internetverbindung herunterladen. Anschließend übertragen Sie sie für den Installationsvorgang in das Azure Stack Development Kit (ASDK).

Melden Sie sich bei einem Computer mit Internetverbindung an, und verwenden Sie die folgenden Skripts, um die Pakete „Azure Resource Manager“ und „Azure Stack Hub“ abhängig von Ihrer Version von Azure Stack Hub herunterzuladen.

Die Installation umfasst fünf Schritte:

1. Installieren von Azure Stack Hub-PowerShell auf einem verbundenen Computer.
2. Aktivieren zusätzlicher Speicherfunktionen
3. Übertragen der PowerShell-Pakete auf Ihre getrennte Arbeitsstation
4. Manuelles Bootstrapping des NuGet-Anbieters auf Ihrer getrennten Arbeitsstation
5. Bestätigen der Installation von PowerShell

Installieren von Azure Stack Hub PowerShell

1. Sie können entweder AzureRM - oder Az-Module verwenden. Mit dem folgenden Code werden Az-Module aus einem vertrauenswürdigen Onlinerepository https://www.powershellgallery.com/gespeichert.

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   Install-module -Name PowerShellGet -MinimumVersion 2.2.3 -Force
   Import-Module -Name PackageManagement -ErrorAction Stop
   $savedModulesPath = "<Path that is used to save the packages>"
   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name Az -Path $savedModulesPath -Force -RequiredVersion 2.0.1
   

2. Nachdem die Az-Module installiert wurden, fahren Sie mit der Installation der AzureStack-Module fort.

   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $savedModulesPath -Force -RequiredVersion 2.4.0
   

Hinweis

Für Computer ohne Internetverbindung empfiehlt es sich, das folgende Cmdlet auszuführen, um das Sammeln von Telemetriedaten zu deaktivieren. Andernfalls kommt es bei den Cmdlets unter Umständen zu einer Leistungsbeeinträchtigung, wenn die Telemetriedatensammlung nicht deaktiviert wird. Dies betrifft nur Computer ohne Internetverbindung.

Disable-AzDataCollection

Hinzufügen Ihrer Paketen auf Ihrer Arbeitsstation

1. Kopieren Sie die heruntergeladenen Pakete auf ein USB-Gerät.

2. Melden Sie sich bei der getrennten Arbeitsstation an, und kopieren Sie die Pakete vom USB-Gerät an einen Speicherort auf der Arbeitsstation.

3. Manuelles Bootstrapping des NuGet-Anbieters auf Ihrer getrennten Arbeitsstation Anweisungen finden Sie unter Manuelles Bootstrapping des NuGet-Anbieters auf einem Computer, der nicht mit dem Internet verbunden ist.

4. Registrieren Sie diesen Speicherort als Standardrepository, und installieren Sie die Module AzureRM und AzureStack aus diesem Repository:

    # requires -Version 5
    # requires -RunAsAdministrator
    # requires -Module PowerShellGet
    # requires -Module PackageManagement
   
    $SourceLocation = "<Location on the development kit that contains the PowerShell packages>"
    $RepoName = "MyNuGetSource"
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    Register-PSRepository -Name $RepoName -SourceLocation $SourceLocation -InstallationPolicy Trusted
   

5. Installieren Sie die Az-Module.

    Install-Module -Name Az -Repository $RepoName -RequiredVersion 2.0.1 -Scope AllUsers
   

6. Installieren Sie die AzureStack-Module.

   Install-Module -Name AzureStack -Repository $RepoName -RequiredVersion 2.4.0 -Scope AllUsers
   

Bestätigen der Installation der PowerShell

Führen Sie den folgenden Befehl aus, um die Installation zu überprüfen:

Get-Module -Name "Az*" -ListAvailable
Get-Module -Name "Azs*" -ListAvailable

6. Konfigurieren von PowerShell für die Verwendung eines Proxyservers

In Szenarien, für die ein Proxyserver für den Zugriff auf das Internet erforderlich ist, konfigurieren Sie zuerst PowerShell für die Verwendung eines vorhandenen Proxyservers:

1. Öffnen Sie eine PowerShell-Eingabeaufforderung mit erhöhten Rechten.

2. Führen Sie die folgenden Befehle aus:

   #To use Windows credentials for proxy authentication
   [System.Net.WebRequest]::DefaultWebProxy.Credentials = [System.Net.CredentialCache]::DefaultCredentials
   
   #Alternatively, to prompt for separate credentials that can be used for #proxy authentication
   [System.Net.WebRequest]::DefaultWebProxy.Credentials = Get-Credential
   

7. Verwenden des Az-Moduls

Sie können die Cmdlets und Codebeispiele basierend auf AzureRM-Modulen verwenden. Allerdings sollten Sie den Namen der Module und Cmdlets ändern. Die Modulnamen haben sich geändert, sodass AzureRM und Azure zu Az werden. Gleiches gilt für die Cmdlets. So wurde beispielsweise das Modul AzureRM.Compute in Az.Compute umbenannt. New-AzureRMVM wurde zu New-AzVM, und Get-AzureStorageBlob ist jetzt Get-AzStorageBlob.

Eine ausführlichere Erläuterung und Anleitungen zum Verschieben eines AzureRM-Skripts in Az sowie Informationen zu Breaking Changes im Az-Modul von Azure Stack Hub finden Sie unter Migrieren von AzureRM zum Az-Modul von Azure PowerShell.

Bekannte Probleme

Fehler bei der Installation der Az-Module

• Geltungsbereich: Dieses Problem betrifft das Release 2002 und höhere Releases
• Ursache: Bei der Installation des Moduls wird ein Fehler ausgelöst. Die Fehlermeldung beginnt wie folgt: Register-PacakgeSource : A parameter cannot be found that matches parameter name. 'PackageManagementProvider'. Oder die Fehlermeldung enthält den folgenden Text: PackageManagement\Install-Package : Cannot convert value "2.0.1-preview" to type "System.Version". Error: "Input string was not in a correct format."
• Abhilfe: Führen Sie das folgende Cmdlet in der gleichen Sitzung aus:
  Install-Module PowershellGet -MinimumVersion 2.3.0 -Force
  Schließen Sie die Sitzung, und starten Sie eine neue PowerShell-Sitzung mit erhöhten Rechten.
• Häufigkeit: Allgemein

Bei der Installation des Az-Moduls wird fälschlicherweise ein Fehler vom Typ „Administratorrechte erforderlich“ ausgelöst

• Geltungsbereich: Dieses Problem betrifft das Release 2002 und höhere Releases
• Ursache: Wenn Sie das Modul über eine Eingabeaufforderung mit erhöhten Rechten installieren, wird ein Fehler ausgelöst. Der Fehler lautet Administrator rights required.
• Abhilfe: Schließen Sie die Sitzung, und starten Sie eine neue PowerShell-Sitzung mit erhöhten Rechten. Stellen Sie sicher, dass Az nicht bereits vorhanden ist. Das Kontomodul wurde in die Sitzung geladen.
• Häufigkeit: Allgemein

Cmdlet New-AzVmss schlägt fehl, wenn das Profil „2020-09-01-hybrid“ verwendet wird

• Geltungsbereich: Dieses Problem gilt für das Profil 2020-09-01-hybrid.
• Ursache: Das Cmdlet New-AzVmss funktioniert nicht mit dem Profil „2020-09-01-hybrid“.
• Problembehebung: Verwenden Sie eine Vorlage zum Erstellen einer VM-Skalierung gruppe. Ein Beispiel für die Azure Stack Hub Resource Manager-Vorlagen finden Sie im GitHub-Repository AzureStack-QuickStart-Templates/101-vmss-windows-vm, ebenso wie Anweisungen zur Verwendung von Azure Stack Hub Resource Manager mit Visual Studio Code.
• Häufigkeit: Allgemein

Fehler beim Ausführen eines PowerShell-Skripts ausgelöst

• Geltungsbereich: Dieses Problem betrifft das Release 2002 und höhere Releases.

• Ursache: Wenn Sie Skripts oder PowerShell-Befehle mithilfe der spezifischen Azure Stack Hub-Module ausführen, muss Ihr Skript oder Befehl im Modul verfügbar sein. Es wird möglicherweise der folgende Fehler angezeigt:

  Method 'get_SerializationSettings' in type 'Microsoft.Azure.Management.Internal.Resources.ResourceManagementClient' from assembly 'Microsoft.Azure.Commands.ResourceManager.Common, Version=4.0.0.0, 
  Culture=neutral, PublicKeyToken=31bf3856ad364e35' does not have an implementation.
  

  Das aktuelle Modul ist das PowerShell Az-Modul, das das PowerShell AzureRM-Modul ersetzt hat. Wenn Sie versuchen, ein Skript auszuführen, das AzureRM-Befehle aufruft, obwohl das Az-Modul installiert ist, löst Ihr Skript Fehler aus. Wenn Sie versuchen, ein Skript auszuführen, das Az-Befehle aufruft, obwohl das AzureRM-Modul installiert ist, löst Ihr Skript Fehler aus.

• Abhilfe: Deinstallieren Sie das AzureRM-Modul, und installieren Sie das Az-Modul. Anleitungen finden Sie unter Installieren des PowerShell Az-Moduls für Azure Stack Hub. Wenn Sie die Azure Stack Hub-Tools verwenden, nutzen Sie die Az-Tools. Klonen Sie das Repository „Tools“ aus dem Branch az, oder laden Sie AzureStack-Tools aus dem Branch az herunter. Anweisungen dazu finden Sie unter Herunterladen von Azure Stack Hub-Tools aus GitHub.

• Häufigkeit: Allgemein

Fehler bei New-AzADServicePrincipal und New-AzADApplication

• Anwendbar: Azure Stack-Umgebungen mit Microsoft Entra ID.

• Ursache: Azure Active Directory Graph hat einen Breaking Change eingeführt, um IdentifierUri für Active Directory-Anwendungen auf die Unterdomänen einer überprüften Domäne im Verzeichnis zu beschränken. Vor der Änderung wurde diese Einschränkung nur für mehrinstanzenfähige Apps erzwungen. Diese Einschränkung gilt jetzt auch für Einzelmandanten-Apps. Die Änderung führt zu folgendem Fehler: Values of identifierUris property must use a verified domain of the organization or its subdomain' is displayed when running.

• Abhilfe: Sie haben zwei Möglichkeiten, um diese Einschränkung zu umgehen.

  • Sie müssen einen Dienstprinzipalnamen verwenden, der eine Unterdomäne des Verzeichnismandanten ist. Wenn das Verzeichnis beispielsweise contoso.onmicrosoft.com ist, muss der Dienstprinzipalname die Form <foo>.contoso.onmicrosoft.com aufweisen. Verwenden Sie das folgende Cmdlet:

    New-AzADServicePrincipal -Role Owner -DisplayName <foo>.contoso.onmicrosoft.com
    

    Weitere Informationen zur Identität und zur Verwendung von Dienstprinzipalen mit Azure Stack Hub finden Sie in der Übersicht über Identitätsanbieter für Azure Stack Hub.

  • Erstellen Sie die Microsoft Entra-App, die eine gültige IdentifierUri app bereitstellt, und erstellen Sie dann den Dienstprinzipal, der der App zugeordnet wird, mithilfe des folgenden Cmdlets:

    $app=New-AzADApplication -DisplayName 'newapp' -IdentifierUris http://anything.contoso.onmicrosoft.com
    New-AzADServicePrincipal -Role Owner -ApplicationId $app.ApplicationId
    

• Häufigkeit: Allgemein

Fehler: „SharedTokenCacheCredential-Authentifizierungsfehler“

• Geltungsbereich: Dieses Problem gilt für alle unterstützten Versionen.
• Ursache: Der Fehler SharedTokenCacheCredential-Authentifizierungsfehler wird ausgelöst, wenn mehrere Versionen von AzAccounts zusammen mit dem Azure Stack Hub PowerShell-Modul, Version 2.1.1, installiert sind.
• Abhilfe: Entfernen Sie alle Versionen von AzAccounts, und installieren Sie nur die unterstützte Version 2.2.8 von AzAccounts.
• Häufigkeit: Allgemein

Nächste Schritte

• Herunterladen von Azure Stack Hub-Tools aus GitHub
• Konfigurieren der PowerShell-Umgebung des Azure Stack Hub-Benutzers
• Konfigurieren der PowerShell-Umgebung des Azure Stack Hub-Operators
• Verwalten von API-Versionsprofilen in Azure Stack Hub