Asystent uaktualniania do obsługi Gradle (Android Gradle) to narzędzie dostępne w Android Studio, które pomaga uaktualnić wersję pakietu AGP używaną w projekcie.
Często pojawiają się zmiany w AGP związane z nowymi funkcjami konfigurowania kompilacji, nowymi interfejsami API do użycia przez inne wtyczki Gradle oraz ulepszeniami integracji kompilacji projektu z Androidem Studio. Uaktualnienie wersji AGP używanej w Twoim projekcie umożliwia korzystanie 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 aktualizacji AGP przeprowadzi Cię przez zmiany niezbędne do uaktualnienia wersji AI. Oto najczęstsze przypadki użycia Asystenta uaktualnienia:
Zmiany składni: Asystent uaktualniania próbuje przetłumaczyć pliki kompilacji dla starszej wersji AGP na pliki wymagane w jej nowszej wersji. W miarę opracowywania AGP pliki kompilacji są aktualizowane pod kątem obsługi interfejsów w miarę ich zastępowania, wycofywania lub nieobsługiwanego.
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 Twojej wersji AGP.
Wymagania dotyczące zgodności między wtyczkami AGP i wtyczkami Gradle innych firm: Asystent uaktualniania wie o wymaganiach dotyczących zgodności między AGP a niektórymi wtyczkami Gradle innych firm i upewnia się, że używasz wersji wtyczek innych firm do Gradle, które są wymagane w Twojej wersji systemu AGP.
Ogólnie rzecz biorąc, Asystent uaktualniania ułatwia aktualizowanie plików kompilacji i rozumie powiązane komunikaty o błędach po uaktualnieniu AGP. Asystent uaktualniania wyjaśnia również, dlaczego proponowane zmiany są konieczne.
Jak korzystać z Asystenta aktualizacji AGP
Aby skorzystać z Asystenta uaktualniania, upewnij się, że struktura projektu zawiera to narzędzie, a potem uruchom go z poziomu Android Studio zgodnie z opisem w sekcji Uruchamianie Asystenta uaktualnienia.
Konfigurowanie projektu
Zanim uruchomisz Asystenta uaktualniania, sprawdź, czy projekt jest poprawnie sformatowany i ma kopię zapasową. Aby mieć pewność, że Asystent uaktualniania AGP jest prawidłowo skonfigurowany, zapoznaj się z sekcjami poniżej.
Utwórz strukturę projektu za pomocą plików kompilacji Gradle i języka specyficznego dla domeny
Aby w pełni wykorzystać możliwości Asystenta aktualizacji AGP:
- Skonfiguruj kompilację za pomocą plików kompilacji Gradle: Asystent uaktualniania wymaga analizy statycznej plików kompilacji Gradle. Aby w pełni wykorzystać możliwości Asystenta aktualizacji, skonfiguruj kompilację, korzystając z tych plików.
- Użyj deklaratywnego języka kompilacji specyficznego dla domeny: pliki kompilacji Gradle są wyrażane w Groovy lub Kotlin. Jednak im bardziej deklaratywne wyrażenie konfiguracji projektu, tym większe prawdopodobieństwo, że Asystent uaktualniania znajdzie wszystkie miejsca wymagające korekty.
Nawet jeśli projekt spełnia te ograniczenia, Asystent uaktualniania może nie przeprowadzić czystego uaktualnienia. Wskazówki dotyczące naprawiania i zgłaszania błędów znajdziesz w sekcji Rozwiązywanie problemów.
Tworzenie kopii zapasowej projektu
Zanim użyjesz Asystenta uaktualniania, zalecamy, aby Twój projekt nie zawierał niezatwierdzonych zmian, które widzi system kontroli wersji. Jeśli nie korzystasz z kontroli wersji, utwórz kopię zapasową ostatniej znanej prawidłowej wersji.
Gdy Asystent uaktualniania zostanie uruchomiony, a projekt zostanie skompilowany i przetestowany, możesz zatwierdzić nową wersję projektu w swoim systemie kontroli wersji.
Uruchom Asystenta uaktualniania
Aby uruchomić Asystenta uaktualniania, wykonaj te czynności:
Aby uruchomić Asystenta uaktualniania, wybierz Narzędzia > Asystent uaktualniania AGP lub kliknij powiadomienie (jak pokazano na rysunku 1).
Pojawi się okno narzędzia ze szczegółowymi informacjami o domyślnej aktualizacji, w tym o bieżącej wersji interfejsu AGP projektu oraz najnowszej wersji obsługiwanej przez tę wersję Android Studio.
Rysunek 1. Okno narzędzia Asystent uaktualniania AGP po uruchomieniu z prośbą o powiadomienie. Sprawdź wymagane i zalecane kroki.
Drzewo z polami wyboru w panelu po lewej stronie zawiera szczegóły poszczególnych kroków uaktualnienia. Są one podzielone na kategorie według tego, czy są one wymagane czy zalecane do zaktualizowania, a także czy wymagają innych kroków. Wybierz poszczególne elementy w drzewie, aby wyświetlić więcej informacji o każdym kroku w panelu głównym.
Aby przeprowadzić uaktualnienie, wybierz wymagane i odpowiednie kroki, a następnie kliknij Wykonaj wybrane kroki.
Asystent uaktualniania zmienia pliki kompilacji projektu i próbuje zsynchronizować nową kompilację z Android Studio. Może to chwilę potrwać, jeśli masz wiele modułów, ponieważ konieczne może być pobranie nowych wersji wtyczek i bibliotek.
Sprawdź raport po uaktualnieniu. Raport ten zawiera informacje o ukończonych krokach oraz o tym, czy uaktualnienie się powiodło. Obejmuje to też działanie umożliwiające wycofanie zmian wprowadzonych przez asystenta uaktualniania w przypadku problemów z tworzeniem lub testowaniem projektu po uaktualnieniu.
Po zsynchronizowaniu projektu z Androidem Studio skompiluj go i uruchom pakiety testowe, aby sprawdzić, czy operacja uaktualniania nie zmieniła żadnych funkcji.
Po sprawdzeniu, czy projekt jest w dobrym stanie, zatwierdź jego nową wersję w systemie kontroli wersji.
Rozwiązywanie problemów z błędami
Jeśli Asystent uaktualniania zasugeruje uaktualnienie, ale uaktualnienie się nie powiedzie, zwykle jest to spowodowane zmianami w plikach kompilacji, które skutkują niepowodzeniem synchronizacji. Aby wyodrębnić i rozwiązać problem, wykonaj te czynności:
Najpierw sprawdź błąd, który doprowadził do niepowodzenia synchronizacji. Czasami błąd ma jasną przyczynę, którą możesz usunąć 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 etapy. Przywróć oryginalny stan z kontroli wersji lub z kopii zapasowych i sprawdź, czy projekt jest w pierwotnym stanie i jest zsynchronizowany z Androidem Studio.
Sprawdź błąd, korzystając z 2 rodzajów podziałów uaktualnień:
Uaktualnij AGP do innej wersji. Jeśli aktualizacja zakończyła się niepowodzeniem, to uaktualnieniem dużej liczby wersji, najlepszym sposobem na wykrycie problemu jest przeprowadzenie serii mniejszych uaktualnień z każdej wersji do nowej, by znaleźć pierwsze uaktualnienie, które powoduje problem.
W ramach uaktualnienia wykonaj poszczególne kroki pojedynczo. Po określeniu uaktualnienia, które wywołuje problem, możesz wyłączyć jego poszczególne kroki. Jeśli to możliwe, spróbuj wykonać każdy krok po kolei, by sprawdzić, który z nich powoduje błąd. Jeśli nie możesz znaleźć odpowiedzi za ten krok, sprawdź informacje o wersji innych wtyczek Gradle, których używasz, pod kątem problemów ze zgodnością z Gradle lub AGP. Czasami nowa wersja dotyczy korzystania z wycofanych lub wewnętrznych interfejsów API.
Zgłoś błąd Czasami wszystkie kroki przygotowawcze i synchronizacja się sprawdzają, ale ostatni etap uaktualnienia nadal się nie powiedzie. W takim przypadku zgłoś błąd. Nawet jeśli uda Ci się samodzielnie naprawić błąd, zgłoś pierwotny błąd w narzędziu do śledzenia błędów, aby zespół programistów mógł rozwiązać problem.