Comment migrer votre projet vers AndroidX : guide complet, exemples et dépannage

Le développement d'applications Android est en constante évolution, et l'une des transformations les plus importantes de ces dernières années a été l'introduction de AndroidX. Cette nouvelle structure de bibliothèque représente un bond en avant par rapport aux anciennes bibliothèques de support et affecte à la fois la manière dont les applications sont développées à partir de zéro et la nécessité de migrer les projets existants pour maintenir la compatibilité, le support et la sécurité. Une compréhension approfondie de la manière de migrer vers AndroidX est essentielle pour tout développeur Android qui aspire à créer des applications modernes, efficaces et évolutives.

Qu'est-ce qu'AndroidX et pourquoi est-il si pertinent dans le développement Android ?

AndroidX Il s'agit de l'évolution des anciennes bibliothèques de compatibilité, appelées bibliothèques de support. Sa création répond au besoin d’offrir une expérience de développement plus cohérente, modulaire et durable, intégrant de nouvelles fonctionnalités et de meilleures pratiques qui facilitent à la fois le travail et la maintenance future. Les bibliothèques AndroidX sont hébergées sous l'espace de noms androidx, remplaçant les anciens noms de paquets android.support etc.

Modernisation de l’écosystème : AndroidX non seulement unifie et renforce la compatibilité, mais introduit également de nouvelles fonctionnalités et modules qui permettent l'utilisation de modèles et d'architectures modernes.
Mises à jour indépendantes : Chaque bibliothèque AndroidX peut être mise à jour de manière autonome, ce qui évite conflits de versions et permet de conserver facilement uniquement les composants nécessaires dans le projet.
Cohérence du nom : Toutes les bibliothèques partagent une nomenclature et une structure organisationnelle cohérentes, ce qui facilite la gestion des dépendances et la compréhension de leurs fonctionnalités.
Support et maintenance étendus : Les bibliothèques de soutien ont cessé de recevoir mises à jour, la migration vers AndroidX est donc essentielle pour continuer à accéder aux nouvelles fonctionnalités, aux correctifs de sécurité et au support officiel.

La migration vers AndroidX est particulièrement importante car toutes les innovations et améliorations de l’écosystème Android sont implémentées exclusivement dans ces nouvelles bibliothèques. Ne pas migrer expose votre projet à des risques d’obsolescence et d’incompatibilité.

Histoire et évolution de la compatibilité Android : des bibliothèques de support à AndroidX

Dans un premier temps, le Bibliothèques de soutien Ils ont joué un rôle essentiel en permettant aux développeurs d'implémenter des fonctionnalités modernes sur des appareils plus anciens, garantissant une large base d'utilisateurs et permettant l'évolution constante des applications Android. Cependant, sa croissance incontrôlée et l’absence d’une structure modulaire cohérente ont déclenché de nombreux problèmes, tels que conflits de versions, limitations dans la mise à jour des dépendances et difficultés de maintenance.

AndroidX répond à ces défis en regroupant les bibliothèques en ensembles indépendants sous un espace de noms unifié et en simplifiant la gestion des versions pour offrir plus de flexibilité et de contrôle. Depuis sa sortie, AndroidX est devenu la norme de facto pour le développement Android, et les nouveaux projets construits avec les dernières versions d'Android Studio sont configurés pour utiliser ces bibliothèques par défaut.

Principaux avantages de la migration vers AndroidX

Compatibilité à long terme garantie : Les bibliothèques de support ont été officiellement abandonnées et ne reçoivent plus de nouvelles mises à jour.
Accès aux nouvelles technologies et outils : L'utilisation d'AndroidX est indispensable pour adopter Jetpack et profiter des dernières avancées en matière d'architecture et de composants d'interface utilisateur.
Meilleures performances et modularité : Les bibliothèques sont plus optimisées et permettent des mises à jour sélectives, minimisant les risques et améliorant les performances globales des applications.
Facilité de maintenance et de développement : La structure modulaire et la convention de nommage cohérente simplifient la gestion des dépendances, le débogage et l'ajout de nouvelles fonctionnalités.
Prise en charge étendue des outils et environnements modernes : L'environnement de développement, l'intégration continue et les outils de test sont axés sur la prise en charge complète d'AndroidX.

De plus, AndroidX facilite la correction des erreurs et des vulnérabilités, réduit la dette technique et prépare les projets d'améliorations futures, faisant du processus de migration un investissement stratégique à moyen et long terme.

Exigences essentielles avant de commencer la migration vers AndroidX

Environnement de développement mis à jour : Il est essentiel d'utiliser une version moderne d'Android Studio, à partir de la version 3.2, pour disposer de tous les outils de migration automatisés et d'un support complet.
Configuration Gradle : Votre dossier build.gradle doit avoir au moins compileSdkVersion y cibleSdkVersion en version 28 ou supérieure. Si vous utilisez le plugin Gradle inférieur à la version 3.2/3.3, vous rencontrerez une incompatibilité.
Contrôle de version ou sauvegarde : Faites une sauvegarde de votre projet et utilisez de préférence une branche distincte dans votre système de contrôle de version (Git ou similaire), vous permettant d'annuler les modifications en cas de problème.
Examen des dépendances : Examinez et documentez toutes les dépendances externes, en particulier celles qui peuvent utiliser des bibliothèques de support ou des packages hérités, et vérifiez la disponibilité de leurs versions compatibles AndroidX.
Gestion des succursales et du cycle de développement : Évitez de migrer pendant que des développements critiques sont en cours ; Effectuez la migration lorsque le projet est à un point stable pour minimiser les conflits.

Guide étape par étape pour migrer un projet existant vers AndroidX

Exécutez l'outil de migration Android Studio :
- Ouvrez le projet dans Android Studio.
- Dans le menu du haut, sélectionnez Refactor > Migrer vers AndroidX….
- Android Studio affichera une boîte de dialogue contenant des avertissements et des informations sur la migration. Acceptez de faire une sauvegarde si le système le recommande.
- Haz clic en Migrer pour démarrer le processus.
- Examinez les modifications proposées et confirmez en cliquant Do Refactor.
Mise à jour du fichier gradle.properties :
- Le processus de migration ajoute automatiquement deux lignes clés :
  - android.useAndroidX=true: Permet l'utilisation des bibliothèques AndroidX pour l'ensemble du projet.
  - android.enableJetifier=true: Active le « jetifier », un outil qui adapte les dépendances externes qui utilisent encore des bibliothèques de support pour les rendre compatibles avec AndroidX.
- Confirmez que ces lignes sont présentes après la migration.
Vérification et ajustement des dépendances dans build.gradle :
- Examinez toutes les dépendances dans vos fichiers build.gradle (niveau projet et module).
- Remplace toute référence aux anciens packages com.android.support.*, android.arch.* o android.support.test.* par leurs équivalents dans androidx. Vous pouvez vérifier le table de correspondance officielle pour vérifier la correspondance exacte de chaque bibliothèque.
- Éliminez les dépendances en double ou conflictuelles.
Révision et migration des dépendances tierces :
- Jetifier effectuera une grande partie du travail d'adaptation des dépendances externes, mais c'est une bonne idée de vérifier son statut dans le journal de construction ou directement dans les fichiers XML et les classes Java/Kotlin.
- Si une dépendance externe ne prend pas en charge AndroidX et que Jetifier ne l'a pas traduite correctement, recherchez une alternative compatible ou mettez à jour la bibliothèque vers une version récente qui le fait.
Révision manuelle des mises en page et du code source :
- Ouvrez vos fichiers de mise en page XML et vérifiez que les importations et les références aux widgets et aux composants d'interface utilisateur correspondent aux packages androidx et ne pas android.support.
- Assurez-vous que toutes les importations dans vos classes Java/Kotlin font référence aux nouveaux chemins.
- Si vous utilisez ProGuard ou R8, mettez à jour vos règles pour refléter les noms et les chemins des packages AndroidX.
Compilation et tests approfondis :
- Compiler le projet et l'exécuter test fonctionel et unitaire pour valider que la migration n'a pas provoqué d'erreurs.
- Traitez tous les avertissements ou erreurs liés aux incompatibilités, aux chemins d’importation ou aux modifications d’API.

Comment agir lorsque la migration automatique ne résout pas tous les cas

Modifications manuelles des mises en page : Certains fichiers XML peuvent encore inclure des chemins vers android.support; les ajuster manuellement pour androidx en fonction du composant.
Configurations spécifiques à ProGuard/R8 : Si vous utilisez des règles liées aux classes migrées, mettez-les à jour pour refléter les nouveaux noms de packages.
Scripts personnalisés et tâches Gradle : Si vous avez des scripts de build personnalisés qui font référence à des packages plus anciens, mettez-les à jour.
Mise à jour de la documentation interne : Adaptez toute documentation de projet interne pour refléter les changements et faciliter la maintenance future.
Vérification des incompatibilités dans les bibliothèques externes : Si la migration génère des erreurs liées à des dépendances incompatibles, consultez la documentation officielle de la bibliothèque et envisagez de migrer vers des alternatives plus modernes.

Exemples de migration de classes et de bibliothèques : d'android.support vers androidx

Avant: android.support.v7.app.AppCompatActivity
Après: androidx.appcompat.app.AppCompatActivity
Avant: android.support.design.widget.FloatingActionButton
Après: com.google.android.material.floatingactionbutton.FloatingActionButton
Avant: android.support.v4.content.LocalBroadcastManager
Après: androidx.localbroadcastmanager.content.LocalBroadcastManager
Avant: android.arch.lifecycle.ViewModel
Après: androidx.lifecycle.ViewModel
Avant: android.arch.persistence.room.Room
Après: androidx.room.Room

Vous pouvez trouver la liste complète des équivalences dans le .

Validation après la migration vers AndroidX et gestion des erreurs courantes

Vérifiez tous les modules et sous-projets : Dans les projets multi-modules, chaque module doit être migré et ses dépendances doivent être cohérentes.
Gérer les erreurs et les avertissements de Lint : AndroidX introduit de nouvelles vérifications Lint qui aident à détecter les erreurs courantes après la migration.
Gestion des API instables ou obsolètes : Après la migration, certaines anciennes classes ou méthodes peuvent être barrées ou marquées comme obsolètes ; remplacez-les par les alternatives recommandées par la documentation et l'IDE lui-même.
Tests approfondis : Effectue des tests fonctionnels, unitaires et d'intégration, en accordant une attention particulière aux fonctionnalités sensibles telles que la navigation, la persistance et la communication entre les activités.

Migration dans les projets Xamarin.Android et Xamarin.Forms

L'adoption d'AndroidX est également pertinente dans l'environnement de développement multiplateforme car Xamarin. Les étapes spécifiques sont détaillées ci-dessous :

Prérequis dans Xamarin :
- Veuillez utiliser Visual Studio mis à jour et Xamarin.Android 10.0 ou supérieur.
- Installez JDK 8 et assurez-vous que vous disposez de l'API Android SDK 28 ou supérieure.
Paquets NuGet AndroidX : Incluez les packages AndroidX NuGet directement dans votre projet Xamarin.Android.
Outil de migration dans l'IDE : Dans Visual Studio, accédez à Outils > Options > Xamarin > Paramètres Android et activer le migrateur vers AndroidX.
Migration automatique dans Xamarin.Forms :
- Ciblez votre projet sur l’API 29 ou supérieure et utilisez Xamarin.Forms 4.5 ou version ultérieure.
- Compilez le projet afin que le dépendances de la bibliothèque de compatibilité à porter sur AndroidX ;
- Si des erreurs apparaissent en raison de packages AndroidX manquants, installez les listes dans la sortie de build via NuGet ou en modifiant le fichier .csproj.
Résolution des conflits et ajustements manuels : Certaines bibliothèques d’architecture peuvent provoquer des conflits ; supprimez les références en double et conservez uniquement les versions AndroidX.

La migration vers Xamarin permet d'accéder aux fonctionnalités Android modernes et garantit la longévité du projet.

Migration avancée : mise à niveau des bibliothèques multimédias ExoPlayer vers AndroidX Media3

Si votre projet utilise ExoPlayer et les bibliothèques de galerie de , la migration vers AndroidX implique de passer à androidx.media3. Ce processus nécessite outils supplémentaires, tels que des scripts automatisés pour ajuster la structure des packages Gradle, des importations et des dépendances.

Exigences précédentes:
- Assurez-vous que le projet est sous contrôle de code source ou sous sauvegarde.
- Mettez à jour votre projet vers la dernière version d'ExoPlayer et supprimez les méthodes obsolètes.
- Augmenter le compileSdkVersion à 32 ou supérieur et utilisez des versions mises à jour de Gradle.
- Remplacez les importations génériques par des importations complètes dans vos fichiers sources.
Exécutez le script de migration :
- Téléchargez et exécutez le script fourni dans la documentation officielle d'ExoPlayer.
- Exécutez le script pour attribuer des packages, des classes et des dépendances à la nouvelle structure Media3.
- Vérifiez les modifications avec des outils de comparaison de code.
Appliquer les modifications au service multimédia :
- Modifiez votre service pour hériter de MediaLibraryService et utiliser androidx.media3.session.MediaLibrarySession.
- Adapte les implémentations du cycle de vie et des méthodes de rappel.
- Remplace les classes et méthodes obsolètes ou supprimées par leurs équivalents Media3.
Gestion des notifications et des autorisations :
- MediaLibraryService gère les notifications multimédias ; personnalisez le fournisseur si vous en avez besoin.
- Demandez l’autorisation FOREGROUND_SERVICE si votre application l’exige.
Tests et corrections de bugs :
- Corriger les avertissements d'API instables avec des annotations @OptIn selon ce qui correspond.
- Remplace tous les appels d'API obsolètes qui sont barrés dans l'éditeur.

Vous trouverez plus de détails sur la migration spécifique aux médias dans la documentation officielle de Media3 AndroidX.

Questions fréquemment posées et dépannage après la migration

Que dois-je faire si une bibliothèque tierce échoue après la migration ? Veuillez essayer de le mettre à jour vers une version compatible avec AndroidX. S'il n'existe pas, cherchez des alternatives ou envisagez de le conserver temporairement activer Jetifier.
Le processus est-il réversible ? Oui, tant que vous travaillez sur une branche ou avec des sauvegardes, vous pouvez annuler les modifications.
Dois-je migrer les tests ? Oui, les tests doivent également utiliser les chemins AndroidX et non les anciens packages.
Cela affecte-t-il tous les modules du projet ? Oui, la migration doit être complète sur tous les modules pour éviter les incohérences et les erreurs de compilation.
Que faire si mon projet utilise déjà AndroidX ? Les projets créés avec les versions modernes d'Android Studio sont désormais configurés correctement, mais il est judicieux de vérifier les anciennes références.

La mise à jour et la migration de votre projet Android vers AndroidX peuvent sembler difficiles au début, mais avec les bons outils et les bonnes étapes, le processus devient systématique et sécurisé. La migration garantit la compatibilité future, donne accès aux dernières améliorations de performances et de sécurité et positionne vos applications parmi les meilleures de l'écosystème Android. Investir du temps dans cette transition est essentiel pour tout développeur ou équipe à la recherche de qualité, d’évolutivité et d’un long cycle de vie pour ses applications.