Upgrade Assistant für das Android-Gradle-Plug-in verwenden

Der Android Gradle-Plug-in-Upgrade-Assistent (Android Gradle Plugin, AGP) ist ein Tool in Android Studio, mit dem Sie die AGP-Version aktualisieren können, die von Ihrem Projekt verwendet wird.

Es gibt häufig Releases für AGP-Änderungen im Zusammenhang mit neuen Funktionen zum Konfigurieren Ihres Builds, neuen APIs für die Verwendung durch andere Gradle-Plug-ins und Verbesserungen der Integration des Projekterstellungsprozesses in Android Studio. Wenn Sie die AGP-Version aktualisieren, die von Ihrem Projekt verwendet wird, können Sie die neuesten Funktionen nutzen.

Weitere Informationen zur empfohlenen Projekt struktur für den Upgrade-Assistenten finden Sie auf dieser Seite unter Einrichtung.

Anwendungsfälle für den AGP-Upgrade-Assistenten

Der AGP-Upgrade-Assistent führt Sie durch die Änderungen, die für das Upgrade von AGP-Versionen erforderlich sind. Im Folgenden sind die häufigsten Anwendungsfälle für den Upgrade-Assistenten aufgeführt:

• Syntaxänderungen: Der Upgrade-Assistent versucht, Ihre Build Dateien für eine ältere AGP-Version in die für eine neuere AGP-Version erforderlichen Dateien zu übersetzen. Im Zuge der AGP-Entwicklung werden Build-Dateien aktualisiert, um Schnittstellen zu unterstützen, wenn diese im Laufe der Zeit ersetzt, als veraltet gekennzeichnet oder nicht mehr unterstützt werden.

• Kompatibilitätsanforderungen zwischen AGP und Gradle: Der Upgrade-Assistent kennt die Kompatibilitätsanforderungen zwischen AGP und Gradle und sorgt dafür, dass Sie die für Ihre AGP-Version erforderliche Gradle-Version verwenden.

• Kompatibilitätsanforderungen zwischen AGP und Gradle-Plug-ins von Drittanbietern: Der Upgrade-Assistent kennt die Kompatibilitätsanforderungen zwischen AGP und einigen Gradle-Plug-ins von Drittanbietern und sorgt dafür, dass Sie die Versionen der Gradle-Plug-ins von Drittanbietern verwenden, die für Ihre AGP-Version erforderlich sind.

Im Allgemeinen erleichtert der Upgrade-Assistent das Aktualisieren von Build-Dateien und das Verstehen zugehöriger Fehlermeldungen nach einem AGP-Upgrade. Der Upgrade-Assistent erklärt auch, warum die vorgeschlagenen Änderungen erforderlich sind.

AGP-Upgrade-Assistent verwenden

Wenn Sie den Upgrade-Assistenten verwenden möchten, muss Ihre Projektstruktur für das Tool geeignet sein. Führen Sie es dann in Android Studio aus, wie unter Upgrade-Assistent ausführen beschrieben.

Projekt einrichten

Bevor Sie den Upgrade-Assistenten ausführen, prüfen Sie, ob Ihr Projekt richtig formatiert und gesichert ist. Lesen Sie die folgenden Abschnitte, um sicherzustellen, dass der AGP-Upgrade-Assistent richtig eingerichtet ist.

Projekt mit den Gradle-Build-Dateien und der domänenspezifischen Sprache strukturieren

So nutzen Sie den AGP-Upgrade-Assistenten optimal:

• Build mit den Gradle-Build-Dateien konfigurieren: Der Upgrade-Assistent basiert auf der statischen Analyse der Gradle-Build-Dateien. Konfigurieren Sie Ihren Build mit diesen Build-Dateien, um den Upgrade-Assistenten optimal zu nutzen. Verwenden Sie Gradle-Versionskataloge um auf Abhängigkeiten und Plug-ins zu verweisen, die in einer libs.versions.toml Datei im Unterverzeichnis gradle Ihres Projekts definiert sind.

• Deklarative domänenspezifische Sprache für den Build verwenden: Gradle-Build-Dateien werden in Groovy oder Kotlin ausgedrückt. Je deklarativer der Ausdruck der Projektkonfiguration ist, desto wahrscheinlicher ist es, dass der Upgrade-Assistent alle Stellen findet, die für ein Upgrade angepasst werden müssen.

Auch wenn ein Projekt diesen Einschränkungen entspricht, kann der Upgrade-Assistent möglicherweise kein sauberes Upgrade durchführen. Unter Fehler beheben finden Sie eine Anleitung zum Beheben oder Melden von Fehlern.

Projekt sichern

Bevor Sie den Upgrade-Assistenten verwenden, empfehlen wir, dass Ihr Projekt keine nicht übertragenen Änderungen enthält, wie in Ihrem Versionsverwaltungssystem zu sehen. Wenn Sie keine Versionsverwaltung verwenden, verwenden Sie an dieser Stelle eine Sicherung einer letzten bekannten funktionierenden Version.

Nachdem der Upgrade-Assistent ausgeführt wurde und das Projekt erfolgreich erstellt und getestet wurde, können Sie die neue Version des Projekts in Ihr Versionsverwaltungssystem übertragen.

Upgrade-Assistent ausführen

So führen Sie den Upgrade-Assistenten aus:

1. Rufen Sie den Upgrade-Assistenten auf, indem Sie zu Tools > AGP Upgrade Assistant navigieren oder auf die Benachrichtigungsaufforderung klicken, wie in Abbildung 1 gezeigt.

   Im angezeigten Toolfenster werden die Details des Standard-Upgrades angezeigt, einschließlich der aktuellen AGP-Version des Projekts und der neuesten Version, die von dieser Android Studio-Version unterstützt wird.

   

2. Prüfen Sie die erforderlichen und empfohlenen Schritte.

   Im linken Bereich enthält die Struktur mit Kontrollkästchen Details zu den einzelnen Schritten des Upgrades, kategorisiert danach, ob sie für die Aktualisierung erforderlich oder empfohlen sind und ob sie Voraussetzungen für andere Schritte sind. Wählen Sie einzelne Elemente in der Struktur aus, um weitere Details zu den einzelnen Schritten im Hauptbereich anzuzeigen.

3. Wenn Sie das Upgrade ausführen möchten, wählen Sie die erforderlichen und gewünschten Schritte aus und klicken Sie auf Ausgewählte Schritte ausführen.

   Der Upgrade-Assistent ändert die Build-Dateien des Projekts und versucht, den neuen Projekt-Build mit Android Studio zu synchronisieren. Das kann eine Weile dauern, wenn Sie viele Module haben, da möglicherweise neue Versionen von Plug-ins und Bibliotheken heruntergeladen werden müssen.

4. Sehen Sie sich den Bericht nach dem Upgrade an. In diesem Bericht werden die abgeschlossenen Schritte beschrieben und angegeben, ob das Upgrade erfolgreich war. Er enthält auch eine Aktion zum Rückgängigmachen von Änderungen, die vom Upgrade-Assistenten vorgenommen wurden, wenn es nach dem Upgrade Probleme beim Erstellen oder Testen des Projekts gibt.

5. Nachdem das Projekt erfolgreich mit Android Studio synchronisiert wurde, erstellen Sie das Projekt und führen Sie Testsuites aus, um zu prüfen, ob das Upgrade keine Änderungen an der Funktionalität vorgenommen hat.

6. Nachdem Sie geprüft haben, ob sich Ihr Projekt in einem guten Zustand befindet, übertragen Sie die neue Version Ihres Projekts in Ihr Versionsverwaltungssystem.

Fehler beheben

Wenn der Upgrade-Assistent ein Upgrade vorschlägt, das aber fehlschlägt, liegt das in der Regel daran, dass Änderungen an den Build-Dateien vorgenommen wurden, was zu einem Synchronisierungsfehler führt. Gehen Sie so vor, um den Fehler zu isolieren und zu beheben:

• Sehen Sie sich zuerst den Fehler an, der zum Synchronisierungsfehler geführt hat. Manchmal hat der Fehler eine klare Ursache, die Sie in den Build-Dateien des Projekts beheben können.

• Wenn die Fehlermeldung nicht klar ist oder die Ursache des Problems nicht offensichtlich ist, setzen Sie das Projekt in den ursprünglichen Zustand zurück, um das Upgrade in kleinere Schritte zu unterteilen. Stellen Sie den ursprünglichen Zustand aus der Versionsverwaltung oder aus Sicherungen wieder her und prüfen Sie, ob sich das Projekt im ursprünglichen Zustand befindet und mit Android Studio synchronisiert ist.

Untersuchen Sie den Fehler, indem Sie zwei Arten von Upgrade-Aufschlüsselungen ausführen:

• Upgrade auf eine andere AGP-Version als die neueste Version Wenn das fehlgeschlagene Upgrade ein Upgrade einer großen Anzahl von Versionen war, können Sie das Problem am besten isolieren, indem Sie eine Reihe kleinerer Upgrades von Version zu Version durchführen, um das erste Upgrade zu finden, das das Problem auslöst.

• Führen Sie die einzelnen Schritte eines Upgrades nacheinander aus. Sobald Sie das Upgrade ermittelt haben, das das Problem auslöst, können Sie möglicherweise einzelne Schritte im Upgrade deaktivieren. Wenn das möglich ist, führen Sie jeden Schritt einzeln aus, um herauszufinden, welcher Schritt für den Fehler verantwortlich ist. Wenn Sie den verantwortlichen Schritt nicht finden können, prüfen Sie die Versionshinweise aller anderen Gradle-Plug-ins, die Sie verwenden, auf Kompatibilitätsprobleme mit Gradle oder AGP. Manchmal wird mit einer Neuveröffentlichung die Verwendung veralteter oder interner APIs behoben.

• Fehler melden. Manchmal sind alle vorbereitenden Schritte und die Synchronisierung erfolgreich, aber der letzte Upgrade-Schritt schlägt trotzdem fehl. In diesem Fall melden Sie bitte einen Fehler. Auch wenn Sie den Fehler selbst beheben können, melden Sie den ursprünglichen Fehler im Bugtracker, so dass das Problem vom Entwicklungsteam behoben werden kann.