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

Von Bedeutung

Alle Versionen des Azure Resource Manager (AzureRM)-PowerShell-Moduls sind veraltet und werden nicht unterstützt. Das Az PowerShell-Modul ist jetzt das empfohlene PowerShell-Modul für die Interaktion mit Azure und Azure Stack Hub. In diesem Artikel wird beschrieben, wie Sie mit dem Az PowerShell-Modul beginnen. Informationen zum Migrieren zum Az PowerShell-Modul finden Sie unter Migrieren von AzureRM zu Azure PowerShell Az im Azure Stack Hub. Ausführliche Informationen zu den erweiterten Funktionen der Az-Module, die in globalen Azure eingeführt wurden, finden Sie unter Einführung in das Azure Az PowerShell-Modul.

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 in der PSGallery.

In diesem Artikel wird erläutert, wie Sie die Azure PowerShell Az- und kompatiblen Azure Stack Hub-Administratormodule mit PowerShellGet installieren. Sie können die Az-Module auf Windows-, macOS- und Linux-Plattformen installieren.

Sie können auch die Az-Module für Azure Stack Hub in einem Docker-Container ausführen. Anweisungen finden Sie unter Verwenden von Docker zum Ausführen von PowerShell 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 zum Verwalten von Versionsunterschieden zwischen Azure und Azure Stack Hub. Ein API-Versionsprofil ist eine Reihe von PowerShell-Modulen des Azure Resource Manager mit bestimmten API-Versionen. Jede Cloudplattform verfügt über eine Reihe unterstützter API-Versionsprofile. Beispielsweise unterstützt Azure Stack Hub eine bestimmte Profilversion wie 2020-09-01-Hybrid. Wenn Sie ein Profil installieren, werden die PowerShell-Module des Azure Resource Manager installiert, die dem angegebenen Profil entsprechen.

Sie können Azure Stack Hub-kompatible PowerShell Az-Module in internetgebundenen, teilweise verbundenen oder getrennten Szenarien installieren. Dieser Artikel führt Sie durch die detaillierten Anweisungen für diese Szenarien.

Überprüfen Sie Ihre Voraussetzungen

Az-Module werden auf Azure Stack Hub mit Update 2002 oder höher und mit allen aktuellen Hotfixes unterstützt. Weitere Informationen finden Sie in den Versionshinweisen zu Azure Stack Hub .

Die Azure PowerShell Az-Module funktionieren mit PowerShell 5.1 oder höher unter Windows oder PowerShell Core 6.x und höher auf allen Plattformen. Sie sollten die neueste Version von PowerShell Core installieren, die für Ihr Betriebssystem verfügbar ist. Azure PowerShell hat keine anderen Anforderungen, wenn sie auf PowerShell Core ausgeführt werden.

Führen Sie den folgenden 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. Aktualisieren Sie bei Bedarf auf Windows PowerShell 5.1 . Wenn Sie Windows 10 verwenden, ist PowerShell 5.1 bereits installiert.

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

3. Stellen Sie sicher, dass Sie über die neueste Version von PowerShellGet verfügen. Führen Sie die folgenden Cmdlets aus 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
   

Voraussetzungen für Linux und Mac

PowerShell Core 6.x oder höher ist erforderlich. Folgen Sie dem Link , um Anweisungen zu erhalten.

Deinstallieren vorhandener Versionen der Azure Stack Hub PowerShell-Module

Stellen Sie vor der Installation der erforderlichen Version sicher, dass Sie alle zuvor installierten Azure Stack Hub Azure Resource Manager- oder Az PowerShell-Module deinstallieren. Deinstallieren Sie die Module mit einer der folgenden beiden Methoden:

• Um die vorhandenen Azure Resource Manager- und Az PowerShell-Module zu deinstallieren, schließen Sie alle aktiven PowerShell-Sitzungen, und führen Sie die folgenden Cmdlets aus:

  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 ein Fehler wie "Das Modul wird bereits verwendet" auftritt, schließen Sie die PowerShell-Sitzungen, die die Module verwenden, und führen Sie diese Cmdlets erneut aus.

• Wenn Uninstall-Module dies 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 sein. Für PowerShell Core können die Speicherorte sein C:\Program Files\PowerShell\7\Modules und C:\Users\{yourusername}\Documents\PowerShell\Modules. Wenn Sie diese Ordner löschen, werden alle vorhandenen Azure PowerShell-Module entfernt.

Verbunden: Installieren mit Internetverbindung

Das Azure Stack Az-Modul funktioniert mit PowerShell 5.1 oder höher auf einem Windows-Computer oder PowerShell 6.x oder höher auf einer Linux- oder macOS-Plattform. Die Verwendung der PowerShellGet-Cmdlets ist die bevorzugte Installationsmethode. Diese Methode funktioniert auf den unterstützten Plattformen auf die gleiche Weise.

1. Führen Sie den folgenden Befehl aus einer PowerShell-Sitzung aus, um PowerShellGet auf eine Mindestversion von Version 2.2.3 zu aktualisieren:

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

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

3. Führen Sie die folgenden Befehle 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 die AzureStack PowerShell-Module:

   Install-Module -Name AzureStack -RequiredVersion 2.4.0
   

Getrennt: Ohne Internetverbindung installieren

In einem getrennten Szenario laden Sie zuerst die PowerShell-Module auf einen Computer mit Internetverbindung herunter. Anschließend übertragen Sie sie zur Installation in das Azure Stack Development Kit (ASDK).

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

Die Installation umfasst fünf Schritte:

1. Installieren Sie Azure Stack Hub PowerShell auf einem verbundenen Computer.
2. Aktivieren Sie zusätzliche Speicherfeatures.
3. Transportieren Sie die PowerShell-Pakete zu Ihrer getrennten Arbeitsstation.
4. Starten Sie den NuGet-Anbieter manuell auf Ihrer getrennten Arbeitsstation.
5. Bestätigen Sie die Installation von PowerShell.

Installieren von Azure Stack Hub PowerShell

1. Der folgende Code installiert Az-Module aus dem vertrauenswürdigen Online-Repository:

   [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. Fahren Sie nach der Installation der Az-Module 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

Auf Computern ohne Internetverbindung wird empfohlen, das Cmdlet Disable-AzDataCollection auszuführen, um die Telemetriedatensammlung zu deaktivieren. Andernfalls kann es zu einer Leistungsbeeinträchtigung der cmdlets kommen. Dies gilt nur für Computer ohne Internetverbindung.

Hinzufügen Ihrer Pakete zu 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. Starten Sie den NuGet-Anbieter manuell 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 Standard-Repository 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 von PowerShell

Bestätigen Sie die Installation, indem Sie den folgenden Befehl ausführen:

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

Konfigurieren von PowerShell für die Verwendung eines Proxyservers

In Szenarien, in denen 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 erhöhte PowerShell-Eingabeaufforderung.

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
   

Verwenden des Az-Moduls

Sie können weiterhin die Cmdlets und Codebeispiele verwenden, die auf AzureRM-Modulen basieren. Sie müssen jedoch den Namen der Module und Cmdlets ändern. Die Modulnamen wurden so geändert, dass AzureRM und Azure werden Az, und dasselbe für Cmdlets. Das Modul wurde z. B. AzureRM.Compute umbenannt in Az.Compute. New-AzureRMVM ist New-AzVM, und Get-AzureStorageBlob ist jetzt Get-AzStorageBlob.

Eine ausführlichere Diskussion und Anleitung für das Verschieben von AzureRM-Skripts in Az und Informationen zum Unterbrechen von Änderungen im Az-Modul von Azure Stack Hub finden Sie unter Migrieren von AzureRM zu Azure PowerShell Az.

Bekannte Probleme

Fehler beim Installieren der Az-Module aufgetreten

• Anwendbar: Dieses Problem gilt für 2002 und höher
• Ursache: Beim Installieren des Moduls wird ein Fehler ausgelöst. Die Fehlermeldung beginnt: Register-PacakgeSource : A parameter cannot be found that matches parameter name. 'PackageManagementProvider'. Oder die Fehlermeldung kann den folgenden Text enthalten: PackageManagement\Install-Package : Cannot convert value "2.0.1-preview" to type "System.Version". Error: "Input string was not in a correct format."
• Behebung: Führen Sie das folgende Cmdlet in derselben Sitzung aus:
  Install-Module PowershellGet -MinimumVersion 2.3.0 -Force
  Schließen Sie Ihre Sitzung, und starten Sie eine neue PowerShell-Sitzung mit erhöhten Rechten.
• Vorkommen: Allgemein

Bei der Installation des Az-Moduls wird der Fehler "Administratorrechte erforderlich" fälschlicherweise angezeigt.

• Anwendbar: Dieses Problem gilt für 2002 und höher
• Ursache: Bei der Installation des Moduls über eine Eingabeaufforderung mit erhöhten Rechten tritt ein Fehler auf. Der Fehler besagt, Administrator rights required.
• Korrektur: Schließen Sie Ihre Sitzung, und starten Sie eine neue PowerShell-Sitzung mit erhöhten Rechten. Stellen Sie sicher, dass keine Az vorhanden ist. Das Kontomodul wurde in die Sitzung geladen.
• Vorkommen: Allgemein

Cmdlet-New-AzVmss schlägt fehl, wenn das Hybrid-Profil von 2020-09-01 verwendet wird

• Anwendbar: Dieses Problem gilt für das Hybridprofil 2020-09-01.
• Ursache: Das Cmdlet New-AzVmss funktioniert nicht mit dem Hybridprofil 2020-09-01.
• Korrektur: Verwenden Sie eine Vorlage zum Erstellen eines Skalierungssatzes für virtuelle Computer. Sie finden ein Beispiel der Azure Stack Hub Resource Manager-Vorlagen im GitHub-Repository AzureStack-QuickStart-Templates/101-vmss-windows-vm , und Sie finden Anweisungen zur Verwendung von Azure Stack Hub-Ressourcenmanagern mit Visual Studio Code.
• Vorkommen: Allgemein

Fehler beim Ausführen eines PowerShell-Skripts

• Anwendbar: Dieses Problem gilt für 2002 und höher.

• Ursache: Wenn Sie Skripts oder PowerShell-Befehle mit den spezifischen Azure Stack Hub-Modulen ausführen, benötigen Sie Ihr Skript oder Ihren Befehl, um im Modul verfügbar zu sein. Möglicherweise wird 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, wenn das Az-Modul installiert ist, löst Ihr Skript Fehler aus. Oder wenn Sie versuchen, ein Skript auszuführen, das Az-Befehle aufruft, wenn das AzureRM-Modul installiert ist, löst Ihr Skript Fehler aus.

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

• Vorkommen: Allgemein

Mit New-AzADServicePrincipal und New-AzADApplication ausgelöster Fehler

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

• Ursache: Azure Active Directory Graph hat eine erhebliche Änderung eingeführt, um Active Directory-Anwendungen darauf zu beschränken, dass die IdentifierUri Unterdomänen von einer überprüften Domäne im Verzeichnis sein müssen. Vor der Änderung wurde diese Einschränkung nur für die Mehrinstanzen-Apps erzwungen. Nun gilt diese Einschränkung auch für Single-Tenant-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.

• Behebung: Sie können diese Einschränkung auf zwei Arten umgehen.

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

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

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

  • Erstellen Sie die Microsoft Entra-App, indem Sie ein gültiges IdentifierUri angeben, und erstellen Sie dann den Dienstprinzipal, indem Sie die App mit dem folgenden Cmdlet verknüpfen:

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

• Vorkommen: Allgemein

Fehler: "SharedTokenCacheCredential-Authentifizierung fehlgeschlagen"

• Anwendbar: Dieses Problem gilt für alle unterstützten Versionen.
• Ursache: Ein SharedTokenCacheCredential-Authentifizierungsfehler tritt auf, wenn mehrere Versionen von AzAccounts zusammen mit dem Azure Stack Hub PowerShell-Modul Version 2.1.1 installiert sind.
• Korrektur: Entfernen Sie alle Versionen von AzAccounts, und installieren Sie nur die unterstützte AzAccounts Version 2.2.8.
• Vorkommen: Allgemein

Nächste Schritte

• Herunterladen von Azure Stack Hub-Tools von 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