Risoluzione dei problemi noti

Questo articolo descrive alcuni dei problemi noti relativi a .NET Multi-platform App UI (.NET MAUI) e come è possibile risolverli o aggirarli. Il repository MAUI .NET illustra anche alcuni problemi noti.

Non è possibile individuare i carichi di lavoro MAUI .NET

Sono disponibili due opzioni per l'installazione dei carichi di lavoro MAUI .NET:

1. Visual Studio in Windows può installare .msi file per ogni pacchetto del carico di lavoro.
2. dotnet workload install comandi.

Su Windows, se si esegue un dotnet workload install dopo aver installato .NET MAUI tramite il programma di installazione di Visual Studio, Visual Studio può entrare in uno stato in cui non è possibile individuare i carichi di lavoro .NET MAUI. Si riceveranno errori di compilazione che informano di installare i carichi di lavoro MAUI .NET ed è possibile immettere uno stato in cui i carichi di lavoro non possono essere ripristinati o reinstallati. Per altre informazioni, vedere il problema di GitHub dotnet/sdk#22388.

Windows

La soluzione a questo problema in Windows consiste nel disinstallare i carichi di lavoro MAUI .NET tramite l'interfaccia della riga di comando, disinstallare gli SDK .NET nel Pannello di controllo e disinstallare i carichi di lavoro MAUI .NET in Visual Studio. Queste disinstallazioni possono essere eseguite con il processo seguente:

1. Eseguire dotnet workload uninstall maui se hai mai utilizzato i comandi dotnet workload install.
2. Disinstallare tutti i programmi di installazione autonomi di .NET SDK dal Pannello di controllo. Questi programmi di installazione hanno nomi simili a Microsoft .NET SDK 6.0.300.
3. In ogni istanza di Visual Studio, disinstallare i carichi di lavoro per lo sviluppo di applicazioni desktop .NET e per lo sviluppo dell'interfaccia utente di app multipiattaforma .NET.

Verificare quindi se sono presenti file aggiuntivi .msi che devono essere disinstallati eseguendo il comando seguente:

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

Questo reg query comando elenca gli SDK .NET 6+ ancora installati nel computer, ad esempio:

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

Se si riceve un output simile, è necessario copiare il GUID per ogni pacchetto e disinstallare il pacchetto con il msiexec comando :

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

È quindi consigliabile continuare a eseguire il reg query comando fino a quando non restituisce alcun risultato. Quando non sono presenti altri risultati e tutti gli SDK .NET 6+ vengono disinstallati, è anche consigliabile eliminare le cartelle seguenti:

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

Dopo aver seguito questo processo, dovrebbe essere possibile reinstallare .NET MAUI tramite Visual Studio o installando la versione di .NET SDK scelta ed eseguendo il dotnet workload install maui comando .

La versione della piattaforma non è presente

Visual Studio potrebbe non risolvere i carichi di lavoro necessari se si tenta di compilare un progetto e si riceve un errore simile al testo seguente:

La versione della piattaforma non è presente per uno o più framework di destinazione, anche se hanno specificato una piattaforma: net8.0-android, net8.0-ios, net8.0-maccatalyst

Questo problema deriva in genere dall'avere installato un SDK x86 e un SDK x64, mentre viene utilizzata la versione x86. Visual Studio e .NET MAUI richiedono .NET SDK x64. Se nel sistema operativo è presente una variabile a livello PATH di sistema che risolve prima x86 SDK, è necessario correggerla rimuovendo x86 .NET SDK dalla PATH variabile o promuovendo x64 .NET SDK in modo che venga risolto per primo. Per altre informazioni sulla risoluzione dei problemi relativi a x86 e x64 SDK, vedere Installare .NET in Windows - Risoluzione dei problemi.

Il tipo o lo spazio dei nomi 'Default' non esiste

Quando si usa l'API, è possibile che venga visualizzato l'errore Contactsseguente relativo a iOS e macOS:

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

Le piattaforme iOS e macOS contengono uno spazio dei nomi radice denominato Contacts. Questo conflitto causa un conflitto per tali piattaforme con lo spazio dei nomi Microsoft.Maui.ApplicationModel.Communication, che contiene un tipo Contacts. Lo Microsoft.Maui.ApplicationModel.Communication spazio dei nomi viene importato automaticamente dall'impostazione <ImplicitUsings> nel file di progetto.

Per scrivere codice che venga compilato anche per iOS e macOS, qualificare completamente il tipo Contacts. In alternativa, fornire una using direttiva all'inizio del file di codice per eseguire il mapping dello Communication spazio dei nomi:

using Communication = Microsoft.Maui.ApplicationModel.Communication;

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

Xcode non è attualmente installato o non è stato trovato

Dopo aver installato gli strumenti da riga di comando Xcode usando xcode-select --install, Visual Studio Code potrebbe mostrare un messaggio "Xcode non è attualmente installato o non è stato trovato" quando si tenta di compilare app MAUI .NET destinate a iOS o Mac Catalyst. In questo scenario verificare che sia installato anche Xcode dall'App Store. Avviare quindi Xcode e passare a Xcode > Preferences > Locations Command > Line Tools e verificare se l'elenco a discesa è vuoto. Se è vuoto, selezionare il menu a discesa e quindi selezionare il percorso degli strumenti da riga di comando Xcode. Chiudere quindi Xcode e riavviare Visual Studio Code.

Impossibile trovare un bundle di app Xcode valido

Se viene visualizzato l'errore "Impossibile trovare un bundle di app Xcode valido in '/Library/Developer/CommandLineTools'" quando si tenta di compilare app MAUI .NET destinate a iOS o Mac Catalyst, provare la soluzione descritta in Xcode non è attualmente installata o non è stata trovata. Se non è ancora possibile accedere all'elenco a discesa Xcode > Preferenze > Posizioni > Strumenti da Riga di Comando, eseguire il comando seguente:

sudo xcode-select --reset

Non è possibile individuare la versione Xcode

In alcuni scenari, la compilazione di un'app MAUI .NET in iOS o Mac Catalyst potrebbe tentare di usare una versione di Xcode non più installata nel computer. Quando si verifica questo problema, si riceverà un messaggio di errore simile al seguente:

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

Quando si compila un'app, .NET per iOS e .NET per Mac Catalyst usa il processo seguente per determinare quale versione di Xcode usare:

1. Se la MD_APPLE_SDK_ROOT variabile di ambiente è impostata, usarne il valore. Questa variabile di ambiente verrà deprecata in una versione futura; non usarlo.
2. Se il file ~/Library/Preferences/Xamarin/Settings.plist o ~/Library/Preferences/maui/Settings.plist esiste, usare il valore definito al suo interno. Questi file saranno deprecati in una versione futura; non usarli.
3. Usare il valore di xcode-select -p.
4. Usa /Applications/Xcode.app.

L'approccio consigliato per specificare la posizione di Xcode nel computer consiste nel:

1. Eliminare i file ~/Library/Preferences/Xamarin/Settings.plist o ~/Library/Preferences/maui/Settings.plist (se esistenti).
2. Usare xcode-select --switch ... per selezionare la versione di Xcode del sistema o impostare la DEVELOPER_DIR variabile di ambiente sul percorso di Xcode. Per altre informazioni, vedere Creare con una versione specifica di Xcode.

Diagnosticare i problemi nelle app ibride Blazor

BlazorWebView include la registrazione predefinita che consente di diagnosticare i problemi nell'app Blazor Hybrid. Per abilitare questa registrazione sono necessari due passaggi:

1. Abilitare e i componenti correlati per registrare BlazorWebView le informazioni di diagnostica.
2. Configurare un logger per scrivere l'output del log in cui è possibile visualizzarlo.

Per altre informazioni, vedere Diagnosi dei problemi nelle app ibride Blazor.

Disabilitare la creazione di pacchetti di immagini

Ai fini della risoluzione dei problemi, l'impacchettamento delle risorse immagine può essere disabilitato impostando la proprietà di $(EnableMauiImageProcessing) compilazione su false nel primo nodo <PropertyGroup> del file di progetto.

<EnableMauiImageProcessing>false</EnableMauiImageProcessing>

Disabilitare il packaging della schermata iniziale

Per la risoluzione dei problemi, la generazione di risorse della schermata iniziale può essere disabilitata impostando la proprietà di compilazione $(EnableSplashScreenProcessing) su false nel primo nodo <PropertyGroup> del tuo file di progetto:

<EnableSplashScreenProcessing>false</EnableSplashScreenProcessing>

Disabilitare l'impacchettamento dei font

Ai fini della risoluzione dei problemi, il confezionamento delle risorse dei font può essere disabilitato impostando il valore della proprietà di build $(EnableMauiFontProcessing) su false nel primo nodo <PropertyGroup> del file di progetto:

<EnableMauiFontProcessing>false</EnableMauiFontProcessing>

Disabilita l'impacchettamento dei file di risorse

Ai fini della risoluzione dei problemi, l'impacchettamento delle risorse del file asset può essere disabilitato impostando la proprietà di compilazione $(EnableMauiAssetProcessing) su false nel primo nodo <PropertyGroup> del file di progetto.

<EnableMauiAssetProcessing>false</EnableMauiAssetProcessing>

Generare una schermata iniziale vuota

Ai fini della risoluzione dei problemi, è possibile generare una schermata iniziale vuota se non si dispone di un <MauiSplashScreen> elemento e non si dispone di una schermata iniziale personalizzata. A tale scopo, impostare la proprietà di $(EnableBlankMauiSplashScreen) compilazione su true nel primo <PropertyGroup> nodo del file di progetto:

<EnableBlankMauiSplashScreen>true</EnableBlankMauiSplashScreen>

La generazione di una schermata iniziale vuota eseguirà l'override di qualsiasi schermata iniziale personalizzata e causerà il rifiuto dell'App Store. Tuttavia, può essere un approccio utile nei test per assicurarsi che l'interfaccia utente dell'app sia corretta.

Errori di file immagine con nomi duplicati

Potrebbero verificarsi errori di compilazione relativi ai nomi file di immagine duplicati:

Sono stati rilevati uno o più nomi di file duplicati. Tutti i nomi file di output dell'immagine devono essere univoci.

Ciò si verifica per gli elementi MauiIcon e MauiImage perché, a partire da .NET 8, .NET MAUI verifica che non siano presenti nomi di file di risorse immagine duplicati.

L'errore si verificherà quando si dispone di nomi file identici in più cartelle e in determinate circostanze quando si dispone di nomi file identici con estensioni diverse in cartelle diverse. Ad esempio, l'errore di compilazione si verificherà per un file PNG in Resources/Images/PNG/dotnet_bot.png e un file SVG in Resources/Images/SVG/dotnet_bot.svg perché i file SVG vengono convertiti in file PNG in fase di compilazione.

L'errore si verifica anche se si usa l'attributo Include in un MauiImage elemento per includere tutte le immagini in una cartella e quindi includere anche un file di immagine specifico:

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

Se viene visualizzato questo errore di compilazione, può essere corretto assicurandosi che il file di progetto non includa immagini duplicate. A tale scopo, modificare uno MauiIcon o MauiImage che faccia riferimento a un file specifico per usare l'attributo Update anziché l'attributo Include :

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

Per informazioni sugli attributi dell'elemento MSBuild, vedere Elemento Item (MSBuild): Attributi ed elementi.