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.

android skills add agp-9-upgrade

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 uaktualnienia 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 rzecz biorąc, 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 tym 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:

• Skonfiguruj kompilację za pomocą plików kompilacji Gradle: asystent uaktualnienia 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żone w języku 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.

Nawet jeśli projekt spełnia te ograniczenia, asystent uaktualnienia może nie być w stanie przeprowadzić czystego uaktualnienia. Wskazówki dotyczące rozwiązywania problemów 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 uaktualnienia, kliknij Tools > AGP Upgrade Assistant (Narzędzia > Asystent uaktualnienia 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ę Androida Studio.

   

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 głównym panelu.

3. Aby przeprowadzić uaktualnienie, wybierz wymagane i pożądane kroki, 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. Sprawdź 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 uaktualniania, jeśli po uaktualnieniu wystąpią problemy z kompilacją lub testowaniem projektu.

5. Po zsynchronizowaniu projektu z Android Studio skompiluj go i uruchom zestawy testów, aby sprawdzić, czy uaktualnienie nie zmieniło ż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 kończy się niepowodzeniem. 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ł się nim zająć.