Résolution des problèmes connus

Article
03/20/2024

Cet article décrit certains quelques-uns des problèmes connus liés à .NET Multi-platform App UI (.NET MAUI), et comment vous pouvez résoudre ou contourner ces problèmes. Le dépôt .NET MAUI détaille également certains problèmes connus.

Impossible de localiser les charges de travail .NET MAUI

Il existe deux options pour installer les charges de travail .NET MAUI :

Visual Studio sur Windows peut installer des fichiers .msi pour chaque pack de charge de travail.
Des commandes dotnet workload install.

Sur Windows, si vous exécutez une commande dotnet workload install après avoir installé .NET MAUI via le programme d’installation de Visual Studio, Visual Studio peut entrer dans un état où il ne peut pas localiser les charges de travail .NET MAUI. Vous recevrez des erreurs de build vous indiquant d’installer les charges de travail .NET MAUI, et il est possible d’entrer un état où les charges de travail ne peuvent pas être réparées ou réinstallées. Pour plus d’informations, consultez le problème GitHub dotnet/sdk#22388.

Windows

La solution à ce problème sur Windows consiste à désinstaller les charges de travail .NET MAUI via l’interface CLI, à désinstaller les Kits de développement logiciel (SDK) .NET dans le Panneau de configuration et à désinstaller les charges de travail .NET MAUI dans Visual Studio. Ces désinstallations peuvent être effectuées avec le processus suivant :

Exécutez dotnet workload uninstall maui si vous avez déjà utilisé les commandes dotnet workload install.
Désinstallez les programmes d’installation autonomes du Kit de développement logiciel (SDK) .NET à partir du Panneau de configuration. Ces programmes d’installation ont des noms similaires à Microsoft .NET SDK 6.0.300.
Dans chaque instance de Visual Studio, désinstallez le développement de .NET Multi-platform App UI et les charges de travail Visual Studio de développement .NET Desktop.

Vérifiez ensuite s’il existe des fichiers .msi supplémentaires qui doivent être désinstallés en exécutant la commande suivante :

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

Cette commande reg query liste les Kits de développement logiciel (SDK) .NET 6+ qui sont toujours installés sur votre machine, par exemple :

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

Si vous recevez une sortie similaire, vous devez copier le GUID de chaque package et désinstaller le package avec la commande msiexec :

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

Ensuite, vous devez continuer à exécuter la commande reg query jusqu’à ce qu’elle ne retourne plus aucun résultat. Une fois qu’il n’y a plus de résultats et que tous les Kits de développement logiciel (SDK) .NET 6+ sont désinstallés, vous devez également envisager de supprimer les dossiers suivants :

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

Après avoir suivi ce processus, vous devez être en mesure de réinstaller .NET MAUI via Visual Studio, ou en installant la version du Kit de développement logiciel (SDK) .NET choisie et en exécutant la commande dotnet workload install maui.

Mac

Le programme d’installation et le programme de mise à jour de Visual Studio pour Mac utilisent des commandes dotnet workload install pour installer les fichiers .pkg de .NET MAUI.

Comme les fichiers .pkg ne peuvent pas être désinstallés, l’approche la plus simple pour désinstaller les charges de travail sur un Mac consiste à exécuter les commandes suivantes pour supprimer les dossiers spécifiés :

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

Après avoir exécuté ces commandes, vous devez être en mesure de réinstaller .NET MAUI via Visual Studio pour Mac, ou en installant la version du Kit de développement logiciel (SDK) .NET choisie et en exécutant la commande dotnet workload install maui.

La version de la plateforme n’est pas présente

Il est possible que Visual Studio ne puise pas résoudre les charges de travail requises si vous essayez de compiler un projet et que vous recevez une erreur similaire au texte suivant :

La version de la plateforme n’est pas présente pour un ou plusieurs frameworks cibles, même s’ils ont spécifié une plateforme : net8.0-android, net8.0-ios, net8.0-maccatalyst

Ce problème vient généralement du fait que des Kits de développement logiciel (SDK) x86 et x64 sont installés, et que la version x86 est utilisée. Visual Studio et .NET MAUI nécessitent le Kit de développement logiciel (SDK) .NET x64. Si votre système d’exploitation a une variable PATH à l’échelle du système qui résout d’abord le Kit de développement logiciel (SDK) x86, vous devez corriger cela en supprimant le Kit de développement logiciel (SDK) .NET x86 de la variable PATH, ou en promouvant le Kit de développement logiciel (SDK) .NET x64 afin qu’il soit résolu en premier. Pour plus d’informations sur la résolution des problèmes de résolution des Kits de développement logiciel (SDK) x86 et x64, consultez Installer .NET sur Windows – Résolution des problèmes.

Le type ou l’espace de noms « Default » n’existe pas

Quand vous utilisez l’API Contacts, vous pouvez voir l’erreur suivante liée à iOS et macOS :

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

Les plateformes iOS et macOS contiennent un espace de noms racine nommé Contacts. Ce conflit provoque à son tour un conflit pour ces plateformes avec l’espace de noms Microsoft.Maui.ApplicationModel.Communication, qui contient un type Contacts. L’espace de noms Microsoft.Maui.ApplicationModel.Communication est automatiquement importé par le paramètre <ImplicitUsings> dans le fichier projet.

Pour écrire du code qui se compile également pour iOS et macOS, qualifiez entièrement le type Contacts. Vous pouvez aussi fournir une directive using en haut du fichier de code pour mapper l’espace de noms Communication :

using Communication = Microsoft.Maui.ApplicationModel.Communication;

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

Xcode n’est actuellement pas installé ou est introuvable

Après avoir installé les outils en ligne de commande Xcode en utilisant xcode-select --install, Visual Studio pour Mac peut afficher un message « Xcode n’est actuellement pas installé ou est introuvable » quand vous tentez de générer des applications .NET MAUI ciblant iOS ou Mac Catalyst. Dans ce scénario, vérifiez que Xcode est également installé à partir de l’App Store. Ensuite, lancez Xcode, puis accédez à Xcode > Préférences > Emplacements > Outils en ligne de commande et vérifiez si la liste déroulante est vide. Si elle est vide, sélectionnez la liste déroulante, puis sélectionnez l’emplacement des outils en ligne de commande Xcode. Fermez ensuite Xcode, puis redémarrez Visual Studio pour Mac.

Impossible de trouver un ensemble d’applications Xcode valide

Si vous recevez l’erreur « Impossible de trouver un ensemble d’applications Xcode valide dans '/Library/Developer/CommandLineTools' » quand vous tentez de générer des applications .NET MAUI qui ciblent iOS ou Mac Catalyst, essayez la solution décrite dans Xcode n’est actuellement pas installé ou est introuvable. Si vous ne parvenez toujours pas à accéder à la liste déroulante Xcode > Préférences > Emplacements > Outils en ligne de commande, exécutez la commande suivante :

sudo xcode-select --reset

La version de Xcode est introuvable

Dans certains scénarios, la création d’une application .NET MAUI sur iOS ou Mac Catalyst peut tenter d’utiliser une version de Xcode qui n’est plus installée sur votre machine. Quand cela se produit, vous recevrez un message d’erreur similaire à :

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

Lors de la génération d’une application, .NET iOS et .NET Mac Catalyst utilisent le processus suivant pour déterminer la version de Xcode à utiliser :

Si la variable d’environnement MD_APPLE_SDK_ROOT est définie, utilisez sa valeur.
Si le fichier ~/Library/Preferences/Xamarin/Settings.plist existe, utilisez la valeur qui y est définie.
Utilisez la valeur de xcode-select -p.
Utiliser /Applications/Xcode.app.

Par conséquent, l’approche recommandée pour spécifier l’emplacement de Xcode sur votre machine consiste à définir la variable d’environnement MD_APPLE_SDK_ROOT sur le chemin d’accès de la version de Xcode. Pour plus d’informations, consultez Générer avec une version spécifique de Xcode.

Vous pouvez ensuite supprimer sans risques ~/Library/Preferences/Xamarin/Settings.plist de votre machine.

Diagnostiquer les problèmes dans les applications Blazor Hybrid

BlazorWebView a une journalisation intégrée qui peut vous aider à diagnostiquer les problèmes dans votre application Blazor Hybrid. Deux étapes sont nécessaires pour activer cette journalisation :

Activez BlazorWebView et les composants associés pour consigner les informations de diagnostic.
Configurez un enregistreur d’événements pour écrire la sortie du journal à un endroit où vous pouvez la visualiser.

Pour plus d’informations, consultez Diagnostic des problèmes dans les applications Blazor Hybrid.

Désactiver l’empaquetage d’images

Pour résoudre les problèmes, l’empaquetage des ressources d’image peut être désactivé en définissant la propriété de build $(EnableMauiImageProcessing) sur false dans le premier nœud <PropertyGroup> de votre fichier projet :

<EnableMauiImageProcessing>false</EnableMauiImageProcessing>

Désactiver l’empaquetage de l’écran de démarrage

Pour résoudre les problèmes, l’empaquetage de l’écran de démarrage peut être désactivé en définissant la propriété de build $(EnableSplashScreenProcessing) sur false dans le premier nœud <PropertyGroup> de votre fichier projet :

<EnableSplashScreenProcessing>false</EnableSplashScreenProcessing>

Désactiver l’empaquetage des polices

Pour résoudre les problèmes, l’empaquetage des polices peut être désactivé en définissant la propriété de build $(EnableMauiFontProcessing) sur false dans le premier nœud <PropertyGroup> de votre fichier projet :

<EnableMauiFontProcessing>false</EnableMauiFontProcessing>

Désactiver l’empaquetage des fichiers de ressources

Pour résoudre les problèmes, l’empaquetage des ressources de fichiers de ressources peut être désactivé en définissant la propriété de build $(EnableMauiAssetProcessing) sur false dans le premier nœud <PropertyGroup> de votre fichier projet :

<EnableMauiAssetProcessing>false</EnableMauiAssetProcessing>

Générer un écran de démarrage vide

Pour résoudre les problèmes, un écran de démarrage vide peut être généré si vous n’avez pas d’élément <MauiSplashScreen> et que vous n’avez pas d’écran de démarrage personnalisé. Pour cela, définissez la propriété de build $(EnableBlankMauiSplashScreen) sur true dans le premier nœud <PropertyGroup> de votre fichier projet :

<EnableBlankMauiSplashScreen>true</EnableBlankMauiSplashScreen>

La génération d’un écran de démarrage vide va remplacer l’écran de démarrage personnalisé et entraîner le rejet par l’App Store. Cependant, ce peut être une approche utile pour vérifier que l’interface utilisateur de votre application est correcte.

Erreurs de noms de fichier d’image en doublon

Vous pouvez rencontrer des erreurs de build concernant des noms de fichier d’image en doublon :

Un ou plusieurs noms de fichier en doublon ont été détectés. Tous les noms de fichier de sortie d’image doivent être uniques.

Ceci se produit pour les éléments MauiIcon et MauiImage en raison du fait que depuis .NET 8, .NET MAUI vérifie qu’il n’existe pas de noms de fichier de ressource d’image en doublon.

L’erreur se produit quand vous avez des noms de fichier identiques dans plusieurs dossiers et, dans certaines circonstances, quand vous avez des noms de fichier identiques avec des extensions différentes dans des dossiers différents. Par exemple, l’erreur de build se produit pour un fichier PNG dans Resources/Images/PNG/dotnet_bot.png et un fichier SVG dans Resources/Images/SVG/dotnet_bot.svg, car les fichiers SVG sont convertis en fichiers PNG au moment de la build.

L’erreur se produit également si vous utilisez l’attribut Include sur un élément MauiImage pour inclure toutes les images dans un dossier, puis que vous incluez également un fichier image spécifique :

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

Si vous recevez cette erreur de build, elle peut être corrigée en veillant à ce que votre fichier projet n’inclue pas d’images en doublon. Pour cela, modifiez les éléments MauiIcon ou MauiImage qui référencent un fichier spécifique de façon à utiliser l’attribut Update au lieu de l’attribut Include :

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

Pour plus d’informations sur les attributs des éléments Item MSBuild, consultez Élément Item (MSBuild) : Attributs et éléments.