Soluções de problemas conhecidos

Artigo
03/20/2024

Este artigo descreve alguns dos problemas conhecidos da interface do usuário dos aplicativos multiplataforma do .NET (.NET MAUI) e como você pode resolvê-los ou contorná-los. O Repositório .NET MAUI também detalha alguns problemas conhecidos.

Não é possível localizar as cargas de trabalho do .NET MAUI

Há duas opções para instalar as cargas de trabalho do .NET MAUI:

O Visual Studio no Windows pode instalar arquivos .msi em cada pacote da carga de trabalho.
dotnet workload install comandos.

No Windows, se você executar um dotnet workload install depois de instalar o .NET MAUI pelo instalador do Visual Studio, o Visual Studio poderá inserir um estado em que não consegue localizar as cargas de trabalho do .NET MAUI. Você receberá erros de compilação solicitando a instalação das cargas de trabalho do .NET MAUI, e é possível entrar em um estado em que as cargas de trabalho não podem ser reparadas ou reinstaladas. Para obter mais informações, consulte o problema do GitHub dotnet/sdk#22388.

Windows

A solução para esse problema no Windows é desinstalar as cargas de trabalho do .NET MAUI pela CLI, desinstalar os SDKs do .NET no Painel de Controle e desinstalar as cargas de trabalho do .NET MAUI no Visual Studio. Essas desinstalações podem ser realizadas com o seguinte processo:

Execute dotnet workload uninstall maui se você já usou os comandos dotnet workload install.
Desinstale todos os instaladores autônomos do SDK do .NET do Painel de Controle. Esses instaladores têm nomes semelhantes a Microsoft .NET SDK 6.0.300.
Em todas as instâncias do Visual Studio, desinstale o desenvolvimento da interface do usuário do Aplicativo Multiplataforma do .NET e as cargas de trabalho do Visual Studio de desenvolvimento da área de trabalho do .NET.

Em seguida, verifique se há arquivos .msi adicionais que precisam ser desinstalados executando o seguinte comando:

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

Este comando reg query lista os SDKs do .NET 6+ que ainda estão instalados no seu computador, 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

Se você receber uma saída semelhante, deverá copiar o GUID de cada pacote e desinstalar o pacote com o comando msiexec :

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

Em seguida, você deve continuar executando o comando reg query até que ele não retorne nenhum resultado. Depois que não houver mais resultados e todos os SDKs do .NET 6+ estiverem desinstalados, você também deverá considerar excluir as seguintes pastas:

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

Depois de seguir esse processo, você poderá reinstalar o .NET MAUI pelo Visual Studio ou instalar a versão escolhida do SDK do .NET e executar o comando. dotnet workload install maui .

Mac

O instalador e o atualizador do Visual Studio para Mac usam os comandos dotnet workload install para instalar os arquivos de .pkg do .NET MAUI.

Como os arquivos .pkg não podem ser desinstalados, a abordagem mais simples para desinstalar as cargas de trabalho em um Mac é executar os seguintes comandos para excluir as pastas especificadas:

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

Depois de executar esses comandos, você poderá reinstalar o .NET MAUI pelo Visual Studio para Mac ou instalar a versão do SDK do .NET escolhida e executando o comando dotnet workload install maui.

A versão da plataforma não está presente

É possível que o Visual Studio não esteja resolvendo as cargas de trabalho necessárias se você tentar compilar um projeto e receber um erro semelhante ao texto a seguir:

A versão da plataforma não está presente em uma ou mais estruturas de destino, mesmo que elas tenham especificado uma plataforma: net8.0-android, net8.0-ios, net8.0-maccatalyst

Normalmente, esse problema resulta da instalação de um SDK x86 e x64, e a versão x86 está sendo usada. O Visual Studio e o .NET MAUI exigem o SDK do .NET x64. Se seu sistema operacional tiver uma variável de PATH no sistema que está resolvendo o SDK x86 primeiro, você precisará corrigir isso removendo o SDK do .NET x86 da variável PATH ou promovendo o SDK do .NET x64 para que ele seja resolvido primeiro. Para obter mais informações sobre como solucionar problemas de resolução do SDK x86 vs x64, consulte Instalar o .NET no Windows – Solução de problemas.

O tipo ou namespace "Default" não existe

Ao usar Contacts API, você poderá ver o seguinte erro relacionado ao iOS e ao macOS:

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

As plataformas iOS e macOS contêm um namespace raiz chamado Contacts. Esse conflito causa um conflito nara essas plataformas com o namespace Microsoft.Maui.ApplicationModel.Communication, que contém um tipo Contacts. O namespace Microsoft.Maui.ApplicationModel.Communication é importado automaticamente pela configuração <ImplicitUsings> no arquivo de projeto.

Para escrever o código que também é compilado para iOS e macOS, qualifique totalmente o tipo de Contacts. Como alternativa, forneça uma diretiva using na parte superior do arquivo de código para mapear o namespace Communication:

using Communication = Microsoft.Maui.ApplicationModel.Communication;

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

O Xcode não está instalado no momento ou não pôde ser encontrado

Depois de instalar as ferramentas de linha de comando do Xcode usando xcode-select --install, o Visual Studio para Mac pode mostrar uma mensagem "O Xcode não está instalado no momento ou não foi encontrado" ao tentar criar aplicativos .NET MAUI direcionados ao iOS ou ao Mac Catalyst. Nesse cenário, verifique se você também tem o Xcode instalado na App Store. Em seguida, inicie o Xcode e acesse Xcode > Preferências > Locais > Ferramentas de Linha de Comando e verifique se a lista suspensa está vazia. Se estiver vazio, selecione a lista suspensa e selecione o local das ferramentas da linha de comando do Xcode. Em seguida, feche o Xcode e reinicie o Visual Studio para Mac.

Não foi possível encontrar um pacote de aplicativo Xcode válido

Se você receber o erro "Não foi possível encontrar um pacote de aplicativo Xcode válido em '/Library/Developer/CommandLineTools'" ao tentar criar os aplicativos .NET MAUI destinados ao iOS ou ao Mac Catalyst, experimente a solução descrita em O Xcode não está instalado no momento ou não pôde ser encontrado. Se você ainda não conseguir acessar a lista suspensa Xcode > Preferências > Locais > Ferramentas de Linha de Comando, execute o seguinte comando:

sudo xcode-select --reset

A versão do Xcode não pode ser localizada

Em alguns cenários, a criação de um aplicativo do .NET MAUI no iOS ou Mac Catalyst pode tentar usar uma versão do Xcode que não está mais instalada no seu computador. Quando isso ocorrer, você receberá uma mensagem de erro semelhante a:

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

Ao criar um aplicativo, o .NET iOS e o .NET Mac Catalyst usam o seguinte processo para determinar qual versão do Xcode usar:

Se a variável de ambiente MD_APPLE_SDK_ROOT estiver definida, use seu valor.
Se o arquivo ~/Library/Preferences/Xamarin/Settings.plist existir, use o valor definido nele.
Use o valor de xcode-select -p.
Use /Applications/Xcode.app.

Portanto, a abordagem recomendada para especificar o local do Xcode no seu computador é definir a variável de ambiente MD_APPLE_SDK_ROOT no caminho da versão do Xcode. Para obter mais informações, consulte Compilação com uma versão específica do Xcode.

Em seguida, você pode excluir com segurança ~/Library/Preferences/Xamarin/Settings.plist do seu computador.

Diagnosticar problemas nos aplicativos Híbridos Blazor

BlazorWebView tem log interno que pode ajudá-lo a diagnosticar problemas no seu aplicativo Híbrido Blazor. Há duas etapas para habilitar esse registro em log:

Habilite BlazorWebView e componentes relacionados para registrar informações de diagnóstico.
Configure um agente para gravar a saída de log no local em que você pode exibi-la.

Para obter mais informações, consulte Problemas de diagnóstico nos aplicativos Híbridos Blazor.

Desabilitar o empacotamento de imagem

Quanto aos fins de solução de problemas, o empacotamento de recursos de imagem pode ser desabilitado definindo a propriedade de compilação $(EnableMauiImageProcessing) como false no primeiro nó <PropertyGroup> no arquivo de projeto:

<EnableMauiImageProcessing>false</EnableMauiImageProcessing>

Desabilitar o empacotamento de tela inicial

Quanto aos fins de solução de problemas, a geração de recursos de tela inicial pode ser desabilitada definindo a propriedade de compilação $(EnableSplashScreenProcessing) como false no primeiro nó <PropertyGroup> no arquivo de projeto:

<EnableSplashScreenProcessing>false</EnableSplashScreenProcessing>

Desabilitar o empacotamento de fontes

Quanto aos fins de solução de problemas, o empacotamento de recursos de fonte pode ser desabilitado definindo a propriedade de compilação $(EnableMauiFontProcessing) como false no primeiro nó <PropertyGroup> no arquivo de projeto:

<EnableMauiFontProcessing>false</EnableMauiFontProcessing>

Desabilitar o empacotamento de arquivo de ativo

Quanto aos fins de solução de problemas, o empacotamento de recursos de arquivo de ativo pode ser desabilitado definindo a propriedade de compilação $(EnableMauiAssetProcessing) como false no primeiro nó <PropertyGroup> no seu arquivo de projeto:

<EnableMauiAssetProcessing>false</EnableMauiAssetProcessing>

Gerar uma tela inicial em branco

Quanto aos fins de solução de problemas, uma tela inicial em branco pode ser gerada se você não tiver um item <MauiSplashScreen> e não tiver uma tela inicial personalizada. Isso pode ser feito definindo a propriedade de compilação $(EnableBlankMauiSplashScreen) como true no primeiro nó <PropertyGroup> no seu arquivo de projeto:

<EnableBlankMauiSplashScreen>true</EnableBlankMauiSplashScreen>

Gerar uma tela inicial em branco substituirá qualquer tela inicial personalizada e ocasionará a rejeição da loja de aplicativos. Porém, pode ser uma abordagem útil no teste para garantir que a interface do usuário do aplicativo esteja correta.

Erros de nome de arquivo de imagem duplicado

Você pode encontrar erros de compilação dos nomes de arquivo de imagem duplicados:

Um ou mais nomes de arquivo duplicados foram detectados. Todos os nomes de arquivo de saída de imagem devem ser exclusivos.

Isso ocorre nos itens MauiIcon e MauiImage porque, do .NET 8, o .NET MAUI verifica se não há nomes de arquivo de recurso de imagem duplicados.

O erro ocorrerá quando você tiver nomes de arquivos idênticos em várias pastas e, em determinadas circunstâncias, quando você tiver nomes de arquivos idênticos com extensões diferentes em pastas diferentes. Por exemplo, o erro de compilação ocorrerá em um arquivo PNG em Resources/Images/PNG/dotnet_bot.png e em um arquivo SVG em Resources/Images/SVG/dotnet_bot.svg, porque os arquivos SVG são convertidos em arquivos PNG no momento da compilação.

O erro também ocorrerá se você usar o atributo Include em um item MauiImage para incluir todas as imagens em uma pasta e também incluir um arquivo de imagem específico:

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

Se você receber esse erro de compilação, ele poderá ser corrigido garantindo que o arquivo de projeto não inclua imagens duplicadas. Para fazer isso, altere qualquer MauiIcon ou MauiImage que faça referência a um arquivo específico para usar o atributo Update em vez de o atributo Include:

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

Para obter informações sobre atributos de elemento de item do MSBuild, consulte Elemento do item (MSBuild): Atributos e elementos.