Rozwiązywanie znanych problemów

W tym artykule opisano niektóre znane problemy z interfejsem użytkownika aplikacji wieloplatformowej platformy .NET (.NET MAUI) oraz sposobem ich rozwiązywania lub obejścia. Repozytorium .NET MAUI zawiera również szczegóły niektórych znanych problemów.

Nie można zlokalizować obciążeń .NET MAUI

Istnieją dwie opcje instalowania obciążeń .NET MAUI:

1. Program Visual Studio w systemie Windows może instalować pliki .msi dla każdego pakietu roboczego.
2. dotnet workload install Polecenia.

W systemie Windows, jeśli uruchamiasz dotnet workload install po zainstalowaniu programu .NET MAUI za pośrednictwem instalatora programu Visual Studio, program Visual Studio może wprowadzić stan, w którym nie może zlokalizować obciążeń .NET MAUI. Zostaną wyświetlone błędy kompilacji z informacją o zainstalowaniu obciążeń .NET MAUI. Możliwe jest wprowadzenie stanu, w którym nie można naprawić ani zainstalować ponownie obciążeń. Aby uzyskać więcej informacji, zobacz problem z usługą GitHub dotnet/sdk#22388.

Windows

Rozwiązaniem tego problemu w systemie Windows jest odinstalowanie obciążeń .NET MAUI za pomocą interfejsu wiersza polecenia, odinstalowanie wszystkich zestawów SDK platformy .NET w Panel sterowania i odinstalowanie obciążeń .NET MAUI w programie Visual Studio. Te odinstalowania można wykonać przy użyciu następującego procesu:

1. Uruchom polecenie dotnet workload uninstall maui , jeśli kiedykolwiek użyto dotnet workload install poleceń.
2. Odinstaluj wszystkie autonomiczne instalatory zestawu .NET SDK z Panel sterowania. Te instalatory mają nazwy podobne do Microsoft .NET SDK 6.0.300.
3. W każdym wystąpieniu programu Visual Studio odinstaluj programowanie wieloplatformowego interfejsu użytkownika aplikacji platformy .NET oraz obciążenia programu Visual Studio dla aplikacji klasycznych .NET.

Następnie sprawdź, czy istnieją dodatkowe .msi pliki, które należy odinstalować, uruchamiając następujące polecenie:

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

To reg query polecenie wyświetla listę zestawów SDK platformy .NET 6+ zainstalowanych na maszynie, takich jak:

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

Jeśli otrzymasz podobne dane wyjściowe, należy skopiować identyfikator GUID dla każdego pakietu i odinstalować pakiet za msiexec pomocą polecenia :

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

Następnie należy kontynuować wykonywanie reg query polecenia, dopóki nie zwróci żadnych wyników. Gdy nie będzie więcej wyników i wszystkie zestawy SDK platformy .NET 6+ zostaną odinstalowane, należy również rozważyć usunięcie następujących folderów:

• 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.* lub C:\Program Files\dotnet\sdk\7.*
• C:\Program Files\dotnet\host\fxr\6.* lub C:\Program Files\dotnet\host\fxr\7.*

Po wykonaniu tego procesu powinno być możliwe ponowne zainstalowanie programu .NET MAUI za pomocą programu Visual Studio lub zainstalowanie wybranej wersji zestawu .NET SDK i uruchomienie dotnet workload install maui polecenia .

Mac

instalator i aktualizator Visual Studio dla komputerów Mac używają dotnet workload install poleceń do instalowania plików .pkg programu .NET MAUI.

Ponieważ nie można odinstalować plików .pkg , najprostszym podejściem do odinstalowania obciążeń na komputerze Mac jest uruchomienie następujących poleceń w celu usunięcia określonych folderów:

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

Po wykonaniu tych poleceń powinno być możliwe ponowne zainstalowanie programu .NET MAUI za pomocą Visual Studio dla komputerów Mac lub zainstalowanie wybranej wersji zestawu .NET SDK i uruchomienie dotnet workload install maui polecenia.

Wersja platformy nie jest obecna

Program Visual Studio może nie rozpoznawać wymaganych obciążeń, jeśli spróbujesz skompilować projekt i wystąpi błąd podobny do następującego tekstu:

Wersja platformy nie jest obecna dla co najmniej jednej platformy docelowej, mimo że określono platformę: net8.0-android, net8.0-ios, net8.0-maccatalyst

Ten problem zazwyczaj wynika z zainstalowania zestawu SDK x86 i x64, a wersja x86 jest używana. Programy Visual Studio i .NET MAUI wymagają zestawu SDK platformy .NET x64. Jeśli system operacyjny ma zmienną dla całego PATH systemu, która najpierw rozpoznaje zestaw SDK x86, należy rozwiązać ten problem, usuwając zestaw SDK platformy .NET x86 ze PATH zmiennej lub promując zestaw SDK platformy .NET x64, aby rozwiązać ten problem jako pierwszy. Aby uzyskać więcej informacji na temat rozwiązywania problemów z rozpoznawaniem zestawu SDK x86 i x64, zobacz Instalowanie platformy .NET w systemie Windows — rozwiązywanie problemów.

Typ lub przestrzeń nazw "Default" nie istnieje

W przypadku korzystania z interfejsu Contacts API może zostać wyświetlony następujący błąd związany z systemami iOS i macOS:

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

Platformy systemów iOS i macOS zawierają przestrzeń nazw katalogu głównego o nazwie Contacts. Ten konflikt powoduje konflikt dla tych platform z Microsoft.Maui.ApplicationModel.Communication przestrzenią nazw, która zawiera Contacts typ. Microsoft.Maui.ApplicationModel.Communication Przestrzeń nazw jest automatycznie importowana przez <ImplicitUsings> ustawienie w pliku projektu.

Aby napisać kod kompilowany również dla systemów iOS i macOS, należy w pełni zakwalifikować Contacts typ. Alternatywnie podaj dyrektywę using w górnej części pliku kodu, aby zamapować Communication przestrzeń nazw:

using Communication = Microsoft.Maui.ApplicationModel.Communication;

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

Program Xcode nie jest obecnie zainstalowany lub nie można go odnaleźć

Po zainstalowaniu narzędzi wiersza polecenia programu Xcode przy użyciu programu xcode-select --installVisual Studio dla komputerów Mac może zostać wyświetlony komunikat "Xcode nie jest obecnie zainstalowany lub nie można go odnaleźć" podczas próby skompilowania aplikacji MAUI platformy .NET przeznaczonych dla systemu iOS lub Mac Catalyst. W tym scenariuszu sprawdź, czy masz również zainstalowany program Xcode ze sklepu App Store. Następnie uruchom program Xcode i przejdź do pozycji Narzędzia wiersza polecenia Preferencji >> Xcode > i sprawdź, czy lista rozwijana jest pusta. Jeśli jest on pusty, wybierz listę rozwijaną, a następnie wybierz lokalizację narzędzi wiersza polecenia Xcode. Następnie zamknij program Xcode i uruchom ponownie Visual Studio dla komputerów Mac.

Nie można odnaleźć prawidłowego pakietu aplikacji Xcode

Jeśli podczas próby skompilowania aplikacji MAUI platformy .NET, które są przeznaczone dla systemu iOS lub Mac Catalyst, podczas próby skompilowania aplikacji MAUI platformy .NET przeznaczonych dla systemu iOS lub Mac Catalyst, spróbuj użyć rozwiązania opisanego w narzędziu Xcode, które nie jest obecnie zainstalowane lub nie można go znaleźć. Jeśli nadal nie możesz uzyskać dostępu do listy rozwijanej Narzędzia wiersza polecenia preferencji > Xcode>, > uruchom następujące polecenie:

sudo xcode-select --reset

Nie można znaleźć wersji programu Xcode

W niektórych scenariuszach utworzenie aplikacji MAUI platformy .NET w systemie iOS lub Mac Catalyst może podjąć próbę użycia wersji programu Xcode, która nie jest już zainstalowana na maszynie. W takim przypadku zostanie wyświetlony komunikat o błędzie podobny do następującego:

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

Podczas kompilowania aplikacji platforma .NET dla systemów iOS i .NET dla komputerów Mac Catalyst używa następującego procesu, aby określić, która wersja programu Xcode ma być używana:

1. Jeśli zmienna środowiskowa jest ustawiona MD_APPLE_SDK_ROOT , użyj jej wartości.
2. Jeśli plik ~/Library/Preferences/Xamarin/Ustawienia.plist istnieje, użyj wartości zdefiniowanej w niej.
3. Użyj wartości xcode-select -p.
4. Użyj witryny /Applications/Xcode.app.

W związku z tym zalecaną metodą określania lokalizacji programu Xcode na maszynie jest ustawienie MD_APPLE_SDK_ROOT zmiennej środowiskowej na ścieżkę wersji programu Xcode. Aby uzyskać więcej informacji, zobacz Build with a specific version of Xcode (Kompilowanie przy użyciu określonej wersji programu Xcode).

Następnie możesz bezpiecznie usunąć plik ~/Library/Preferences/Xamarin/Ustawienia.plist z komputera.

Diagnozowanie problemów w aplikacjach hybrydowych platformy Blazor

BlazorWebView ma wbudowane rejestrowanie, które może pomóc w diagnozowaniu problemów w aplikacji hybrydowej platformy Blazor. Aby włączyć to rejestrowanie, należy wykonać dwa kroki:

1. Włącz BlazorWebView i powiązane składniki w celu rejestrowania informacji diagnostycznych.
2. Skonfiguruj rejestrator, aby zapisywał dane wyjściowe dziennika w miejscu, w którym można go wyświetlić.

Aby uzyskać więcej informacji, zobacz Diagnozowanie problemów w aplikacjach hybrydowych platformy Blazor.

Wyłączanie tworzenia pakietów obrazów

Na potrzeby rozwiązywania problemów pakowanie zasobów obrazu można wyłączyć, ustawiając $(EnableMauiImageProcessing) właściwość kompilacji na false w pierwszym <PropertyGroup> węźle w pliku projektu:

<EnableMauiImageProcessing>false</EnableMauiImageProcessing>

Wyłączanie tworzenia pakietów ekranu powitalnego

W celach rozwiązywania problemów generowanie zasobów ekranu powitalnego można wyłączyć, ustawiając $(EnableSplashScreenProcessing) właściwość kompilacji na false w pierwszym <PropertyGroup> węźle w pliku projektu:

<EnableSplashScreenProcessing>false</EnableSplashScreenProcessing>

Wyłączanie tworzenia pakietów czcionek

W celu rozwiązywania problemów można wyłączyć pakowanie zasobów czcionek, ustawiając $(EnableMauiFontProcessing) właściwość kompilacji na false w pierwszym <PropertyGroup> węźle w pliku projektu:

<EnableMauiFontProcessing>false</EnableMauiFontProcessing>

Wyłączanie tworzenia pakietów plików elementów zawartości

W celach rozwiązywania problemów pakowanie zasobów plików zasobów zasobów można wyłączyć, ustawiając $(EnableMauiAssetProcessing) właściwość kompilacji na false w pierwszym <PropertyGroup> węźle w pliku projektu:

<EnableMauiAssetProcessing>false</EnableMauiAssetProcessing>

Generowanie pustego ekranu powitalnego

W celach rozwiązywania problemów można wygenerować pusty ekran powitalny, jeśli nie masz <MauiSplashScreen> elementu i nie masz niestandardowego ekranu powitalnego. Można to osiągnąć, ustawiając właściwość kompilacji $(EnableBlankMauiSplashScreen) na true w pierwszym <PropertyGroup> węźle w pliku projektu:

<EnableBlankMauiSplashScreen>true</EnableBlankMauiSplashScreen>

Wygenerowanie pustego ekranu powitalnego spowoduje zastąpienie dowolnego niestandardowego ekranu powitalnego i spowoduje odrzucenie sklepu z aplikacjami. Jednak może to być przydatne podejście do testowania, aby upewnić się, że interfejs użytkownika aplikacji jest poprawny.

Błędy zduplikowanych nazw plików obrazów

Mogą wystąpić błędy kompilacji dotyczące zduplikowanych nazw plików obrazów:

Wykryto co najmniej jedną zduplikowaną nazwę pliku. Wszystkie nazwy plików wyjściowych obrazów muszą być unikatowe.

Dzieje się tak w przypadku MauiIcon elementów i MauiImage , ponieważ z platformy .NET 8 program MAUI sprawdza, czy nie ma zduplikowanych nazw plików zasobów obrazu.

Błąd wystąpi, gdy masz identyczne nazwy plików w wielu folderach i w pewnych okolicznościach, gdy masz identyczne nazwy plików z różnymi rozszerzeniami w różnych folderach. Na przykład błąd kompilacji wystąpi dla pliku PNG w folderze Resources/Images/PNG/dotnet_bot.png i pliku SVG w folderze Resources/Images/SVG/dotnet_bot.svg , ponieważ pliki SVG są konwertowane na pliki PNG w czasie kompilacji.

Błąd wystąpi również w przypadku użycia atrybutu Include w elemencie MauiImage w celu uwzględnienia wszystkich obrazów w folderze, a następnie dołączenia określonego pliku obrazu:

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

Jeśli wystąpi ten błąd kompilacji, można go naprawić, upewniając się, że plik projektu nie zawiera zduplikowanych obrazów. W tym celu zmień dowolny MauiIcon plik lub MauiImage odwołujący się do określonego pliku, aby użyć atrybutu Update zamiast atrybutu Include :

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

Aby uzyskać informacje o atrybutach elementu elementu MSBuild, zobacz Element elementu (MSBuild): atrybuty i elementy.