Asystent uaktualniania wtyczki Androida do obsługi Gradle (AGP) to narzędzie w Androidzie Studio, które pomaga uaktualnić wersję AGP używaną w projekcie.
Często publikujemy zmiany AGP związane z nowymi funkcjami konfigurowania kompilacji, nowymi interfejsami API do używania przez inne wtyczki Gradle i ulepszeniami integracji kompilacji projektu z Androidem 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 wtyczki AGP przeprowadzi Cię przez zmiany wymagane do uaktualnienia wersji wtyczki AGP. Oto najczęstsze przypadki użycia Asystenta uaktualniania:
Zmiany w składni: Asystent uaktualniania próbuje przetłumaczyć pliki kompilacji starszej wersji AGP na pliki wymagane w nowszej wersji 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 a Gradle: Asystent uaktualniania zna wymagania dotyczące zgodności między AGP a Gradle i pomaga upewnić się, że używasz wersji Gradle wymaganej w przypadku Twojej wersji AGP.
Wymagania dotyczące zgodności między AGP a wtyczkami Gradle innych firm: Asystent uaktualniania zna wymagania dotyczące zgodności między AGP a niektórymi wtyczkami Gradle innych firm i pomaga zapewnić, że używasz wersji wtyczek Gradle innych firm, które są wymagane w Twojej wersji AGP.
Asystent uaktualniania ułatwia aktualizowanie plików kompilacji i rozumienie powiązanych z nimi komunikatów o błędach po uaktualnieniu AGP. Asystent uaktualniania 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 Androidzie Studio zgodnie z opisem w sekcji Uruchamianie Asystenta uaktualniania.
Konfigurowanie projektu
Zanim uruchomisz Asystenta uaktualniania, upewnij się, że projekt jest prawidłowo sformatowany i ma kopię zapasową. Aby mieć pewność, że Asystent uaktualniania AGP jest prawidłowo skonfigurowany, zapoznaj się z poniższymi sekcjami.
Strukturyzowanie projektu za pomocą plików kompilacji Gradle i języka specyficznego dla domeny
Aby w pełni wykorzystać możliwości Asystenta uaktualniania AGP, wykonaj te czynności:
- Skonfiguruj kompilację za pomocą plików kompilacji Gradle: Asystent uaktualniania korzysta ze statycznej analizy plików kompilacji Gradle. Aby w pełni wykorzystać możliwości Asystenta uaktualniania, skonfiguruj kompilację za pomocą tych plików kompilacji. Użyj katalogów wersji Gradle, aby odwoływać się do zależności i wtyczek zdefiniowanych w pliku
libs.versions.tomlw podkatalogugradleprojektu.
- Używaj deklaratywnego języka DSL kompilacji: pliki kompilacji Gradle są wyrażone w języku Groovy lub Kotlin. Im bardziej deklaratywne jest wyrażenie konfiguracji projektu, tym większe prawdopodobieństwo, że Asystent uaktualniania znajdzie wszystkie miejsca, które wymagają dostosowania do uaktualnienia.
Nawet jeśli projekt spełnia te ograniczenia, Asystent uaktualniania może nie być w stanie przeprowadzić czystego uaktualnienia. W artykule Rozwiązywanie problemów znajdziesz wskazówki dotyczące rozwiązywania błędów i zgłaszania ich.
Tworzenie kopii zapasowej projektu
Zanim użyjesz Asystenta uaktualniania, sprawdź, czy w projekcie nie ma żadnych niezatwierdzonych zmian (zgodnie z informacjami w systemie kontroli wersji). Jeśli nie korzystasz z kontroli wersji, użyj w tym momencie kopii zapasowej ostatniej znanej prawidłowej wersji.
Po uruchomieniu Asystenta uaktualniania i pomyślnym utworzeniu oraz przetestowaniu projektu możesz zatwierdzić nową wersję projektu w systemie kontroli wersji.
Uruchom Asystenta uaktualniania
Aby uruchomić Asystenta uaktualniania, wykonaj te czynności:
Aby uruchomić Asystenta uaktualniania, otwórz 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 w projekcie i najnowszą wersję obsługiwaną przez tę wersję Androida Studio.
Rysunek 1. Okno narzędzia Asystent uaktualniania AGP uruchomione z poziomu powiadomienia. Sprawdź wymagane i zalecane kroki.
W panelu po lewej stronie znajduje się drzewo z polami wyboru, które zawiera szczegółowe informacje o poszczególnych etapach uaktualniania, podzielone na kategorie według tego, czy są wymagane, czy zalecane, oraz czy są warunkiem wstępnym innych etapów. Wybierz poszczególne elementy w drzewie, aby wyświetlić więcej szczegółów o każdym kroku w panelu głównym.
Aby przeprowadzić uaktualnienie, wybierz wymagane i odpowiednie kroki, a następnie kliknij Uruchom wybrane kroki.
Asystent uaktualniania zmienia pliki kompilacji projektu i próbuje zsynchronizować nową kompilację projektu z Android Studio. Jeśli masz wiele modułów, może to potrwać dłużej, ponieważ konieczne może być pobranie nowych wersji wtyczek i bibliotek.
Sprawdź raport po uaktualnieniu. Ten raport zawiera opis wykonanych czynności oraz informację o tym, czy uaktualnienie się powiodło. Obejmuje też działanie, które umożliwia przywrócenie zmian wprowadzonych przez asystenta uaktualniania, jeśli po uaktualnieniu wystąpią problemy z kompilacją lub testowaniem projektu.
Gdy projekt zostanie zsynchronizowany z Androidem Studio, skompiluj go i uruchom pakiety testów, aby sprawdzić, czy operacja uaktualnienia nie zmieniła żadnej funkcji.
Gdy upewnisz się, że projekt jest w dobrym stanie, zatwierdź nową wersję projektu w systemie kontroli wersji.
Rozwiązywanie problemów
Jeśli Asystent uaktualniania sugeruje uaktualnienie, ale uaktualnienie się nie powiedzie, zwykle jest to spowodowane wprowadzeniem zmian w plikach kompilacji, co powoduje niepowodzenie synchronizacji. Aby zlokalizować i naprawić błąd, wykonaj te czynności:
Najpierw sprawdź błąd, który spowodował niepowodzenie synchronizacji. Czasami błąd ma oczywistą przyczynę, którą można rozwiązać w plikach kompilacji projektu.
Jeśli komunikat o błędzie jest niejasny lub nie wiesz, 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 zsynchronizowany z Androidem Studio.
Zbadaj błąd, korzystając z 2 rodzajów podziałów uaktualnienia:
Uaktualnij do innej wersji AGP, która nie jest najnowsza. Jeśli nieudane uaktualnienie obejmowało dużą liczbę wersji, najlepszym sposobem na wyizolowanie problemu jest przeprowadzenie serii mniejszych uaktualnień, od wersji do wersji, aby znaleźć pierwsze uaktualnienie, które powoduje problem.
W ramach uaktualnienia wykonuj poszczególne kroki pojedynczo. Gdy ustalisz, które uaktualnienie powoduje problem, możesz wyłączyć poszczególne kroki uaktualnienia. Jeśli to możliwe, wykonuj każdy krok pojedynczo, aby sprawdzić, który z nich jest przyczyną błędu. Jeśli nie możesz znaleźć odpowiedzialnego za to kroku, 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żywania wycofanych lub wewnętrznych interfejsów API.
Zgłoś błąd. Czasami wszystkie kroki przygotowawcze i synchronizacja przebiegają pomyślnie, ale ostatni krok uaktualniania kończy się niepowodzeniem. W takim przypadku zgłoś błąd. Nawet jeśli uda Ci się samodzielnie naprawić błąd, zgłoś pierwotną awarię w narzędziu do śledzenia błędów, aby zespół programistów mógł rozwiązać ten problem.