Solución de problemas conocidos

  • Artículo

En este artículo se describen algunos de los problemas conocidos con .NET Multi-Platform App UI (.NET MAUI) y cómo puedes resolverlos o solucionarlos. En el repositorio de .NET MAUI también se detallan algunos problemas conocidos.

No se pueden encontrar las cargas de trabajo de .NET MAUI

Hay dos opciones para instalar las cargas de trabajo de .NET MAUI:

  1. Visual Studio en Windows puede instalar archivos .msi para cada paquete de carga de trabajo.
  2. Comandos de dotnet workload install.

En Windows, si ejecutas un dotnet workload install después de instalar .NET MAUI a través del instalador de Visual Studio, Visual Studio puede entrar en un estado en el que no puede encontrar las cargas de trabajo de .NET MAUI. Recibirás errores de compilación que te indicarán que instales las cargas de trabajo de .NET MAUI y es posible entrar en un estado en el que las cargas de trabajo no se puedan reparar ni reinstalar. Para obtener más información, consulta el problema de GitHub dotnet/sdk#22388.

Windows

La solución a este problema en Windows es desinstalar las cargas de trabajo de .NET MAUI a través de la CLI, desinstalar los SDK de .NET en Panel de control y desinstalar las cargas de trabajo de .NET MAUI en Visual Studio. Estas desinstalaciones se pueden realizar con el siguiente proceso:

  1. Ejecuta dotnet workload uninstall maui si alguna vez has usado los comandos dotnet workload install.
  2. Desinstala los instaladores independientes del SDK de .NET en el Panel de control. Estos instaladores tienen nombres similares a Microsoft .NET SDK 6.0.300.
  3. En cada instancia de Visual Studio, desinstala el desarrollo de .NET Multi-Platform App UI y las cargas de trabajo de Visual Studio de desarrollo del escritorio de .NET.

Luego, comprueba si hay archivos .msi adicionales que deben desinstalarse ejecutando el comando siguiente:

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

Este comando reg query enumera los SDK de .NET 6+ que todavía están instalados en el equipo, como:

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 recibes una salida similar, debes copiar el GUID de cada paquete y desinstalar el paquete con el comando msiexec:

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

Después, debes seguir ejecutando el comando reg query hasta que no devuelva ningún resultado. Cuando ya no haya más resultados y se desinstalen todos los SDK de .NET 6+, también debes considerar la posibilidad de eliminar las siguientes carpetas:

  • 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.*

Después de seguir este proceso, deberías poder reinstalar .NET MAUI a través de Visual Studio o instalando la versión elegida del SDK de .NET y ejecutando el comando dotnet workload install maui.

Mac

El instalador y el actualizador de Visual Studio para Mac usan comandos dotnet workload install para instalar los archivos .pkg de .NET MAUI.

Dado que los archivos .pkg no se pueden desinstalar, el enfoque más sencillo para desinstalar las cargas de trabajo en un equipo Mac es ejecutar los siguientes comandos para eliminar las carpetas especificadas:

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

Después de ejecutar estos comandos, deberías poder reinstalar .NET MAUI a través de Visual Studio para Mac, o instalando la versión del SDK de .NET elegida y ejecutando el comando dotnet workload install maui.

La versión de la plataforma no está presente

Es posible que Visual Studio no resuelva las cargas de trabajo necesarias si intentas compilar un proyecto y recibes un error similar al texto siguiente:

La versión de la plataforma no está presente para una o varias plataformas de destino, aunque hayan especificado una plataforma: net8.0-android, net8.0-ios, net8.0-maccatalyst

Este problema suele producirse por tener instalados un SDK de x86 y x64, y se está utilizando la versión x86. Visual Studio y .NET MAUI requieren el SDK de .NET x64. Si el sistema operativo tiene una variable PATH en todo el sistema que resuelve primero el SDK de x86, debes corregir este problema quitando el SDK de .NET x86 de la variable PATH o promocionando el SDK de .NET x64 para que se resuelva primero. Para obtener más información sobre cómo solucionar problemas de resolución del SDK x86 frente a x64, consulta Instalación de .NET en Windows: solución de problemas.

El tipo o el espacio de nombres 'Default' no existe

Al usar la API Contacts, es posible que veas el siguiente error relacionado con iOS y macOS:

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

Las plataformas iOS y macOS contienen un espacio de nombres raíz denominado Contacts. Este conflicto provoca un conflicto para esas plataformas con el espacio de nombres Microsoft.Maui.ApplicationModel.Communication, que contiene un tipo Contacts. El Microsoft.Maui.ApplicationModel.Communication espacio de nombres se importa automáticamente con la configuración <ImplicitUsings> en el archivo del proyecto.

Para escribir código que también se compile para iOS y macOS, califique completamente el tipo Contacts. Como alternativa, facilita una directiva using en la parte superior del archivo de código para asignar el espacio de nombres Communication:

using Communication = Microsoft.Maui.ApplicationModel.Communication;

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

Xcode no está instalado actualmente o no se ha encontrado

Después de instalar las herramientas de línea de comandos de Xcode con xcode-select --install, Visual Studio para Mac podría mostrar un mensaje de tipo "Xcode no está instalado actualmente o no se ha encontrado" al intentar compilar aplicaciones de .NET MAUI destinadas a iOS o Mac Catalyst. En este escenario, comprueba que también tienes Xcode instalado desde App Store. Después, inicia Xcode y ve a Xcode>Preferences > Locations > Command Line Tools y comprueba si el menú desplegable está vacío. Si está vacío, selecciona la lista desplegable y, después, selecciona la ubicación de las herramientas de línea de comandos de Xcode. Después cierra Xcode y, luego, reinicia Visual Studio para Mac.

No se pudo encontrar un lote de aplicaciones de Xcode válido

Si recibes el error "No se pudo encontrar un lote de de aplicaciones Xcode válido en '/Library/Developer/CommandLineTools'" al intentar compilar aplicaciones de .NET MAUI destinadas a iOS o Mac Catalyst, prueba la solución descrita en Xcode no está instalado actualmente o no se puede encontrar. Si sigues sin poder acceder a la lista desplegable Xcode > Preferencias > Ubicaciones > Herramientas de línea de comandos ejecuta el siguiente comando:

sudo xcode-select --reset

No se puede encontrar la versión de Xcode

En algunos escenarios, la compilación de una aplicación MAUI de .NET en iOS o Mac Catalyst puede intentar usar una versión de Xcode que ya no esté instalada en el equipo. Cuando esto ocurra, recibirá un mensaje de error similar al siguiente:

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

Al compilar una aplicación, .NET iOS y .NET Mac Catalyst usan el siguiente proceso para determinar qué versión de Xcode se va a usar:

  1. Si la variable de entorno MD_APPLE_SDK_ROOT esté establecida, use su valor.
  2. Si existe el archivo ~/Library/Preferences/Xamarin/Settings.plist, use el valor definido dentro de él.
  3. Use el valor de xcode-select -p.
  4. Use /Applications/Xcode.app.

Por lo tanto, el enfoque recomendado para especificar la ubicación de Xcode en la máquina es establecer la variable de entorno MD_APPLE_SDK_ROOT en la ruta de acceso de la versión de Xcode. Para obtener más información, consulte Compilación con una versión específica de Xcode.

Después, puede eliminar de forma segura ~/Library/Preferences/Xamarin/Settings.plist de su equipo.

Diagnóstico de problemas en las aplicaciones híbridas de Blazor.

BlazorWebView cuenta con un registro integrado que puede ayudarte a diagnosticar problemas en la aplicación híbrida de Blazor. Hay dos pasos para habilitar este registro:

  1. Habilite BlazorWebView y los componentes relacionados para registrar la información de diagnóstico.
  2. Configura un registrador para que escriba la salida del registro donde puedas verla.

Para obtener más información, consulta Diagnóstico de problemas en las aplicaciones híbridas de Blazor

Deshabilitar el empaquetado de imágenes

Con fines de solucionar problemas, el empaquetado de recursos de imagen se puede deshabilitar estableciendo la propiedad de compilación $(EnableMauiImageProcessing) en false en en el primer nodo <PropertyGroup> del archivo de proyecto:

<EnableMauiImageProcessing>false</EnableMauiImageProcessing>

Deshabilitar el empaquetado de la pantalla de presentación

Con fines de solucionar problemas, la generación de recursos de la pantalla de presentación se puede deshabilitar estableciendo la propiedad de compilación $(EnableSplashScreenProcessing) en false en el primer nodo <PropertyGroup> del archivo de proyecto:

<EnableSplashScreenProcessing>false</EnableSplashScreenProcessing>

Deshabilitar el empaquetado de fuentes

Con fines de solucionar problemas, el empaquetado de recursos de fuente se puede deshabilitar estableciendo la propiedad de compilación $(EnableMauiFontProcessing) en false en el primer nodo <PropertyGroup> del archivo de proyecto:

<EnableMauiFontProcessing>false</EnableMauiFontProcessing>

Deshabilitar el empaquetado de archivos de recursos

Con fines de solucionar problemas, el empaquetado de de archivos de recursos se puede deshabilitar estableciendo la propiedad de compilación $(EnableMauiAssetProcessing) en false en el primer nodo <PropertyGroup> del archivo de proyecto:

<EnableMauiAssetProcessing>false</EnableMauiAssetProcessing>

Generar una pantalla de presentación en blanco

Con fines de solucionar problemas, se puede generar una pantalla de presentación en blanco si no se tiene un elemento <MauiSplashScreen> y no se tiene una pantalla de presentación personalizada. Esto se puede lograr estableciendo la propiedad de compilación $(EnableBlankMauiSplashScreen) en true en el primer nodo <PropertyGroup> del archivo del proyecto:

<EnableBlankMauiSplashScreen>true</EnableBlankMauiSplashScreen>

La generación de una pantalla de presentación en blanco reemplazará cualquier pantalla de presentación personalizada y provocará el rechazo de la tienda de aplicaciones. Sin embargo, puede ser un enfoque útil en las pruebas para asegurarte de que la interfaz de usuario de la aplicación es correcta.

Errores de nombre de archivo de imagen duplicados

Es posible que encuentres errores de compilación sobre los nombres de archivo de imagen duplicados:

Se detectaron uno o varios nombres de archivo duplicados. Todos los nombres de archivo de salida de imagen deben ser únicos.

Esto ocurre para los elementos MauiIcon y MauiImage porque desde .NET 8, .NET MAUI comprueba que no hay nombres de archivo de recursos de imagen duplicados.

El error se producirá cuando tengas nombres de archivo idénticos en varias carpetas y, en determinadas circunstancias, cuando tengas nombres de archivo idénticos con extensiones diferentes en carpetas diferentes. Por ejemplo, el error de compilación se producirá para un archivo PNG en Resources/Images/PNG/dotnet_bot.png y un archivo SVG en Resources/Images/SVG/dotnet_bot.svg porque los archivos SVG se convierten en archivos PNG en tiempo de compilación.

El error también se producirá si usa el atributo Include en un elemento MauiImage para incluir todas las imágenes de una carpeta y, después, también se incluye un archivo de imagen específico:

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

Si recibes este error de compilación, lo puedes corregir asegurándote de que el archivo del proyecto no incluya imágenes duplicadas. Para ello, cambia cualquier MauiIcon o MauiImage que haga referencia a un archivo específico para usar el atributo Update en lugar del atributo Include:

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

Para obtener información sobre los atributos del elemento de MSBuild, consulta Elemento Item (MSBuild): Atributos y elementos.