Android Gradle プラグイン（AGP）Upgrade Assistant は、プロジェクトで使用する AGP のバージョンをアップグレードするために役立つ Android Studio のツールです。
ビルドを設定するための新機能、他の Gradle プラグインによって使用される新しい API、プロジェクト ビルドと Android Studio との統合の改善に関連する AGP の変更が頻繁にリリースされています。プロジェクトによって使用される AGP のバージョンをアップグレードすると、最新の機能を利用できます。
Upgrade Assistant 用の推奨されるプロジェクト構造について詳しくは、このページのセットアップをご覧ください。
AGP Upgrade Assistant のユースケース
AGP Upgrade Assistant は、AGP バージョンをアップグレードするために必要な変更をガイドします。Upgrade Assistant の一般的なユースケースを次に示します。
構文の変更: Upgrade Assistant は、古い AGP バージョンのビルドファイルを、新しい AGP バージョンに必要なビルドファイルに変換しようと試みます。AGP の開発に伴い、インターフェースは時間の経過とともに置き換えられたり非推奨になったりサポートされなくなったりするため、ビルドファイルはインターフェースをサポートするように更新されます。
AGP と Gradle の互換性要件: Upgrade Assistant は、AGP と Gradle の互換性要件を認識し、お使いの AGP バージョンに必要な Gradle バージョンを確実に使用できるようにします。
AGP とサードパーティの Gradle プラグインの互換性要件: Upgrade Assistant は、AGP とサードパーティの Gradle プラグインの互換性要件を認識し、お使いの AGP バージョンに必要なサードパーティの Gradle プラグイン バージョンを確実に使用できるようにします。
一般的に、Upgrade Assistant を使用すると、ビルドファイルの更新が容易になり、AGP のアップグレード後は関連するエラー メッセージが理解しやすくなります。Upgrade Assistant は、提案される変更が必要な理由についても説明します。
AGP Upgrade Assistant の使用方法
Upgrade Assistant を使用するには、お使いのプロジェクトの構造がツールに対応していることを確認したうえで、Upgrade Assistant を実行する手順に沿って、Android Studio から Upgrade Assistant を実行します。
プロジェクトをセットアップする
Upgrade Assistant を実行する前に、プロジェクトが適切に構造化され、バックアップされていることを確認します。AGP Upgrade Assistant が正しくセットアップされていることを確認するには、以下のセクションをご覧ください。
Gradle ビルドファイルとドメイン固有の言語でプロジェクトを構造化する
AGP Upgrade Assistant を最大限に活用するには、次の手順を実施します。
- Gradle ビルドファイルでビルドを設定する: Upgrade Assistant は、Gradle ビルドファイルの静的分析に依存しています。Upgrade Assistant を最大限に活用するには、それらのビルドファイルを使用してビルドを設定します。
- 宣言型のビルドドメイン固有の言語を使用する: Gradle ビルドファイルは Groovy または Kotlin で表現されます。ただし、プロジェクト構成の表現が宣言的であればあるほど、アップグレード用の調整が必要なすべての箇所が Upgrade Assistant によって検出される可能性が高くなります。
プロジェクトがこれらの制限に従っていても、Upgrade Assistant がクリーンなアップグレードに失敗することがあります。バグの解決方法と報告方法については、エラーのトラブルシューティングをご覧ください。
プロジェクトをバックアップする
Upgrade Assistant を使用する前に、バージョン管理システムで検出される未登録の変更をプロジェクトに残さないようにすることをおすすめします。バージョン管理を使用していない場合は、その時点で確認済みの最新の良好なバージョンのバックアップを使用してください。
Upgrade Assistant を実行し、プロジェクトが正常にビルドされてテストに合格した後で、プロジェクトの新しいバージョンをバージョン管理システムに登録できます。
Upgrade Assistant を実行する
Upgrade Assistant を実行する手順は次のとおりです。
Upgrade Assistant を起動するには、[Tools] > [AGP Upgrade Assistant] に移動するか、通知プロンプトをクリックします（図 1 を参照）。
ツール ウィンドウが開き、デフォルト アップグレードの詳細が表示されます。これには、プロジェクトの現在の AGP バージョンと、お使いの Android Studio バージョンでサポートされている最新バージョンの情報が含まれます。
図 1. 起動された AGP Upgrade Assistant のツール ウィンドウと通知プロンプト。 必須のステップと推奨されるステップを確認します。
左側のパネルのツリーには、アップグレードの個々のステップがチェックボックス付きで表示され、それぞれがアップグレードの必須のステップか推奨されるステップか、また他のステップの前提条件かが示されます。ツリー内の個々のアイテムを選択すると、メインパネルに各ステップの詳細が表示されます。
アップグレードを実行するには、必須のステップと実行したいステップを選択し、[Run selected steps] をクリックします。
Upgrade Assistant は、プロジェクト ビルドファイルを変更し、新しいプロジェクト ビルドを Android Studio と同期しようと試みます。プラグインとライブラリの新しいバージョンのダウンロードが必要になるため、モジュールが多数ある場合は、この処理に時間がかかることがあります。
アップグレード後のレポートを確認します。このレポートには、完了したステップと、アップグレードが成功したかどうかが記載されています。アップグレード後、プロジェクトのビルドまたはテストに問題がある場合は、Upgrade Assistant によって行われた変更を元に戻すアクションも記載されています。
プロジェクトが Android Studio と正常に同期されたら、プロジェクトをビルドしてテストスイートを実行し、アップグレード オペレーションによって機能に変化が生じていないことを確認します。
プロジェクトが良好な状態にあることを確認したら、バージョン管理システムにプロジェクトの新しいバージョンを登録します。
エラーをトラブルシューティングする
Upgrade Assistant が提案したアップグレードが失敗した場合、通常はビルドファイルに変更を加えたことによる同期の失敗が原因です。エラーの切り分けと修正に役立つ手順は次のとおりです。
まず、同期が失敗する原因となったエラーを検査します。エラーの原因が明確で、プロジェクトのビルドファイル内で特定できる場合もあります。
エラー メッセージが不明確な場合や問題の原因が不明な場合は、プロジェクトを元の状態に戻し、アップグレードを小さいステップに分割します。バージョン管理システムまたはバックアップから元の状態を復元し、プロジェクトが元の状態に戻っていて Android Studio と同期されていることを確認します。
次の 2 種類のアップグレードの細分化を使用して、エラーを調査します。
最新でない AGP バージョンにアップグレードする。失敗したアップグレードが多数のバージョンを含むアップグレードであった場合、問題を切り分ける最良の方法は、バージョンごとの小規模なアップグレードを順次実行して、問題を引き起こす最初のアップグレードを見つけることです。
1 つのアップグレードに含まれる個別のステップを一度に 1 つずつ実行する。問題を引き起こすアップグレードが見つかったら、そのアップグレードに含まれる個別のステップを分離できる場合があります。分離できる場合は、個別のステップを一度に 1 つずつ試して、エラーの原因となっているステップを見つけます。エラーの原因になっているステップが見つからない場合は、お使いになっているその他の Gradle プラグインのリリースノートを参照して、Gradle または AGP の互換性に関する問題を調べます。新しいリリースは非推奨の API または内部 API の使用に対応している場合があります。
バグを報告する。すべての準備ステップと同期が成功したにもかかわらず、最後のアップグレード ステップが失敗することがあります。この場合は、バグを報告してください。自力でエラーの解決に成功した場合でも、バグトラッカーにエラーを報告して、開発チームが問題を解決できるようご協力をお願いします。