Para começar a desenvolver aplicativos .NET MAUI nativos e multiplataforma no Windows, macOS ou Linux, instale o Visual Studio Code mais recente seguindo as etapas de instalação.
Pré-requisitos
Para criar, assinar e implantar aplicativos .NET MAUI para iOS, você precisará de:
Instalação
Para criar aplicativos .NET MAUI, você precisará instalar a versão mais recente Visual Studio Code.
No Visual Studio Code, na guia Extensões, pesquise ".NET MAUI" e instale a extensão .NET MAUI. A extensão do .NET MAUI instala automaticamente o Kit de Desenvolvimento do C# e as extensões do C#, que são necessárias para a execução da extensão do .NET MAUI.
Observação
A extensão .NET MAUI requer o C# Dev Kit e as extensões C#. Você deve entrar no Kit de Desenvolvimento do C# para usar a funcionalidade da extensão do .NET MAUI. Para obter mais informações, veja essa postagem do blog para saber mais sobre o C# Dev Kit e sua família de extensões.
Instalar cargas de trabalho do .NET e .NET MAUI
Instale o .NET 9.
No Windows, é recomendável usar o instalador do Visual Studio para gerenciar as instalações de carga de trabalho do .NET e .NET MAUI. As instruções sobre como usar o instalador do Visual Studio podem ser encontradas aqui.
No Linux, instale usando as instruções de instalação com script.
Instale a carga de trabalho do .NET MAUI.
No Windows, a menos que seja instalado por meio do instalador do Visual Studio, execute o seguinte comando em um terminal:
dotnet workload install maui
No macOS, execute o seguinte comando em um terminal:
sudo dotnet workload install maui
No Linux, execute o seguinte comando em um terminal:
dotnet workload install maui-android
Para depurar um aplicativo .NET MAUI no Visual Studio Code, você precisará ter uma plataforma de destino válida em relação ao sistema operacional do computador de desenvolvimento. A inclusão de plataformas de destino inválidas impedirá a construção do seu projeto. Você pode gerenciar as plataformas de destino no arquivo de projeto do seu aplicativo (.csproj):
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>net9.0-android;net9.0-ios;net9.0-maccatalyst</TargetFrameworks>
<TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net9.0-windows10.0.19041.0</TargetFrameworks>
| Seu sistema operacional |
Plataformas de destino com suporte |
| Windows |
Windows, Android |
| macOS |
Android, iOS, macOS |
| Linux |
Android |
iOS e macOS
Para depurar para um destino iOS ou macOS no Visual Studio Code:
- Instale a versão do Xcode exigida pela versão do MAUI do .NET que você está usando. Para obter informações, consulte Versões de lançamento. A última versão estável do Xcode pode ser baixada na Apple App Store.
- Execute
xcode-select --install em um terminal para adquirir as ferramentas de linha de comando do Xcode.
- Abra o Xcode e certifique-se de aceitar todos os contratos de licença.
Android
Para depurar para um destino do Android no Visual Studio Code:
- Instale o Microsoft OpenJDK 17.
- Instale o SDK do Android por meio de uma das seguintes abordagens:
- (Recomendado) Crie um novo projeto do .NET MAUI (
dotnet new maui) e use o destino InstallAndroidDependencies.
- Instale por meio do Visual Studio (somente Windows).
- Instale por meio do Android Studio.
- Instale por meio do gerenciador de pacotes preferido no Linux.
Solução de problemas
Você pode enfrentar problemas ao configurar a extensão do .NET MAUI para o Visual Studio Code. Para ver detalhes sobre erros relacionados à extensão, navegue até a janela Saída (CTRL/CMD + Shift + u) e selecione .NET MAUI no menu suspenso. Veja as seções abaixo para ajudar a resolver seu problema. Se você ainda estiver enfrentando problemas depois de seguir as etapas de solução de problemas, relate um problema.
Criação do projeto
Se você tentar criar um novo projeto e o explorador de arquivos continuar aparecendo em um loop infinito, talvez você não esteja selecionando uma pasta vazia. Verifique se não há arquivos ou pastas ocultos, crie uma nova pasta ou crie seu aplicativo .NET MAUI a partir da linha de comando usando dotnet new maui.
Usando o destino InstallAndroidDependencies
O .NET 9 tem um destino de build que ajuda a configurar seu ambiente Android para você. Execute o seguinte comando em um terminal para configurar seu computador e configurar seu ambiente Android:
dotnet build -t:InstallAndroidDependencies -f:net9.0-android -p:AndroidSdkDirectory="<AndroidSdkPath>" -p:JavaSdkDirectory="<JavaSdkPath>" -p:AcceptAndroidSDKLicenses=True
No comando acima:
AndroidSdkDirectory="<AndroidSdkPath>": instala ou atualiza as dependências do Android para o caminho absoluto especificado.
- Windows: o AndroidSdkPath sugerido é
%LOCALAPPDATA%/Android/Sdk.
- macOS: o AndroidSdkPath sugerido é
$HOME/Library/Android/sdk.
JavaSdkDirectory="<JavaSdkPath>": instala o Java no caminho absoluto especificado.AcceptAndroidSDKLicenses=True: aceita as licenças necessárias do Android para desenvolvimento.
Há um erro informando que o SDK do Android ou Java SDK não foi encontrado
- Abra a paleta de comandos (Ctrl/Cmd + Shift + P) e pesquise o comando
.NET MAUI: Configure Android. Selecione "Definir caminho do SDK do Android" e "Definir caminho do JDK do Android" e valide se eles apontam para as instalações de cada um.
- A pasta SDK do Android deve ter subpastas, como
build-tools, cmdline-tools e platform-tools.
- A pasta Java OpenJDK deve ter subpasta, como
bin, lib e muito mais.
- No Windows, se você instalar por meio do Visual Studio, o SDK do Java estará em
C:\Program Files\Microsoft\ e o SDK do Android estará em C:\Program Files (x86)\Android\android-sdk.
- Defina a variável de ambiente
JAVA_HOME para um caminho válido do Java OpenJDK.
- Defina a variável de ambiente
ANDROID_HOME para o caminho do SDK do Android.
- Verifique suas versões mínimas das dependências instaladas do Android:
- build-tools >= 34.0.0
- cmdline-tools == 11.0
- platforms;android-34*
- .NET 9: platform-tools = 34.0.5
Há um erro indicando que as licenças do Android não estão sendo aceitas
Em um prompt de comando ou terminal elevado, navegue até a pasta do SDK do Android cmdline-tools/latest/bin/, execute sdkmanager --licenses e siga os prompts da CLI.
Minhas dependências do Android não estão carregando no Gerenciador de Soluções, mas meu aplicativo é compilado corretamente
Este é um problema conhecido se você instalar para %APPDATA% no Windows e será corrigido em uma versão futura.
Instalação do iOS/Xcode
- Se você receber um erro informando que o Xcode não foi encontrado, execute
xcode-select --install em um terminal e verifique se isso xcode-select -p aponta para a instalação do Xcode.
- Se você ainda estiver enfrentando problemas, abra o próprio Xcode para garantir que ele seja carregado corretamente. Assim que o Xcode estiver aberto, navegue até Xcode > Configurações > Locais e verifique se o campo Ferramentas de linha de comando está apontando para o Xcode correto.
- Há um problema conhecido: às vezes você precisa criar seu aplicativo iOS/macOS duas vezes para que ele seja implantado. Isso será corrigido em uma versão futura.
Problemas de depuração
- A depuração pode falhar ao iniciar por vários motivos. Se não houver um erro claro na janela Saída, primeiro verifique se você está usando a configuração de execução C# no Visual Studio Code.
- Se você estiver usando uma versão mais antiga do .NET, o depurador C# não terá suporte para aplicativos .NET MAUI. Você pode usar a configuração de depuração herdada do .NET MAUI desmarcando a configuração da extensão MAUI > Configuration > Experimental > Use VSDbg.
- Você pode tentar um build de linha de comando do terminal para ver se o erro está no seu código ou na extensão do .NET MAUI. Por exemplo, você pode executar
dotnet build -f:net9.0-android para ver se a compilação do Android é bem-sucedida fora do Visual Studio Code. Se essa compilação for bem-sucedida, Reporte um problema
Limitações conhecidas
- Atualmente, você não pode alternar a estrutura de destino do IntelliSense (ele mostrará realce de sintaxe apenas na primeira estrutura de destino listada em seu arquivo .csproj). Essa capacidade está em andamento. Para obter destaque de sintaxe para outros destinos (por exemplo, Android em vez de iOS), você pode reordenar as estruturas de destino em seu arquivo de projeto.
- A Recarga Dinâmica do .NET está atualmente em visualização no Kit de Desenvolvimento do C#.
Envie-nos seus comentários sobre outros recursos que você gostaria de ver à medida que continuamos criando essa nova experiência!
Fornecer comentários
Leia as Perguntas frequentes sobre o Kit de Desenvolvimento do C# e verifique os Problemas conhecidos existentes antes de registrar um novo problema ou sugestão. Você pode enviar sugestões e problemas de dentro do Visual Studio Code por meio da caixa de diálogo Ajuda > Problema de Relatório . Certifique-se de selecionar "Uma extensão" e, em seguida, a extensão do .NET MAUI no menu suspenso.
