Migração do projeto Xamarin.Android

Um projeto .NET 8 para um aplicativo .NET para Android é semelhante ao exemplo a seguir:

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

Para um projeto de biblioteca, omita completamente a propriedade $(OutputType) 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 no .NET para projetos Android. Os elementos de configuração <dllmap> não são suportados de todo no .NET Core, e outros tipos de elementos em pacotes de compatibilidade, como System.Configuration.ConfigurationManager, nunca foram suportados 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>

Em vez disso, a propriedade $(AndroidSupportedAbis) deve ser substituída por identificadores de tempo de execução 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 tempo de execução, consulte Catálogo RID do .NET.

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

Propriedade	Observações
$(AndroidUseIntermediateDesignerFile)	True por padrão.
$(AndroidBoundExceptionType)	System por padrão. Esta propriedade altera os tipos de exceções lançados por vários métodos para alinhar melhor com a semântica do .NET, embora isso implique um custo para a compatibilidade com o Xamarin.Android. Para obter mais informações, consulte Algumas das novas exceções Java encapsuladas usam exceções BCL que diferem dos tipos de BCL relacionados.
$(AndroidClassParser)	class-parse por padrão. jar2xml não é suportado.
$(AndroidDexTool)	d8 por padrão. dx não é suportado.
$(AndroidCodegenTarget)	XAJavaInterop1 por padrão. XamarinAndroid não é suportado.
$(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á detetado e usado, se existir, para facilitar a migração.
$(DebugType)	portable por padrão. full e pdbonly não são suportados.
$(MonoSymbolArchive)	False, uma vez que mono-symbolicate não é suportado.

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

Observação

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

Alterações ao AndroidManifest.xml

Nos projetos Xamarin.Android, Java e Kotlin Android, o elemento <uses-sdk/> indica a versão mínima do Android suportada pelo seu aplicativo, bem como a versão Android de destino contra a qual 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/>, consulte a documentação do Android.

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

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

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

TargetFramework mapeia para android:targetSdkVersion. No momento da compilação, esse valor será automaticamente incluído no elemento <uses-sdk/> para você. O benefício de usar TargetFramework dessa maneira é que você recebe a vinculação C# correspondente para Android API 34 para net8.0-android34.0. O Android é lançado independentemente do ciclo de lançamento do .NET, portanto, temos a flexibilidade de optar por 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á automaticamente incluído no elemento <uses-sdk/> para você. As APIs do Android são decoradas com o SupportedOSPlatformAttribute para que você receba avisos de compilação para chamar APIs que só estão disponíveis para algumas das versões do Android em que 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, você pode declarar um SupportedOSPlatformVersion superior em seu projeto ou usar a API IsAndroidVersionAtLeast em tempo de execução:

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

Inclusão de arquivo padrão

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

Comportamento de tempo de execução

Há mudanças comportamentais no método String.IndexOf() no .NET 5+ em diferentes plataformas. Para obter mais informações, consulte .NET Globalização eICU.

linker

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

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

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

No .NET para projetos Android por padrão, Debug compilações não usam o vinculador e Release compilações definem PublishTrimmed=true e TrimMode=partial.

Compilação Ahead-of-Time (AOT)

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

As compilações de lançamento definem-se por padrão como os seguintes valores de propriedade AOT:

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

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

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

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

Codificações suportadas

Se seu aplicativo Xamarin.Android usa determinados conjuntos de códigos internacionais, eles devem ser especificados explicitamente em seu arquivo de projeto usando a propriedade Mandroidl18n MSBuild, para que o vinculador possa incluir recursos de suporte. Para obter mais informações sobre esta propriedade de compilação, consulte MAndroidl18n.

No entanto, a propriedade Mandroidl18n MSBuild não é suportada no .NET para aplicativos Android. Em vez disso, o suporte é fornecido pelo pacote NuGet System.TextEncoding.CodePages. Para obter mais informações, consulte CodePagesEncodingProvider.

CLI do .NET

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

dotnet novo

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

Modelo	Nome curto	Idioma	Etiquetas
Modelo de atividade do Android	android-activity	C#	Androide
Vinculação da biblioteca Java do Android	android-bindinglib	C#	Androide
Modelo de layout do Android	disposição do Android	C#	Androide
Biblioteca de classes Android	androidlib	C#	Androide
Aplicação Android	androide	C#	Androide

Os exemplos a seguir mostram o uso do dotnet new para criar diferentes tipos de projetos .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 o .NET para projetos Android tiver sido criado, os modelos de item podem 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 construir & publicar

Para .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 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 o aapt para gerar o Resource.designer.cs e potencialmente emitir erros de compilação devido a problemas nos ficheiros @(AndroidResource).
• Compile o código C#.
• Execute o alvo ILLink do MSBuild para fazer a ligação.
• Gere stubs Java; AndroidManifest.xml.
• Compile código java via javac.
• Converta código java para .dex via d8/r8.
• Crie um .apk ou .aab e assine-o.

dotnet publish é reservado para publicar uma aplicação para o Google Play e outros mecanismos de distribuição, como ad-hoc. Ele assina também o .apk ou o .aab usando chaves diferentes.

Observação

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

Dotnet Run

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, pode usar o alvo Run MSBuild:

dotnet build HelloAndroid.csproj -t:Run

Ver também

• Projetos vinculativos