Compartilhar via

Migração de projeto do Xamarin.Android

  • Artigo

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. No momento do build, esse valor será incluído automaticamente 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 do build, 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 arquivo relacionado ao .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 obter mais informações, confira arquivos de props de carga de trabalho.

Comportamento de runtime

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.

Vinculador

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

  • <PublishTrimmed>true</PublishTrimmed>
  • <TrimMode>link</TrimMode>, que permite o corte no nível do membro.

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=link. TrimMode=copyused é o padrão para o SDK do .NET, mas não é apropriado para aplicativos móveis. No entanto, você ainda pode aceitar TrimMode=copyused, se necessário.

Se a configuração do AndroidLinkMode herdado for usada, SdkOnly e Full serão padronizados para configurações de vinculador equivalentes:

  • <PublishTrimmed>true</PublishTrimmed>
  • <TrimMode>link</TrimMode>

Com AndroidLinkMode=SdkOnly, apenas os assemblies BCL e SDK marcados com %(Trimmable) são vinculados no nível do membro. AndroidLinkMode=Full define %(TrimMode)=link em todos os assemblies do .NET.

Dica

Você deve migrar para as novas configurações do vinculador, pois a configuração de AndroidLinkMode eventualmente será preterida.

Compilação Ahead of Time

$(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.

A versão cria o padrão para os seguintes valores da propriedade 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 do build, 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 Idioma Marcações
Modelo de atividade do Android android-activity C# Android
Associação da Biblioteca Java do 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 um compilação:

  • Executa aapt para gerar Resource.designer.cs e potencialmente emitir erros de build para problemas em arquivos @(AndroidResource).
  • Compila o código C#.
  • Executa o destino 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. Também 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. Os IDEs chamarão o destino Install para implantação, que produzirá o arquivo .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, você pode usar o destino Run MSBuild:

dotnet build HelloAndroid.csproj -t:Run

Confira também