Migration de projets Xamarin.Android

Article
12/20/2024

Un projet .NET 8 pour une application .NET pour Android est similaire à l’exemple suivant :

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

Pour un projet de bibliothèque, omettez totalement la propriété $(OutputType) ou spécifiez Library comme valeur de propriété.

Fichiers de configuration .NET

Il n’existe aucune prise en charge des fichiers de configuration, tels que Foo.dll.config ou Foo.exe.config, dans les projets .NET pour Android. Les éléments de configuration <dllmap> ne sont pas du tout pris en charge dans .NET Core, et les autres types d’éléments pour les packages de compatibilité tels que System.Configuration.ConfigurationManager n’ont jamais été pris en charge dans les projets Android.

Changements au niveau des propriétés MSBuild

La propriété $(AndroidSupportedAbis) ne doit pas être utilisée :

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

La propriété $(AndroidSupportedAbis) doit être remplacée par des identificateurs de runtime .NET :

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

Pour plus d’informations sur les identificateurs de runtime, consultez Catalogue RID .NET.

Le tableau suivant présente les autres propriétés MSBuild qui ont changé dans .NET pour Android :

Propriété	Commentaires
`$(AndroidUseIntermediateDesignerFile)`	`True` par défaut.
`$(AndroidBoundExceptionType)`	`System` par défaut. Cette propriété modifie les types d’exceptions levées à partir de différentes méthodes pour mieux s’aligner sur la sémantique .NET, au détriment de la compatibilité avec Xamarin.Android. Pour plus d’informations, consultez Certaines des nouvelles exceptions Java enveloppées utilisent des exceptions BCL qui diffèrent des types BCL associés.
`$(AndroidClassParser)`	`class-parse` par défaut. `jar2xml` n’est pas pris en charge.
`$(AndroidDexTool)`	`d8` par défaut. `dx` n’est pas pris en charge.
`$(AndroidCodegenTarget)`	`XAJavaInterop1` par défaut. `XamarinAndroid` n’est pas pris en charge.
`$(AndroidManifest)`	La valeur par défaut est `AndroidManifest.xml` à la racine des projets, car `Properties\AssemblyInfo.cs` n’est plus utilisé dans les projets de style SDK. `Properties\AndroidManifest.xml` est également détecté et utilisé s’il existe, afin de faciliter la migration.
`$(DebugType)`	`portable` par défaut. `full` et `pdbonly` ne sont pas pris en charge.
`$(MonoSymbolArchive)`	`False`, puisque `mono-symbolicate` n’est pas pris en charge.

De plus, si la liaison Java est activée avec @(InputJar), @(EmbeddedJar) ou @(LibraryProjectZip), la propriété $(AllowUnsafeBlocks) est définie par défaut avec la valeur True.

Remarque

La référence d’un projet Android Wear à partir d’une application Android n’est pas prise en charge.

Changements au niveau d’AndroidManifest.xml

Dans les projets Android Xamarin.Android, Java et Kotlin, l’élément <uses-sdk/> indique la version Android minimale prise en charge par votre application, ainsi que la version Android cible sur laquelle votre application est compilée :

<?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>

Pour plus d’informations sur l’élément <uses-sdk/>, consultez la documentation Android.

Dans les applications Android .NET 8, il existe des propriétés MSBuild pour définir ces valeurs. L’utilisation des propriétés MSBuild présente d’autres avantages. Dans la plupart des cas, l’élément <uses-sdk/> doit être supprimé pour laisser la place à des valeurs dans le fichier .csproj de votre projet :

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

Dans cet exemple, net8.0-android est la forme abrégée de net8.0-android34.0. Les versions futures de .NET suivront la dernière version Android disponible au moment de leur publication.

TargetFramework correspond à android:targetSdkVersion. Au moment de la génération, cette valeur sera automatiquement incluse dans l’élément <uses-sdk/> pour vous. L’avantage d’utiliser TargetFramework de cette façon est que vous recevez la liaison C# correspondante pour l’API Android 34 pour net8.0-android34.0. Android est publié indépendamment du cycle de publication de .NET, donc nous avons la possibilité de choisir net8.0-android35.0 lorsqu’une liaison est disponible pour la prochaine version d’Android.

De même, SupportedOSPlatformVersion mappe à android:minSdkVersion. Au moment de la génération, cette valeur sera automatiquement incluse dans l’élément <uses-sdk/> pour vous. Les API Android sont décorées avec SupportedOSPlatformAttribute afin d’obtenir des avertissements de build lorsque vous appelez des API qui sont disponibles uniquement pour certaines versions Android sur lesquelles votre application peut s’exécuter :

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

Pour utiliser cette API en toute sécurité, vous pouvez déclarer une SupportedOSPlatformVersion supérieure dans votre projet ou utiliser l’API IsAndroidVersionAtLeast au moment de l’exécution :

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

Inclusion de fichier par défaut

Le comportement par défaut de globbing de fichiers relatifs à .NET pour Android est défini dans AutoImport.props. Ce comportement peut être désactivé pour les éléments Android en définissant $(EnableDefaultAndroidItems) sur false, ou le comportement d’inclusion de tous les éléments par défaut peut être désactivé en définissant $(EnableDefaultItems) sur false. Pour plus d’informations, consultez Fichiers des propriétés de charge de travail.

Comportement d’exécution

Des changements de comportement ont été apportés à la méthode String.IndexOf() dans .NET 5+ sur différentes plateformes. Pour plus d’informations, consultez Globalisation et ICU .NET.

Éditeur de liens

.NET 8 a de nouveaux paramètres pour l’éditeur de liens :

<PublishTrimmed>true</PublishTrimmed>
<TrimMode>partial</TrimMode>, qui supprime les assemblées qui ont choisi de découper.

Pour plus d’informations, consultez Options de découpage.

Dans les projets .NET pour Android par défaut, les builds Debug n’utilisent pas l’éditeur de liens, tandis que les builds Release définissent PublishTrimmed=true et TrimMode=partial.

Si le paramètre AndroidLinkMode hérité est utilisé, SdkOnly et Full sont définis par défaut avec les paramètres équivalents de l’éditeur de liens :

<PublishTrimmed>true</PublishTrimmed>
<TrimMode>partial</TrimMode>

Avec AndroidLinkMode=SdkOnly, seuls les assemblys BCL et SDK marqués avec %(Trimmable) sont liés au niveau des membres. AndroidLinkMode=Full définit %(TrimMode)=partial sur tous les assemblys .NET.

Conseil

Vous devez migrer vers les nouveaux paramètres de l’éditeur de liens, car le paramètre AndroidLinkMode finira par être déprécié à un moment ou à un autre.

.NET 9 a de nouveaux paramètres pour l’éditeur de liens :

<TrimMode>Full</TrimMode>, qui effectue le découpage complet.

Pour plus d’informations, consultez Options de découpage.

Dans les projets .NET pour Android par défaut, les builds Debug n’utilisent pas l’éditeur de liens, tandis que les builds Release définissent PublishTrimmed=true et TrimMode=partial.

Compilation anticipée

$(RunAOTCompilation) est la nouvelle propriété MSBuild pour activer la compilation anticipée (AoT, Ahead-of-Time). Il s’agit de la même propriété utilisée pour Blazor WASM. La propriété $(AotAssemblies) active également AOT afin d’aider à migrer des projets Xamarin.Android vers des projets .NET pour Android. Toutefois, cette propriété a été dépréciée dans .NET 7.

Les versions release sont définies par défaut avec les valeurs de propriété AOT suivantes :

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

Il s’agit du comportement lorsque les propriétés $(RunAOTCompilation) et $(AndroidEnableProfiledAot) ne sont pas définies, où des paramètres optimaux sont choisis pour le temps de démarrage et la taille de l’application.

Pour désactiver AOT, vous devez définir explicitement les propriétés $(RunAOTCompilation) et $(AndroidEnableProfiledAot) sur false :

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

Encodages pris en charge

Si votre application Xamarin.Android utilise certains jeux de codes internationaux, ces derniers doivent être spécifiés explicitement dans votre fichier projet à l’aide de la propriété MSBuild Mandroidl18n afin que l’éditeur de liens puisse inclure des ressources de prise en charge. Pour plus d’informations sur cette propriété de build, consultez MAndroidl18n.

Toutefois, la propriété MSBuild Mandroidl18n n’est pas prise en charge dans les applications .NET pour Android. La prise en charge est fournie par le package NuGet System.TextEncoding.CodePages. Pour plus d’informations, consultez CodePagesEncodingProvider.

CLI .NET

.NET pour Android prend en charge l’utilisation de l’interface de ligne de commande .NET (CLI.NET) pour créer, générer, publier et exécuter des applications Android.

dotnet new

dotnet new peut être utilisé pour créer de nouveaux projets et éléments .NET pour Android à l’aide de modèles de projet et de modèles d’élément qui sont nommés en se basant sur les schémas et le nommage des modèles .NET existants :

Modèle	Nom court	Langage	Balises
Modèle d’activité Android	android-activity	C#	Android
Liaison de bibliothèque Java Android	android-bindinglib	C#	Android
Modèle de disposition Android	android-layout	C#	Android
Bibliothèque de classes Android	androidlib	C#	Android
Application Android	android	C#	Android

Les exemples suivants montrent l’utilisation de dotnet new pour créer différents types de projets .NET pour Android :

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

Une fois que les projets .NET pour Android ont été créés, des modèles d’élément peuvent être utilisés pour ajouter des éléments aux projets :

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

dotnet build et publish

Pour .NET pour Android, dotnet build produit une application exécutable. Cela signifie créer un fichier .apk ou .aab pendant le processus de génération et réorganiser les tâches MSBuild du SDK .NET afin qu’elles s’exécutent pendant la génération. C’est pourquoi .NET pour Android effectue les opérations suivantes lors d’une génération :

Exécuter aapt pour générer Resource.designer.cs et éventuellement émettre des erreurs de génération pour les problèmes dans les fichiers @(AndroidResource).
Compiler le code C#.
Exécuter la cible MSBuild ILLink pour la liaison.
Générer des stubs Java et AndroidManifest.xml.
Compiler le code Java via javac.
Convertir le code Java en .dex via d8/r8.
Créer un fichier .apk ou .aab et le signer.

dotnet publish est réservé à la publication d’une application pour Google Play et autres mécanismes de distribution comme ad-hoc. Il signe également le fichier .apk ou .aab avec différentes clés.

Remarque

Le comportement dans les IDE diffère. La cible Build ne produit pas de fichier .apk si $(BuildingInsideVisualStudio) est true. Les IDE appellent la cible Install pour le déploiement, ce qui produit le fichier .apk. Ce comportement correspond à Xamarin.Android.

dotnet run

dotnet run peut être utilisé pour lancer des applications sur un appareil ou un émulateur via l’argument --project :

dotnet run --project HelloAndroid.csproj

Vous pouvez également utiliser la cible MSBuild Run :

dotnet build HelloAndroid.csproj -t:Run

Voir aussi

Projets de liaison

Partager via