Behandeln von bekannten Problemen

  • Artikel

In diesem Artikel werden einige der bekannten Probleme mit .NET Multiplatform App UI (.NET MAUI) beschrieben und wie Sie sie lösen oder umgehen können. Das .NET MAUI Repository beschreibt auch einige bekannte Probleme.

Die .NET MAUI-Workloads können nicht gefunden werden

Für die Installation der .NET MAUI-Workloads gibt es zwei Möglichkeiten:

  1. Visual Studio unter Windows kann .msi-Dateien für jedes Workload-Pack installieren.
  2. dotnet workload install-Befehle

Wenn Sie unter Windows nach der Installation von .NET MAUI über das Visual Studio-Installationsprogramm ein dotnet workload install ausführen, kann Visual Studio in einen Zustand geraten, in dem es die .NET MAUI-Workloads nicht finden kann. Sie erhalten Build-Fehler, die Sie auffordern, die .NET MAUI-Workloads zu installieren, und es ist möglich, dass das System in einen Zustand gerät, in dem die Workloads nicht repariert oder neu installiert werden können. Weitere Informationen finden Sie in der GitHub-Ausgabe dotnet/sdk#22388.

Windows

Die Lösung für dieses Problem unter Windows ist die Deinstallation der .NET MAUI-Workloads über die Befehlszeilenschnittstelle, die Deinstallation aller .NET SDKs in der Systemsteuerung und die Deinstallation der .NET MAUI-Workloads in Visual Studio. Diese Deinstallationen können mit dem folgenden Verfahren durchgeführt werden:

  1. Führen Sie dotnet workload uninstall maui aus, wenn Sie jemals die Befehle dotnet workload install verwendet haben.
  2. Deinstallieren Sie alle eigenständigen .NET SDK-Installationsprogramme über die Systemsteuerung. Diese Installationsprogramme haben Namen ähnlich wie Microsoft .NET SDK 6.0.300.
  3. Deinstallieren Sie in jeder Instanz von Visual Studio die Visual Studio-Workloads .NET Multiplatform App UI Development und .NET Desktop Development.

Prüfen Sie anschließend, ob es weitere .msi-Dateien gibt, die deinstalliert werden müssen, indem Sie den folgenden Befehl ausführen:

reg query HKLM\SOFTWARE\Microsoft\Windows\currentversion\uninstall\ -s -f manifest

Dieser reg query-Befehl listet die .NET 6+ SDKs auf, die noch auf Ihrem Rechner installiert sind, wie etwa:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\currentversion\uninstall\{EEC1BB5F-3391-43C2-810E-42D78ADF3140}
    InstallSource    REG_SZ    C:\ProgramData\Microsoft\VisualStudio\Packages\Microsoft.MacCatalyst.Manifest-6.0.300,version=125.179.40883,chip=x64,productarch=neutral\
    DisplayName    REG_SZ    Microsoft.NET.Sdk.MacCatalyst.Manifest-6.0.300

Wenn Sie eine ähnliche Ausgabe erhalten, sollten Sie die GUID für jedes Paket kopieren und das Paket mit dem Befehl msiexec deinstallieren:

msiexec /x {EEC1BB5F-3391-43C2-810E-42D78ADF3140} /q IGNOREDEPENDENCIES=ALL

Dann sollten Sie den Befehl reg query so lange ausführen, bis er keine Ergebnisse mehr liefert. Sobald es keine Ergebnisse mehr gibt und alle .NET 6+ SDKs deinstalliert sind, sollten Sie auch das Löschen der folgenden Ordner in Betracht ziehen:

  • C:\Program Files\dotnet\sdk-manifests
  • C:\Program Files\dotnet\metadata
  • C:\Program Files\dotnet\packs
  • C:\Program Files\dotnet\library-packs
  • C:\Program Files\dotnet\template-packs
  • C:\Program Files\dotnet\sdk\6.* oder C:\Program Files\dotnet\sdk\7.*
  • C:\Program Files\dotnet\host\fxr\6.* oder C:\Program Files\dotnet\host\fxr\7.*

Nach diesem Vorgang sollten Sie in der Lage sein, .NET MAUI neu zu installieren, entweder über Visual Studio oder indem Sie die gewünschte .NET SDK-Version installieren und den Befehl dotnet workload install maui ausführen.

Mac

Das Installations- und Aktualisierungsprogramm von Visual Studio für Mac verwendet dotnet workload install-Befehle zur Installation der .NET MAUI .pkg-Dateien.

Da .pkg-Dateien nicht deinstalliert werden können, besteht die einfachste Methode zur Deinstallation der Workloads auf einem Mac darin, die folgenden Befehle auszuführen, um die angegebenen Ordner zu löschen:

rm -r ~/.dotnet/
sudo rm -r /usr/local/share/dotnet/

Nachdem Sie diese Befehle ausgeführt haben, sollten Sie in der Lage sein, .NET MAUI neu zu installieren, entweder über Visual Studio für Mac oder indem Sie die gewünschte .NET SDK-Version installieren und den Befehl dotnet workload install maui ausführen.

Plattformversion ist nicht vorhanden

Wenn Sie versuchen, ein Projekt zu kompilieren und eine Fehlermeldung ähnlich dem folgenden Text erhalten, löst Visual Studio möglicherweise nicht die erforderlichen Workloads auf:

Für ein oder mehrere Ziel-Frameworks ist keine Plattformversion vorhanden, obwohl sie eine Plattform angegeben haben: net8.0-android, net8.0-ios, net8.0-maccatalyst

Dieses Problem tritt normalerweise auf, wenn ein x86- und ein x64-SDK installiert sind und die x86-Version verwendet wird. Visual Studio und .NET MAUI erfordern das x64 .NET SDK. Wenn Ihr Betriebssystem eine systemweite PATH-Variable hat, die das x86-SDK zuerst auflöst, müssen Sie dies beheben, indem Sie entweder das x86-.NET-SDK aus der PATH-Variable entfernen oder das x64-.NET-SDK höherstufen, damit es zuerst aufgelöst wird. Weitere Informationen zur Fehlerbehebung bei der Auflösung von x86- und x64-SDKs finden Sie unter Installation von .NET unter Windows – Fehlerbehebung.

Typ oder Namespace 'Default' existiert nicht

Wenn Sie die Contacts API verwenden, kann der folgende Fehler in Bezug auf iOS und macOS auftreten:

The type or namespace name 'Default' does not exist in the namespace 'Contacts' (are you missing an assembly reference?)

Die Plattformen iOS und macOS enthalten einen Stamm-Namespace namens Contacts. Dieser Konflikt verursacht einen Konflikt für die Plattformen mit dem Microsoft.Maui.ApplicationModel.Communication Namespace, der einen Contacts Typ enthält. Der Microsoft.Maui.ApplicationModel.Communication-Namespace wird automatisch durch die <ImplicitUsings>-Einstellung in der Projektdatei importiert.

Um Code zu schreiben, der auch für iOS und macOS kompiliert werden kann, qualifizieren Sie den Typ Contacts vollständig. Alternativ können Sie eine using-Anweisung am Anfang der Codedatei angeben, um den Communication-Namenspace zuzuordnen:

using Communication = Microsoft.Maui.ApplicationModel.Communication;

// Code that uses the namespace:
var contact = await Communication.Contacts.Default.PickContactAsync();

Xcode ist derzeit nicht installiert oder konnte nicht gefunden werden

Nachdem Sie die Xcode-Befehlszeilentools mit xcode-select --install installiert haben, zeigt Visual Studio für Mac möglicherweise die Meldung „Xcode ist derzeit nicht installiert oder konnte nicht gefunden werden“ an, wenn Sie versuchen, .NET MAUI-Apps zu erstellen, die auf iOS oder Mac Catalyst abzielen. Stellen Sie in diesem Fall sicher, dass Sie auch Xcode aus dem App Store installiert haben. Starten Sie dann Xcode und gehen Sie zu Xcode > Einstellungen > Speicherorte > Befehlszeilen-Tools und überprüfen Sie, ob das Dropdown-Menü leer ist. Wenn es leer ist, wählen Sie das Dropdown-Menü und dann den Speicherort der Xcode-Befehlszeilentools aus. Schließen Sie dann Xcode und starten Sie Visual Studio für Mac neu.

Es konnte kein gültiges Xcode-App-Bundle gefunden werden

Wenn Sie die Fehlermeldung „Es konnte kein gültiges Xcode-App-Bundle unter '/Library/Developer/CommandLineTools' gefunden werden“ erhalten, wenn Sie versuchen, .NET MAUI-Apps zu erstellen, die auf iOS oder Mac Catalyst abzielen, versuchen Sie die in Xcode ist derzeit nicht installiert oder konnte nicht gefunden werden beschriebene Lösung. Wenn Sie immer noch nicht auf das Dropdown-Menü Xcode > Einstellungen > Speicherorte > Befehlszeilen-Tools zugreifen können, führen Sie den folgenden Befehl aus:

sudo xcode-select --reset

Xcode-Version kann nicht gefunden werden.

In einigen Szenarien kann beim Erstellen einer .NET MAUI-App unter iOS oder Mac Catalyst versucht werden, eine Version von Xcode zu verwenden, die nicht mehr auf Ihrem Computer installiert ist. Wenn dies geschieht, erhalten Sie eine Fehlermeldung ähnlich wie die folgende:

xcodebuild: error: SDK "/Applications/Xcode_14.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk" cannot be located.
xcrun: error: sh -c '/Applications/Xcode_14.1.app/Contents/Developer/usr/bin/xcodebuild -sdk /Applications/Xcode_14.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk -find dsymutil 2> /dev/null' failed with exit code 16384: (null) (errno=Invalid argument)
xcrun: error: unable to find utility "dsymutil", not a developer tool or in PATH

Beim Erstellen einer App verwenden .NET for iOS und .NET for Mac Catalyst den folgenden Prozess, um zu bestimmen, welche Xcode-Version verwendet werden soll:

  1. Wenn die MD_APPLE_SDK_ROOT-Umgebungsvariable festgelegt ist, verwenden Sie ihren Wert.
  2. Wenn die Datei ~/Library/Preferences/Xamarin/Settings.plist vorhanden ist, verwenden Sie den darin definierten Wert.
  3. Verwenden Sie den Wert von xcode-select -p.
  4. Verwenden Sie /Applications/Xcode.app.

Es wird daher empfohlen, zum Angeben des Speicherorts von Xcode auf Ihrem Computer die MD_APPLE_SDK_ROOT-Umgebungsvariable auf den Pfad der Xcode-Version festzulegen. Weitere Informationen finden Sie unter Erstellen von Apps mit einer bestimmten Version von Xcode.

Anschließend können Sie ~/Library/Preferences/Xamarin/Settings.plist von Ihrem Computer löschen.

Diagnose von Problemen in Blazor Hybrid Apps

BlazorWebView verfügt über eine integrierte Protokollierung, die Ihnen bei der Diagnose von Problemen in Ihrer Blazor Hybrid-App helfen kann. Es gibt zwei Schritte, um diese Protokollierung zu aktivieren:

  1. Aktivieren Sie BlazorWebView und verwandte Komponenten zum Protokollieren von Diagnoseinformationen.
  2. Konfigurieren Sie einen Logger, der die Protokollausgabe an einen Ort schreibt, an dem Sie sie einsehen können.

Weitere Informationen finden Sie unter Probleme in Blazor Hybrid-Apps diagnostizieren.

Deaktivieren der Bildverpackung

Zur Fehlerbehebung kann das Paketieren von Bildressourcen deaktiviert werden, indem die $(EnableMauiImageProcessing) Build-Eigenschaft im ersten <PropertyGroup>-Knoten in Ihrer Projektdatei auf false gesetzt wird:

<EnableMauiImageProcessing>false</EnableMauiImageProcessing>

Begrüßungsbildschirm-Paketierung deaktivieren

Zur Fehlerbehebung kann die Erzeugung von Begrüßungsbildschirm-Ressourcen deaktiviert werden, indem die $(EnableSplashScreenProcessing) Build-Eigenschaft im ersten <PropertyGroup>-Knoten der Projektdatei auf false gesetzt wird:

<EnableSplashScreenProcessing>false</EnableSplashScreenProcessing>

Schriftartenpaketierung deaktivieren

Zur Fehlerbehebung kann das Paketieren von Schriftressourcen deaktiviert werden, indem die $(EnableMauiFontProcessing) Build-Eigenschaft im ersten <PropertyGroup>-Knoten in Ihrer Projektdatei auf false gesetzt wird:

<EnableMauiFontProcessing>false</EnableMauiFontProcessing>

Ressourcendateipaketierung deaktivieren

Zur Fehlerbehebung kann die Ressourcenkomprimierung von Asset-Dateien deaktiviert werden, indem die $(EnableMauiAssetProcessing)-Build-Eigenschaft im ersten <PropertyGroup>-Knoten in Ihrer Projektdatei auf false gesetzt wird:

<EnableMauiAssetProcessing>false</EnableMauiAssetProcessing>

Einen leeren Begrüßungsbildschirm generieren

Zur Fehlersuche kann ein leerer Begrüßungsbildschirm erzeugt werden, wenn Sie kein <MauiSplashScreen>-Element und keinen benutzerdefinierten Begrüßungsbildschirm haben. Dies kann erreicht werden, indem die $(EnableBlankMauiSplashScreen)-Build-Eigenschaft im ersten <PropertyGroup>-Knoten in Ihrer Projektdatei auf true gesetzt wird:

<EnableBlankMauiSplashScreen>true</EnableBlankMauiSplashScreen>

Das Erzeugen eines leeren Startbildschirms überschreibt jeden benutzerdefinierten Startbildschirm und führt zur Ablehnung im App Store. Es kann jedoch ein nützlicher Ansatz beim Testen sein, um sicherzustellen, dass die Benutzeroberfläche Ihrer App korrekt ist.

Fehler bei doppelten Bilddateinamen

Es kann zu Fehlern bei der Erstellung doppelter Bilddateinamen kommen:

Es wurden ein oder mehrere doppelte Dateinamen entdeckt. Alle Dateinamen der Bildausgabe müssen eindeutig sein.

Dies tritt bei MauiIcon- und MauiImage-Elementen auf, da .NET MAUI ab .NET 8 prüft, um sicherzustellen, dass es keine doppelten Dateinamen für Bildressourcen gibt.

Der Fehler tritt auf, wenn Sie identische Dateinamen in mehreren Ordnern haben, und in bestimmten Fällen, wenn Sie identische Dateinamen mit unterschiedlichen Erweiterungen in verschiedenen Ordnern haben. Beispielsweise tritt der Erstellungsfehler bei einer PNG-Datei unter Resources/Images/PNG/dotnet_bot.png und einer SVG-Datei unter Resources/Images/SVG/dotnet_bot.svg auf, da SVG-Dateien zur Erstellungszeit in PNG-Dateien umgewandelt werden.

Der Fehler tritt auch auf, wenn Sie das Include-Attribut für ein MauiImage-Element verwenden, um alle Bilder in einen Ordner einzuschließen und dann auch eine bestimmte Bilddatei einzuschließen:

<MauiImage Include="Resources\Images\*" />
<MauiImage Include="Resources\Images\dotnet_bot.svg" BaseSize="168,208" />

Wenn Sie diesen Buildfehler erhalten, kann dies behoben werden, indem Sie sicherstellen, dass Ihre Projektdatei keine doppelten Bilder enthält. Ändern Sie dazu alle MauiIcon oder MauiImage, die auf eine bestimmte Datei verweisen, sodass sie das Attribut Update anstelle des Attributs Include verwenden:

<MauiImage Include="Resources\Images\*" />
<MauiImage Update="Resources\Images\dotnet_bot.svg" BaseSize="168,208" />

Für Informationen über MSBuild-Elementattribute siehe Element (MSBuild): Attribute und Elemente.