Migração de projeto do Xamarin.Android

Um projeto do .NET 8 para um aplicativo .NET para Android é semelhante ao seguinte exemplo:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-android</TargetFramework>
    <OutputType>Exe</OutputType>
  </PropertyGroup>
</Project>

Para um projeto de biblioteca, omita a propriedade $(OutputType) completamente ou especifique Library como o valor da propriedade.

Arquivos de configuração do .NET

Não há suporte para arquivos de configuração como Foo.dll.config ou Foo.exe.config em projetos do .NET para Android. Os elementos de configuração <dllmap> não têm suporte no .NET Core e os outros tipos de elementos para pacotes de compatibilidade, como System.Configuration.ConfigurationManager, nunca tiveram suporte em projetos Android.

Alterações nas propriedades do MSBuild

A propriedade $(AndroidSupportedAbis) não deve ser usada:

<PropertyGroup>
  <!-- Used in Xamarin.Android projects -->
  <AndroidSupportedAbis>armeabi-v7a;arm64-v8a;x86;x86_64</AndroidSupportedAbis>
</PropertyGroup>

Como alternativa, a propriedade $(AndroidSupportedAbis) deve ser substituída por identificadores de runtime do .NET:

<PropertyGroup>
  <!-- Used in .NET for Android projects -->
  <RuntimeIdentifiers>android-arm;android-arm64;android-x86;android-x64</RuntimeIdentifiers>
</PropertyGroup>

Para obter mais informações sobre identificadores de runtime, confira Catálogo do .NET RID.

A tabela a seguir mostra outras propriedades do MSBuild que foram alteradas no .NET para Android:

Propriedade	Comentários
$(AndroidUseIntermediateDesignerFile)	True por padrão.
$(AndroidBoundExceptionType)	System por padrão. Essa propriedade altera os tipos de exceções geradas de vários métodos para se alinhar melhor com a semântica do .NET, ao custo da compatibilidade com o Xamarin.Android. Para obter mais informações, confira Algumas das novas exceções de Java encapsuladas usam exceções da BCL que diferem dos tipos de BCL relacionados.
$(AndroidClassParser)	class-parse por padrão. Não há suporte para jar2xml.
$(AndroidDexTool)	d8 por padrão. Não há suporte para dx.
$(AndroidCodegenTarget)	XAJavaInterop1 por padrão. Não há suporte para XamarinAndroid.
$(AndroidManifest)	O padrão é AndroidManifest.xml na raiz dos projetos porque Properties\AssemblyInfo.cs não é mais usado em projetos no estilo SDK. Properties\AndroidManifest.xml também será detectado e usado se existir, para facilitar a migração.
$(DebugType)	portable por padrão. full e pdbonly não são suportados.
$(MonoSymbolArchive)	False, já que não há suporte para mono-symbolicate.

Além disso, se a associação Java estiver habilitada com @(InputJar), @(EmbeddedJar) ou @(LibraryProjectZip), a propriedade $(AllowUnsafeBlocks) usará True como padrão.

Observação

Não há suporte para fazer referência a um projeto do Android Wear de um aplicativo Android.

Alterações no AndroidManifest.xml

Nos projetos do Xamarin.Android, Java e Kotlin Android, o elemento <uses-sdk/> indica a versão mínima do Android que seu aplicativo dá suporte, bem como a versão de destino do Android em que seu aplicativo é compilado:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    android:versionCode="1"
    android:versionName="1.0"
    package="com.companyname.myapp">
  <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="33" />
  <application android:icon="@mipmap/ic_launcher" android:label="@string/app_name" android:theme="@style/AppTheme" />
</manifest>

Para obter mais informações sobre o elemento <uses-sdk/>, confira a documentação do Android.

Em aplicativos Android do .NET 8, há propriedades do MSBuild para definir esses valores. O uso das propriedades do MSBuild tem outros benefícios. Na maioria dos casos, o elemento <uses-sdk/> deve ser removido em favor de valores no arquivo .csproj do projeto:

<Project>
  <PropertyGroup>
    <TargetFramework>net8.0-android</TargetFramework>
    <SupportedOSPlatformVersion>21</SupportedOSPlatformVersion>
  </PropertyGroup>
</Project>

Neste exemplo, net8.0-android é uma abreviação de net8.0-android34.0. As versões futuras do .NET acompanharão a versão mais recente do Android disponível no momento do lançamento do .NET.

O TargetFramework é mapeado para android:targetSdkVersion. Durante o processo de build, esse valor será automaticamente incluído no elemento <uses-sdk/> para você. O benefício de usar TargetFramework dessa forma é que você recebe a associação C# correspondente para a API 34 do Android para net8.0-android34.0. O Android é lançado independentemente do ciclo de lançamento do .NET, portanto, temos a flexibilidade de aceitar net8.0-android35.0 quando uma associação estiver disponível para a próxima versão do Android.

Da mesma forma, SupportedOSPlatformVersion mapeia para android:minSdkVersion. No momento da compilação, esse valor será incluído automaticamente no elemento <uses-sdk/> para você. As APIs do Android são decoradas com o SupportedOSPlatformAttribute para que você receba avisos de build para chamar APIs que só estão disponíveis para algumas das versões do Android onde seu aplicativo pode ser executado:

error CA1416: This call site is reachable on 'Android' 21.0 and later. `ConnectivityManager.ActiveNetwork` is only supported on: 'Android' 23.0 and later.

Para usar essa API com segurança, declare um SupportedOSPlatformVersion maior em seu projeto ou usar a API IsAndroidVersionAtLeast em runtime:

if (OperatingSystem.IsAndroidVersionAtLeast(23))
{
    // Use the API here
}

Inclusão de arquivo padrão

O comportamento padrão de globbing de arquivos do .NET para Android é definido em AutoImport.props. Esse comportamento pode ser desabilitado para itens do Android definindo $(EnableDefaultAndroidItems) como falseou todo o comportamento de inclusão de item padrão pode ser desabilitado definindo $(EnableDefaultItems) como false. Para mais informações, veja arquivos de propriedades de carga de trabalho.

Comportamento em tempo de execução

Há alterações de comportamento no método String.IndexOf() no .NET 5+ em diferentes plataformas. Para mais informações, confira Globalização do .NET e ICU.

Linker

O .NET 9 tem novas configurações para o vinculador:

• <TrimMode>Full</TrimMode>, que executa o corte completo.

Para obter mais informações, consulte Opções de corte.

Nos projetos do .NET para Android por padrão, os builds Debug não usam o vinculador e os buildsRelease configuram PublishTrimmed=true e TrimMode=partial.

Compilação Antecipada

$(RunAOTCompilation) é a nova propriedade do MSBuild para habilitar a compilação Ahead of Time (AoT). Essa é a mesma propriedade usada para WASM do Blazor. A propriedade $(AotAssemblies) também habilita o AOT, a fim de ajudar na migração de projetos do Xamarin.Android para os projetos do .NET para Android. No entanto, esta propriedade foi preterida no .NET 7.

Compilações de lançamento têm como padrão os seguintes valores das propriedades do AOT:

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <RunAOTCompilation>true</RunAOTCompilation>
  <AndroidEnableProfiledAot>true</AndroidEnableProfiledAot>
</PropertyGroup>

Esse é o comportamento quando as propriedades $(RunAOTCompilation) e $(AndroidEnableProfiledAot) não são definidas e escolhe as configurações ideais para o tempo de inicialização e o tamanho do aplicativo.

Para desabilitar o AOT, você precisa definir explicitamente as propriedades $(RunAOTCompilation) e $(AndroidEnableProfiledAot) para false:

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <RunAOTCompilation>false</RunAOTCompilation>
  <AndroidEnableProfiledAot>false</AndroidEnableProfiledAot>
</PropertyGroup>

Codificações com suporte

Se o aplicativo Xamarin.Android usar determinados conjuntos de códigos internacionais, eles precisarão ser especificados explicitamente no arquivo de projeto usando a propriedade Mandroidl18n MSBuild, para que o vinculador possa incluir recursos de suporte. Para obter mais informações sobre essa propriedade de compilação, confira MAndroidl18n.

No entanto, não há suporte para a propriedade Mandroidl18n MSBuild em aplicativos .NET para Android. O suporte é fornecido pelo pacote NuGet System.TextEncoding.CodePages. Para obter mais informações, consulte CodePagesEncodingProvider.

CLI do .NET

O .NET para Android dá suporte ao uso da interface de linha de comando do .NET (CLI do .NET) para criar, compilar, publicar e executar aplicativos Android.

dotnet new

dotnet new pode ser usado para criar novos projetos e itens do .NET para Android usando modelos de projeto e modelos de item que são nomeados seguindo os padrões e a nomenclatura de modelos existentes do .NET:

Modelo	Nome curto	Linguagem	Etiquetas
Modelo de atividade do Android	android-activity (atividade do android)	C#	Android
Vinculação da Biblioteca Java para Android	android-bindinglib	C#	Android
Modelo de Layout do Android	android-layout	C#	Android
Biblioteca de Classes do Android	androidlib	C#	Android
Aplicativo Android	android	C#	Android

Os exemplos a seguir mostram como usar dotnet new para criar diferentes tipos de projetos do .NET para Android:

dotnet new android            --output MyAndroidApp     --packageName com.mycompany.myandroidapp
dotnet new androidlib         --output MyAndroidLibrary
dotnet new android-bindinglib --output MyJavaBinding

Depois que os projetos do .NET para Android tiverem sido criados, os modelos de item poderão ser usados para adicionar itens aos projetos:

dotnet new android-activity --name LoginActivity --namespace MyAndroidApp
dotnet new android-layout   --name MyLayout      --output Resources/layout

dotnet build & publish

Para o .NET para Android, dotnet build produz um aplicativo executável. Isso significa criar um arquivo .apk ou .aab durante o processo de compilação e reordenar as tarefas do MSBuild do SDK do .NET para que sejam executadas durante a compilação. Portanto, o .NET para Android faz o seguinte durante uma compilação:

• Execute aapt para gerar Resource.designer.cs e potencialmente emitir erros de compilação para problemas em arquivos @(AndroidResource).
• Compila o código C#.
• Execute o alvo do MSBuild ILLink para vinculação.
• Gera stubs java e AndroidManifest.xml.
• Compila o código java via javac.
• Converte o código java em .dex via d8/r8.
• Cria um .apk ou .aab e assina-o.

dotnet publish é reservado para publicar um aplicativo para o Google Play e outros mecanismos de distribuição, como ad-hoc. Além disso, assina o .apk ou .aab com chaves diferentes.

Observação

O comportamento dentro dos IDEs será diferente. O destino Build não produzirá um arquivo .apk se $(BuildingInsideVisualStudio) for true. As IDEs chamarão o alvo Install para implantação, que produzirá o arquivo .apk. Esse comportamento corresponde ao Xamarin.Android.

execução dotnet

dotnet run pode ser usado para iniciar aplicativos em um dispositivo ou emulador por meio do argumento --project:

dotnet run --project HelloAndroid.csproj

Como alternativa, você pode usar o alvo Run MSBuild:

dotnet build HelloAndroid.csproj -t:Run

Confira também

• Projetos de associação