Użyj Asystenta aktualizacji przy użyciu wtyczki Androida do obsługi Gradle

Asystent uaktualniania wtyczki Androida do obsługi Gradle (AGP) to narzędzie w Android Studio, które pomaga uaktualnić wersję AGP używaną w projekcie.

Często publikujemy aktualizacje AGP związane z nowymi funkcjami konfigurowania kompilacji, nowymi interfejsami API do użycia przez inne wtyczki Gradle oraz ulepszeniami integracji kompilacji projektu z Android Studio. Uaktualnienie wersji AGP używanej w projekcie pozwala korzystać z najnowszych funkcji.

Więcej informacji o zalecanej strukturze projektu dla asystenta uaktualniania znajdziesz w sekcji Konfiguracja na tej stronie.

Przypadki użycia asystenta uaktualniania AGP

Asystent uaktualniania AGP przeprowadzi Cię przez zmiany wymagane do uaktualnienia wersji AGP. Oto najczęstsze przypadki użycia asystenta uaktualniania:

  • Zmiany składni: asystent uaktualnienia próbuje przekonwertować pliki kompilacji starszej wersji AGP na pliki wymagane przez nowszą wersję AGP. W miarę rozwoju AGP pliki kompilacji są aktualizowane, aby obsługiwać interfejsy, które z czasem są zastępowane, wycofywane lub przestają być obsługiwane.

  • Wymagania dotyczące zgodności między AGP i Gradle: asystent uaktualnienia zna wymagania dotyczące zgodności między AGP i Gradle i pomaga upewnić się, że używasz wersji Gradle wymaganej przez Twoją wersję AGP.

  • Wymagania dotyczące zgodności między AGP a wtyczkami Gradle innych firm: asystent uaktualnienia zna wymagania dotyczące zgodności między AGP a niektórymi wtyczkami Gradle innych firm i pomaga upewnić się, że używasz wersji wtyczek Gradle innych firm, które są wymagane w przypadku Twojej wersji AGP.

Ogólnie asystent uaktualnienia ułatwia aktualizowanie plików kompilacji i interpretowanie powiązanych komunikatów o błędach po uaktualnieniu AGP. Asystent uaktualnienia wyjaśnia też, dlaczego proponowane zmiany są konieczne.

Jak korzystać z asystenta uaktualniania AGP

Aby użyć asystenta uaktualniania, upewnij się, że struktura projektu jest zgodna z narzędziem, a następnie uruchom je w Android Studio, jak opisano w sekcji Uruchamianie asystenta uaktualniania.

Konfigurowanie projektu

Zanim uruchomisz asystenta uaktualniania, upewnij się, że projekt jest prawidłowo sformatowany i ma kopię zapasową. Aby upewnić się, że asystent uaktualnienia AGP jest prawidłowo skonfigurowany, przeczytaj poniższe sekcje.

strukturyzować projekt za pomocą plików kompilacji Gradle i języka specyficznego dla domeny;

Aby jak najlepiej wykorzystać asystenta uaktualniania AGP, wykonaj te czynności:

  • Skonfiguruj kompilację za pomocą plików kompilacji Gradle: asystent uaktualniania opiera się na analizie statycznej plików kompilacji Gradle. Aby jak najlepiej wykorzystać możliwości asystenta uaktualniania, skonfiguruj kompilację za pomocą tych plików kompilacji. Używaj katalogów wersji Gradle, aby odwoływać się do zależności i wtyczek zdefiniowanych w pliku libs.versions.toml w podkatalogu gradle projektu.
  • Używaj deklaratywnego języka DSL do kompilacji: pliki kompilacji Gradle są wyrażane w Groovy lub Kotlin. Jednak im bardziej deklaratywna jest konfiguracja projektu, tym większe prawdopodobieństwo, że asystent uaktualnienia znajdzie wszystkie miejsca, które wymagają dostosowania do uaktualnienia.

Nawet jeśli projekt spełnia te wymagania, asystent uaktualnienia może nie być w stanie przeprowadzić czystego uaktualnienia. Wskazówki dotyczące rozwiązywania i zgłaszania błędów znajdziesz w artykule Rozwiązywanie problemów.

Tworzenie kopii zapasowej projektu

Zanim użyjesz asystenta uaktualniania, upewnij się, że w projekcie nie ma niezatwierdzonych zmian, które są widoczne w systemie kontroli wersji. Jeśli nie używasz kontroli wersji, użyj kopii zapasowej ostatniej znanej prawidłowej wersji.

Po uruchomieniu asystenta uaktualniania oraz pomyślnym utworzeniu i przetestowaniu projektu możesz zatwierdzić nową wersję projektu w systemie kontroli wersji.

Uruchamianie asystenta uaktualniania

Aby uruchomić asystenta uaktualniania, wykonaj te czynności:

  1. Aby uruchomić asystenta uaktualniania, kliknij Tools > AGP Upgrade Assistant (Narzędzia > Asystent uaktualniania AGP) lub kliknij powiadomienie, jak pokazano na rysunku 1.

    W wyświetlonym oknie narzędzia zobaczysz szczegóły domyślnego uaktualnienia, w tym bieżącą wersję AGP projektu i najnowszą wersję obsługiwaną przez tę wersję Android Studio.

    Okno narzędzia asystenta uaktualniania AGP po uruchomieniu i powiadomienie.
    Rysunek 1. Okno narzędzia asystenta uaktualniania AGP po uruchomieniu z powiadomieniem.

  2. Sprawdź wymagane i zalecane kroki.

    W panelu po lewej stronie drzewo z polami wyboru zawiera szczegółowe informacje o poszczególnych krokach uaktualnienia, podzielonych na kategorie według tego, czy są wymagane, czy zalecane, oraz czy są warunkiem wstępnym innych kroków. Wybierz poszczególne elementy w drzewie, aby wyświetlić więcej informacji o każdym kroku w panelu głównym.

  3. Aby przeprowadzić uaktualnienie, wybierz wymagane kroki i dodatkowe kroki, które chcesz wykonać, a następnie kliknij Uruchom wybrane kroki.

    Asystent uaktualnienia zmienia pliki kompilacji projektu i próbuje zsynchronizować nową kompilację projektu z Android Studio. Jeśli masz wiele modułów, może to trochę potrwać, ponieważ może być konieczne pobranie nowych wersji wtyczek i bibliotek.

  4. Przejrzyj raport po uaktualnieniu. Ten raport zawiera opis wykonanych czynności i informację o tym, czy uaktualnienie się powiodło. Zawiera też działanie umożliwiające cofnięcie zmian wprowadzonych przez asystenta uaktualnienia, jeśli po uaktualnieniu wystąpią problemy z kompilacją lub testowaniem projektu.

  5. Po pomyślnym zsynchronizowaniu projektu z Android Studio utwórz projekt i uruchom zestawy testów, aby sprawdzić, czy operacja uaktualnienia nie zmieniła żadnych funkcji.

  6. Gdy sprawdzisz, czy projekt jest w dobrym stanie, zatwierdź jego nową wersję w systemie kontroli wersji.

Rozwiązywanie problemów

Jeśli asystent uaktualnienia sugeruje uaktualnienie, ale się ono nie powiedzie, zwykle jest to spowodowane wprowadzeniem zmian w plikach kompilacji, co powoduje błąd synchronizacji. Aby wyizolować i naprawić błąd, wykonaj te czynności:

  • Najpierw sprawdź błąd, który spowodował niepowodzenie synchronizacji. Czasami błąd ma wyraźną przyczynę, którą można rozwiązać w plikach kompilacji projektu.

  • Jeśli komunikat o błędzie jest niejasny lub nie wiadomo, co powoduje problem, przywróć projekt do pierwotnego stanu, aby podzielić uaktualnienie na mniejsze kroki. Przywróć pierwotny stan z systemu kontroli wersji lub z kopii zapasowych i upewnij się, że projekt jest w pierwotnym stanie i jest zsynchronizowany z Android Studio.

Zbadaj błąd, korzystając z 2 rodzajów zestawień uaktualnień:

  • Przejście na inną wersję AGP, która nie jest najnowszą wersją. Jeśli nieudane uaktualnienie obejmowało dużą liczbę wersji, najlepszym sposobem na wyizolowanie problemu jest wykonanie serii mniejszych uaktualnień, od wersji do wersji, aby znaleźć pierwsze uaktualnienie, które powoduje problem.

  • W ramach uaktualnienia wykonuj poszczególne kroki po kolei. Gdy ustalisz, które uaktualnienie powoduje problem, możesz wyłączyć poszczególne kroki uaktualnienia. Jeśli to możliwe, spróbuj wykonać każdy krok po kolei, aby dowiedzieć się, który z nich jest odpowiedzialny za błąd. Jeśli nie możesz znaleźć kroku, który powoduje problem, sprawdź informacje o wersji innych używanych wtyczek Gradle pod kątem problemów ze zgodnością z Gradle lub AGP. Czasami nowa wersja dotyczy użycia wycofanych lub wewnętrznych interfejsów API.

  • Zgłoś błąd. Czasami wszystkie kroki przygotowawcze i synchronizacja kończą się powodzeniem, ale ostatni krok uaktualnienia nadal się nie udaje. W takim przypadku zgłoś błąd. Nawet jeśli uda Ci się samodzielnie naprawić błąd, zgłoś pierwotny problem w narzędziu do śledzenia błędów, aby zespół deweloperów mógł go rozwiązać.