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

Der Upgrade-Assistent für das Android-Gradle-Plug-in (AGP) ist ein Tool in Android Studio, mit dem Sie die von Ihrem Projekt verwendete AGP-Version aktualisieren können.

android skills add agp-9-upgrade

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

Weitere Informationen zur empfohlenen Projektstruktur 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 ein 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 Version von AGP in die für eine neuere Version von AGP erforderlichen Dateien zu übersetzen. Im Zuge der Entwicklung des AGP werden Build-Dateien aktualisiert, um Schnittstellen zu unterstützen, die im Laufe der Zeit ersetzt, eingestellt oder nicht mehr unterstützt werden.

• Kompatibilitätsanforderungen zwischen AGP und Gradle: Der Upgrade-Assistent kennt die Kompatibilitätsanforderungen zwischen AGP und Gradle und hilft Ihnen, die für Ihre AGP-Version erforderliche Gradle-Version zu 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 hilft Ihnen, die Versionen von Gradle-Plug-ins von Drittanbietern zu verwenden, die für Ihre AGP-Version erforderlich sind.

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

AGP-Upgrade-Assistent verwenden

Wenn Sie den Upgrade-Assistenten verwenden möchten, muss Ihre Projektstruktur mit dem Tool kompatibel sein. Führen Sie ihn dann in Android Studio aus, wie unter Upgrade-Assistenten ausführen beschrieben.

Projekt einrichten

Bevor Sie den Upgrade-Assistenten ausführen, müssen Sie Ihr Projekt richtig formatieren und sichern. In den folgenden Abschnitten erfahren Sie, wie Sie den AGP-Upgrade-Assistenten richtig einrichten.

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. Damit Sie den Upgrade-Assistenten optimal nutzen können, konfigurieren Sie Ihren Build mit diesen Build-Dateien. 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 Build-Sprache verwenden: Gradle-Build-Dateien werden in Groovy oder Kotlin ausgedrückt. Je deklarativer die Projektkonfiguration jedoch 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 diese Einschränkungen erfüllt, kann es sein, dass der Upgrade-Assistent kein sauberes Upgrade durchführt. Informationen zum Beheben oder Melden von Fehlern finden Sie unter Fehler beheben.

Projekt sichern

Bevor Sie den Upgrade-Assistenten verwenden, sollten Sie darauf achten, dass Ihr Projekt keine nicht übernommenen Änderungen enthält, wie in Ihrem Versionsverwaltungssystem zu sehen ist. Wenn Sie keine Versionsverwaltung verwenden, verwenden Sie an dieser Stelle eine Sicherung der letzten bekannten fehlerfreien 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-Assistenten ausführen

So führen Sie den Upgrade-Assistenten aus:

1. Wenn du den Upgrade-Assistenten starten möchtest, gehe zu Tools > AGP-Upgrade-Assistent oder klicke auf die Benachrichtigungsaufforderung, wie in Abbildung 1 dargestellt.

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

   

2. Sehen Sie sich die erforderlichen und empfohlenen Schritte an.

   Im linken Bereich finden Sie eine Baumstruktur mit Kästchen, in der die einzelnen Schritte des Upgrades aufgeführt sind. Sie sind danach kategorisiert, ob sie erforderlich oder empfohlen sind und ob sie Voraussetzungen für andere Schritte sind. Wählen Sie einzelne Elemente in der Baumstruktur aus, um im Hauptbereich weitere Details zu jedem Schritt aufzurufen.

3. Wählen Sie die erforderlichen und gewünschten Schritte aus und klicken Sie auf Ausgewählte Schritte ausführen, um das Upgrade auszuführen.

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

4. Prüfen Sie den Bericht nach dem Upgrade. In diesem Bericht werden die abgeschlossenen Schritte beschrieben und ob das Upgrade erfolgreich war oder nicht. Außerdem enthält er eine Aktion, mit der Sie Änderungen rückgängig machen können, die vom Upgrade-Assistenten vorgenommen wurden, falls nach dem Upgrade Probleme beim Erstellen oder Testen des Projekts auftreten.

5. Nachdem das Projekt erfolgreich mit Android Studio synchronisiert wurde, erstellen Sie das Projekt und führen Sie Test-Suites aus, um zu prüfen, ob sich durch das Upgrade die Funktionalität geändert hat.

6. Wenn Sie sich vergewissert haben, dass Ihr Projekt in einem guten Zustand ist, übertragen Sie die neue Version Ihres Projekts in Ihr Versionsverwaltungssystem.

Fehler beheben

Wenn der Upgrade-Assistent ein Upgrade vorschlägt, das Upgrade aber fehlschlägt, liegt das in der Regel daran, dass Änderungen an den Build-Dateien vorgenommen wurden, was zu einem Synchronisierungsfehler führt. Führe die folgenden Schritte aus, um den Fehler zu finden und zu beheben:

• Prüfen Sie zuerst den Fehler, 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 eindeutig 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 achten Sie darauf, dass das Projekt im ursprünglichen Zustand und mit Android Studio synchronisiert ist.

Untersuchen Sie den Fehler anhand von zwei Arten von Upgrade-Aufschlüsselungen:

• Upgrade auf eine andere AGP-Version, die nicht die aktuelle Version ist Wenn das fehlgeschlagene Upgrade ein Upgrade über eine große Anzahl von Versionen war, ist es am besten, das Problem zu 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. Wenn Sie das Upgrade ermittelt haben, das das Problem verursacht, können Sie möglicherweise einzelne Schritte im Upgrade deaktivieren. Wenn dies möglich ist, führen Sie jeden Schritt einzeln aus, um herauszufinden, welcher dieser Schritte für den Fehler verantwortlich ist. Wenn Sie den verantwortlichen Schritt nicht finden können, prüfen Sie die Versionshinweise aller anderen von Ihnen verwendeten Gradle-Plug-ins auf Kompatibilitätsprobleme mit Gradle oder AGP. Manchmal wird in einer neuen Version die Verwendung von verworfenen oder internen APIs behandelt.

• Fehler melden Manchmal sind alle Vorbereitungsschritte und die Synchronisierung erfolgreich, aber der letzte Upgradeschritt schlägt fehl. Bitte melde den Fehler in diesem Fall. Auch wenn Sie den Fehler selbst beheben können, melden Sie den ursprünglichen Fehler im Bugtracker, damit das Problem vom Entwicklungsteam behoben werden kann.