Zeitplan für die DSL/API-Migration des Android-Gradle-Plug-ins

Das Android Gradle-Plug-in (AGP) ist das unterstützte Build-System für Android-Anwendungen. Es unterstützt das Kompilieren vieler verschiedener Quelltypen und das Verknüpfen dieser Quelltypen zu einer Anwendung, die Sie auf einem physischen Android-Gerät oder einem Emulator ausführen können.

Im folgenden Abschnitt wird die geplante Weiterentwicklung der DSL und API des AGP beschrieben. Wenn in stabilen Releases neue APIs eingeführt werden, werden alte APIs als eingestellt markiert. Diese eingestellten APIs sind dann in der nächsten stabilen Version nicht mehr verfügbar. In den folgenden Abschnitten finden Sie Informationen zu den anstehenden Änderungen in den einzelnen Hauptversionen von AGP.

Ein detaillierteres Protokoll der AGP-API-Verwerfungen oder ‑Entfernungen finden Sie unter AGP-API-Updates.

AGP 10.0 (Ende 2026)

Android-Gradle-Plug-in 10.0 – API-Änderungen und Modernisierung

Mit AGP 10.0 wird die Umstellung auf ein vollständig lazy-kompatibles Build-Modell mit Konfigurationscache abgeschlossen. Diese Version ist das Ergebnis einer mehrjährigen Bemühung, Legacy-APIs, die nicht lazy sind, durch eine sicherere und leistungsfähigere Architektur zu ersetzen.

Warum ein Lazy-Build-Modell?

Im alten, nicht verzögerten Build-Modell wertet Gradle Objekte sofort aus, fragt Variantendaten ab und konfiguriert Aufgaben in allen Projektmodulen bei jedem Synchronisierungs- oder Build-Aufruf. Durch diese sofortige Auswertung werden CPU-Zeit und Arbeitsspeicher für Varianten und Aufgaben verschwendet, die nicht ausgeführt werden. Außerdem kommt es bei komplexen Build-Skripts zu Konflikten bei der Auswertungsreihenfolge.

Durch die Umstellung auf ein vollständig verzögertes Build-Modell mit Lazy-Providern (Provider<T>) und der modernen Variant API (androidComponents {}) werden Eigenschaften und Task-Verbindungen nur bei Bedarf im aktiven Build-Ausführungsgraphen verzögert berechnet.

Die in dieser Version entfernten Legacy-APIs waren grundsätzlich nicht mit dieser modernen Architektur kompatibel. Wenn Sie sie entfernen, kann AGP den Gradle-Konfigurationscache und die Projektisolation vollständig unterstützen, was die Build-Geschwindigkeit und die Synchronisierungszeiten in Android Studio erheblich verbessert.

Der wichtigste architektonische Unterschied

Die alte BaseVariant API (applicationVariants.all {}) war eifrig und aufgabenorientiert. Entwickler hatten während der Konfigurationsphase direkten Zugriff auf Gradle-Aufgaben und interne Konfigurationen, was die modernen Gradle-Leistungsfunktionen beeinträchtigt.

Die neue Variant API (androidComponents {}) ist lazy und artefaktzentriert. Dabei wird die Property API von Gradle intensiv genutzt und alle Verweise auf Task und TaskProvider werden entfernt. Sie müssen also sauber mit Ein- und Ausgaben (Variant.artifacts) interagieren und nicht mit den zugrunde liegenden Aufgaben selbst.

Was wird entfernt und ersetzt?

Alle bisherigen Schnittstellen und Klassen, die im alten DSL und in der alten Variant API verwendet wurden, werden gelöscht. Bereiten Sie Ihre Build-Skripts und benutzerdefinierten Plug-ins vor, indem Sie die folgenden APIs und Flags, die nicht mehr unterstützt werden, migrieren:

Entfernte API oder Funktion Ersatz oder Aktion erforderlich
Direkter Aufgabenzugriff:
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
 Artifacts API:Anstatt die Aufgabe abzurufen, um ihr Verhalten zu ändern, verwenden Sie variant.artifacts, um tatsächliche Dateien (Artefakte) anzuhängen, zu ändern oder zu ersetzen, die zwischen Aufgaben übergeben werden.
Eager Source Registration:
  • registerJavaGeneratingTask()
  • registerResGeneratingTask()
 Sources API:Verbinden Sie das Ausgabeverzeichnis Ihrer benutzerdefinierten Aufgabe mit variant.sources.java.addGeneratedSourceDirectory(...).
Classpath-/Konfigurationszugriff:
  • getCompileConfiguration()
  • getCompileClasspath()
 Instrumentation API:Wenn Sie Bytecode ändern oder prüfen möchten (der häufigste Anwendungsfall für den Zugriff auf den Klassenpfad), verwenden Sie variant.instrumentation.transformClassesWith(...) mit AsmClassVisitorFactory.
Eager-Property-Mutation:
  • buildConfigField()
  • resValue()
 Lazy-Instanzen von `MapProperty`: Verwenden Sie variant.buildConfigFields.put(...) und variant.manifestPlaceholders.put(...).
Deaktivierungs-Flags:
  • android.newDsl
  • android.builtInKotlin
 Kein direkter Ersatz. Entfernen Sie diese Flags aus gradle.properties. Die moderne DSL und das integrierte Kotlin werden streng durchgesetzt.
Legacy Variant API-Erweiterungen:
  • applicationVariants
  • libraryVariants
  • testVariants
  • unitTestVariants
 Ersetzen durch androidComponents.onVariants().
Variantenfilterung (variantFilter-Block) Ersetzen Sie androidComponents.beforeVariants() durch Variantenauswahlen.
SDK- und NDK-Komponenten:
  • sdkDirectory
  • ndkDirectory
  • bootClasspath
  • adbExecutable
 Über androidComponents.sdkComponents auf SDK-Komponenten zugreifen.
Testumgebungen:
  • deviceProvider
  • testServer
 Benutzerdefinierte Testgeräteregistrierung zu von Gradle verwalteten Geräten migrieren
Veraltete Registrierungs-APIs:
  • registerArtifactType
  • registerBuildTypeSourceProvider
  • registerProductFlavorSourceProvider
  • registerJavaArtifact
  • registerMultiFlavorSourceProvider
  • wrapJavaSourceSet
 Gelöscht, ohne direkten Ersatz.
Transform API Ersetzen Sie „transforms“ durch die Artifacts API und AsmClassVisitorFactory.

Wenn Sie auf alle Ersatz-DSL- und Variant API-Schnittstellen und -Klassen (androidComponents {}) zugreifen möchten, verwenden Sie beim Entwickeln benutzerdefinierter Gradle-Plug-ins oder Build-Logik immer das Artefakt gradle-api.

Migrationsschritte

Damit das Upgrade auf AGP 10.0 reibungslos und vorhersehbar verläuft, sollten Sie die folgenden Migrationsverfahren beachten:

  1. AGP-Upgrade-Assistenten ausführen:Bevor Sie direkt auf Version 10.0 aktualisieren, führen Sie den offiziellen AGP-Upgrade-Assistenten in Android Studio (Tools > AGP Upgrade Assistant) aus. Er automatisiert mehrere häufige DSL- und Build-Skript-Migrationen und trägt dazu bei, das vorhandene Build-Verhalten beizubehalten.
  2. Agent-Modus-Skills in Android Studio verwenden:Nutzen Sie KI-Upgrade-Skills (z. B. die AGP-Upgrade-Skills, die im Android-Skills-Repository verfügbar sind), um die Migration komplexer Build-Logik und DSLs in Android Studio zu automatisieren und zu vereinfachen.
  3. Veralteten Code in AGP 9.x zuerst korrigieren:Aktualisieren Sie Ihr Projekt auf die aktuelle AGP 9.x-Version und beheben Sie alle vorhandenen Warnungen zu veraltetem Code. Wenn Ihr Projekt mit Version 9.x ohne Warnungen und ohne android.newDsl=false oder android.builtInKotlin=false funktioniert, ist der Übergang zu Version 10.0 problemlos möglich.
  4. Gradle-Plug-ins von Drittanbietern prüfen:Achten Sie darauf, dass Plug-ins von Drittanbietern auf Versionen aktualisiert werden, die mit AGP 10.0 kompatibel sind. Bei Plugins, die noch auf Legacy-Erweiterungstypen basieren, treten Build-Fehler wie ClassCastException: ... cannot be cast to class BaseExtension auf.
  5. Offizielle Migrationsrezepte verwenden:Komplexe, praxisnahe Migrationsbeispiele und Gegenüberstellungen finden Sie im offiziellen GitHub-Repository „gradle-recipes“.

Hier sehen Sie einen Vorher-Nachher-Vergleich, der zeigt, wie Sie von der sofortigen Abfrage von Legacy-Varianten zur verzögerten Konfiguration von Varianten mit androidComponents {} migrieren:

Vorher: Legacy Variant API (in AGP 10.0 entfernt)

// Eager evaluation using the legacy Variant API
android {
    applicationVariants.all { variant ->
        if (variant.buildType.name == "release") {
            // Eagerly queries and modifies properties during evaluation
        }
    }
}

Nachher: Modern Variant API (androidComponents {})

// Lazy, Configuration Cache compatible Variant API
androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        // Safely and lazily configures properties
    }
}

Verhalten von AGP 10.0 in AGP 9.x testen

Sie müssen nicht auf die Veröffentlichung von AGP 10.0 warten, um das Build-Verhalten zu testen und die Kompatibilität zu prüfen. Wenn Sie eine AGP 9.x-Version verwenden, können Sie das Verhalten von AGP 10.0 explizit erzwingen, indem Sie prüfen, ob in Ihrem gradle.properties alle Opt-outs deaktiviert und die folgenden Flags für strenges Verhalten festgelegt sind:

# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true

# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true

Durch die Erzwingung von android.newDsl=true und android.builtInKotlin=true können Sie überprüfen, ob Ihre benutzerdefinierte Build-Logik und Ihre Drittanbieter-Plug-ins vollständig mit den strengen API-Anforderungen von AGP 10.0 kompatibel sind.

Selektiver Widerruf für Unterprojekte während der Migration

Wenn Sie android.newDsl=true global in Ihrem Projekt aktivieren möchten, um moderne Verhaltensweisen zu testen, aber mehr Zeit für die Migration bestimmter Unterprojekte benötigen, können Sie einzelne Module ab AGP 9.4.0-alpha04 selektiv deaktivieren. Fügen Sie android.newDsl.optOut zu gradle.properties hinzu, um Projektpfade anzugeben:

# Enable modern DSL globally across the build
android.newDsl=true

# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib

Selektive Deaktivierung von integriertem Kotlin pro Modul

Wenn Sie integriertes Kotlin global für Ihr Projekt (android.builtInKotlin=true) aktivieren möchten, aber mehr Zeit für die Migration bestimmter Unterprojekte von kotlin-android benötigen (oder für Module ohne Kotlin-Code), konfigurieren Sie diese Module auf DSL-Ebene und nicht auf Projektebene. Legen Sie enableKotlin = false in der Build-Datei des Moduls fest:

android {
    enableKotlin = false
}

Workflow für Feedback und Fehlerberichte

Wir möchten sichergehen, dass die neue Variant API Ihre erforderlichen Anwendungsfälle unterstützt. Wenn Sie bei der Migration von den alten APIs auf ein Problem stoßen, bei dem die neue Variant API Ihren Anwendungsfall nicht abdecken kann, gehen Sie so vor, um Feedback zu geben:

  1. Vorhandene Elemente prüfen:Prüfen Sie zuerst den globalen Tracking-Fehler für die AGP 10.0 Variant API, um festzustellen, ob Ihr Migrationsblocker bereits bekannt ist, und geben Sie dem Problem ein „+1“.
  2. Fehlende APIs melden:Wenn Ihr Anwendungsfall einzigartig ist, stellen Sie eine neue Funktionsanfrage mit unserer speziellen Variant API-Vorlage, damit wir die Anfrage prüfen und Ihnen helfen können.

(Vorläufig) Zugriff auf private interne AGP-Klassen wird entfernt

Durch die Abhängigkeit vom gradle-Artefakt werden jetzt alle internen Klassen ausgeblendet und der Kompilierungszugriff ist nur auf die Schnittstellen und Klassen beschränkt, die im gradle-api-Artefakt verfügbar sind. Dies wirkt sich auf die Plugin-Kompilierung aus.

Es ist nicht möglich, manuell eine Abhängigkeit hinzuzufügen, um Zugriff auf die internen Klassen zu erhalten.

AGP 9.0 (Januar 2026)

Neue Variant APIs sind stabil, alte APIs sind veraltet

Die Variant APIs, die sich in den Versionen 4.1 und 4.2 in der Inkubationsphase befanden, sind jetzt stabil und befinden sich im Artefakt gradle-api. Die bisherigen Schnittstellen und Klassen, die in der alten Variant API verwendet wurden, sind jetzt veraltet und erfordern eine explizite Einwilligung.

Neue DSL-Schnittstellen sind stabil, alte sind veraltet

Die DSL-Schnittstellen, die sich in den Versionen 4.1, 4.2 und 7.0 in der Inkubationsphase befanden, sind jetzt stabil und befinden sich im gradle-api-Artefakt. Die bisherigen Schnittstellen und Klassen, die in der DSL verwendet wurden, sind jetzt veraltet und erfordern eine explizite Einwilligung für die Verwendung.

Private interne AGP-Kurse sind weiterhin zugänglich

Private interne Klassen aus AGP, die sich in anderen Artefakten befinden, sind während der Kompilierung von Build-Dateien und ‑Plug-ins weiterhin zugänglich. Wir empfehlen jedoch, sie nicht zu verwenden, da sie sich jederzeit auf inkompatible Weise ändern können.