了解 Android API 層級
Xamarin.Android 有數個 Android API 層級設定，可決定應用程式與多個 Android 版本的相容性。 本指南說明這些設定的意義、如何設定這些設定，以及在運行時間對您的應用程式產生什麼影響。
快速入門
Xamarin.Android 公開三個 Android API 層級項目設定：
目標 Framework – 指定要在建置應用程式時使用的架構。 Xamarin.Android 會在 編譯 時期使用此 API 層級。
最低 Android 版本 – 指定您想要應用程式支援的最舊 Android 版本。 Android 會在 運行 時間使用此 API 層級。
目標 Android 版本 – 指定應用程式要執行的 Android 版本。 Android 會在 運行 時間使用此 API 層級。
您必須先安裝該 API 層級的 SDK 平台元件，才能為您的項目設定 API 層級。 如需下載和安裝 Android SDK 元件的詳細資訊，請參閱 Android SDK 安裝程式。
注意
從 2021 年 8 月開始，Google Play 控制台會要求新的應用程式以 API 層級 30 （Android 11.0） 或更高版本為目標。 從 2021 年 11 月開始，需要現有的應用程式以 API 層級 30 或更新版本為目標。 如需詳細資訊，請參閱 Play Console 檔中的中的 Play Console 目標 API 層級需求。
一般而言，這三個 Xamarin.Android API 層級都會設定為相同的值。 在 [應用程式] 頁面上，將 [使用 Android 版本編譯] （Target Framework） 設定為最新的穩定 API 版本（或至少，設定為具有您需要之所有功能的 Android 版本）。 在下列螢幕快照中，目標 Framework 會設定為 Android 7.1 （API 層級 25 - Nougat）：
在 [ Android 指令清單 ] 頁面上，將 [最低 Android 版本] 設定為 [使用 SDK 編譯] 版本 ，並將 [目標 Android 版本] 設定為與目標 Framework 版本相同的值（在下列螢幕快照中，目標 Android Framework 設定為 Android 7.1 （Nougat））：
如果您想要維持與舊版 Android 的回溯相容性，請將 [最低 Android 版本] 設定 為 您想要應用程式支援的舊版 Android。 （請注意，API 層級 14 是所需的 最低 API 層級Google Play 服務和 Firebase 支援。下列範例組態支援從 API 層級 14 到 API 層級 25 的 Android 版本：
如果您的應用程式支援多個 Android 版本，您的程式代碼必須包含運行時間檢查，以確保您的應用程式使用最低 Android 版本設定（如需詳細資訊，請參閱 下方 Android 版本的 運行時間檢查）。 如果您要取用或建立連結庫，請參閱 下面的 API 層級和連結庫 ，以取得設定連結庫 API 層級設定的最佳做法。
Android 版本和 API 層級
隨著Android平臺的發展和新的Android版本發行，每個Android版本都會獲指派一個稱為 API層級的唯一整數標識碼。 因此，每個 Android 版本都會對應至單一 Android API 層級。 由於使用者在舊版和最新版本的 Android 上安裝應用程式，因此實際 Android 應用程式必須設計為使用多個 Android API 層級。
Android 版本
Android 的每個版本都會以多個名稱執行：
- Android 版本，例如 Android 9.0
- 程序代碼 （或甜點） 名稱，例如 Pie
- 對應的 API 層級，例如 API 層級 28
Android 程式代碼名稱可能對應至多個版本和 API 層級（如下表所示），但每個 Android 版本都對應至一個 API 層級。
此外，Xamarin.Android 會 定義對應至目前已知 Android API 層級的組建版本代碼 。 下表可協助您在 API 層級、Android 版本、程式代碼名稱和 Xamarin.Android 組建版本代碼之間翻譯（組建版本代碼是在 命名空間中 Android.OS 定義）：
| 名稱 | 版本 | API 層級 | 已發行 | 組建版本代碼 |
|---|---|---|---|---|
| Q | 10.0 | 29 | 2020 年 8 月 | BuildVersionCodes.Q |
| 圓形圖 | 9.0 | 28 | 2018 年 8 月 | BuildVersionCodes.P |
| Oreo | 8.1 | 27 | 2017 年 12 | BuildVersionCodes.OMr1 |
| Oreo | 8.0 | 26 | 2017 年 8 月 | BuildVersionCodes.O |
| Nougat | 7.1 | 25 | 2016年12月 | BuildVersionCodes.NMr1 |
| Nougat | 7.0 | 24 | 2016 年 8 月 | BuildVersionCodes.N |
| Marshmallow | 6.0 | 23 | 2015年8月 | BuildVersionCodes.M |
| Lollipop | 5.1 | 22 | 2015年3月 | BuildVersionCodes.LollipopMr1 |
| Lollipop | 5.0 | 21 | 2014 年 11 月 | BuildVersionCodes.Lollipop |
| Kitkat Watch | 4.4W | 20 | 2014年6月 | BuildVersionCodes.KitKatWatch |
| Kitkat | 4.4 | 19 | 2013年10月 | BuildVersionCodes.KitKat |
| 果凍豆 | 4.3 | 18 | 2013年7月 | BuildVersionCodes.JellyBeanMr2 |
| 果凍豆 | 4.2-4.2.2 | 17 | 2012年11月 | BuildVersionCodes.JellyBeanMr1 |
| 果凍豆 | 4.1-4.1.1 | 16 | 2012年6月 | BuildVersionCodes.JellyBean |
| 霜淇淋三明治 | 4.0.3-4.0.4 | 15 | 2011年12月 | BuildVersionCodes.IceCreamSandwichMr1 |
| 霜淇淋三明治 | 4.0-4.0.2 | 14 | 2011 年 10 月 | BuildVersionCodes.IceCreamSandwich |
| 蜂窩 | 3.2 | 13 | 2011年6月 | BuildVersionCodes.HoneyCombMr2 |
| 蜂窩 | 3.1.x | 12 | 2011 年 5 月 | BuildVersionCodes.HoneyCombMr1 |
| 蜂窩 | 3.0.x | 11 | 2011年2月 | BuildVersionCodes.HoneyComb |
| 姜 餅 | 2.3.3-2.3.4 | 10 | 2011年2月 | BuildVersionCodes.GingerBreadMr1 |
| 姜 餅 | 2.3-2.3.2 | 9 | 2010 年 11 月 | BuildVersionCodes.GingerBread |
| Froyo | 2.2.x | 8 | 2010 年 6 月 | BuildVersionCodes.Froyo |
| Eclair | 2.1.x | 7 | 2010 年 1 月 | BuildVersionCodes.EclairMr1 |
| Eclair | 2.0.1 | 6 | 2009年12月 | BuildVersionCodes.Eclair01 |
| Eclair | 2.0 | 5 | 2009年11月 | BuildVersionCodes.Eclair |
| 環圈圖 | 1.6 | 4 | 2009年9月 | BuildVersionCodes.Donut |
| 蛋糕 | 1.5 | 3 | 2009年5月 | BuildVersionCodes.Cupcake |
| 基本 | 1.1 | 2 | 2009年2月 | BuildVersionCodes.Base11 |
| 基本 | 1.0 | 1 | 2008 年 10 月 | BuildVersionCodes.Base |
如下表所示，新的 Android 版本會經常發行，有時每年發行一個以上的版本。 因此，執行您 app 的 Android 裝置宇宙包含各種較舊和較新的 Android 版本。 如何保證您的應用程式會在這麼多不同版本的 Android 上一致且可靠地執行？ Android 的 API 層級可協助您管理此問題。
Android API 層級
每個 Android 裝置只會 在 API 層級執行 ， 此 API 層級保證為每個 Android 平臺版本是唯一 的。 API 層級可精確識別應用程式可以呼叫的 API 集合版本;它會識別您以開發人員身分撰寫程式代碼的指令清單專案、許可權等組合。 Android 的 API 層級系統可協助 Android 判斷在裝置上安裝應用程式之前，應用程式是否與 Android 系統映像相容。
建置應用程式時，它包含下列 API 層級資訊：
應用程式要執行的目標Android API層級。
Android 裝置必須執行應用程式的最低 Android API 層級。
這些設定是用來確保安裝時可在 Android 裝置上正確執行應用程式所需的功能。 如果沒有，應用程式會遭到封鎖，無法在該裝置上執行。 例如，如果Android裝置的API層級低於您為應用程式指定的最低API層級，則Android裝置會防止使用者安裝您的應用程式。
專案 API 層級設定
下列各節說明如何使用 SDK 管理員來為您想要設定目標的 API 層級準備開發環境，然後詳細說明如何在 Xamarin.Android 中設定 目標 Framework、 最低 Android 版本和 目標 Android 版本 設定。
Android SDK 平臺
您必須先安裝對應至該 API 層級的 Android SDK 平臺版本，才能在 Xamarin.Android 中選取目標或最低 API 層級。 目標 Framework、最低 Android 版本和目標 Android 版本的可用選項範圍僅限於您已安裝的 Android SDK 版本範圍。 您可以使用 SDK 管理員來確認已安裝必要的 Android SDK 版本，而且您可以使用它來新增應用程式所需的任何新的 API 層級。 如果您不熟悉如何安裝 API 層級，請參閱 Android SDK 安裝程式。
目標 Framework
目標 Framework （也稱為 compileSdkVersion） 是您的應用程式在建置時間編譯的特定 Android 架構版本（API 層級）。 此設定會指定應用程式 在執行時預期 使用哪些 API，但在安裝應用程式時，它不會影響哪些 API 實際可供您的應用程式使用。 因此，變更 Target Framework 設定並不會變更運行時間行為。
Target Framework 會識別應用程式所連結的連結庫版本– 此設定會決定您可以在應用程式中使用的 API。 例如，如果您想要使用 Android 5.0 Lollipop 中引進的 NotificationBuilder.SetCategory 方法，則必須將目標 Framework 設定為 API 層級 21 （Lollipop） 或更新版本。 如果您將項目的目標 Framework 設定為 API 層級 19 （KitKat） 等 API 層級，並嘗試在程式碼中呼叫 SetCategory 方法，您將會收到編譯錯誤。
建議您一律使用 最新的 可用 Target Framework 版本進行編譯。 這麼做可讓您針對程式代碼可能呼叫的任何已淘汰 API 提供實用的警告訊息。 當您使用最新的支持連結庫版本時，使用最新的目標 Framework 版本特別重要 – 每個連結庫都預期您的應用程式會在該支持連結庫的最低 API 層級或更高層級進行編譯。
若要存取 Visual Studio 中的 [目標 Framework] 設定，請在 方案總管 中開啟專案屬性，然後選取 [應用程式] 頁面：
在 [使用 Android 編譯版本編譯] 底下的下拉功能表中選取 API 層級，以設定目標 Framework，如上所示。
最低 Android 版本
最低 Android 版本 （也稱為 minSdkVersion） 是最舊版本的 Android OS（也就是最低 API 層級），可以安裝並執行您的應用程式。 根據預設，應用程式只能安裝在符合目標 Framework 設定或更新版本的裝置上;如果 [最低 Android 版本] 設定低於 [目標 Framework] 設定，則您的應用程式也可以在舊版 Android 上執行。 例如，如果您將目標 Framework 設定為 Android 7.1 （Nougat），並將 [最低 Android 版本] 設定為 Android 4.0.3 （Ice Cream Sandwich），則您的應用程式可以安裝在 API 層級 15 到 API 層級 25 的任何平臺上。包括。
雖然您的應用程式可能會成功建置並安裝在這一系列平臺上，但這並不保證它會在所有這些平臺上成功 執行 。 例如，如果您的應用程式安裝在 Android 5.0 （Lollipop）上，而且您的程式代碼會呼叫只能在 Android 7.1 （Nougat） 和更新版本中提供的 API，您的應用程式將會收到運行時錯誤，而且可能會當機。 因此，您的程式代碼必須確保 – 在運行時間 – 它只會呼叫其執行中 Android 裝置所支援的 API。 換句話說，您的程式代碼必須包含明確的運行時間檢查，以確保您的應用程式只在最近足以支持這些 API 的裝置上使用較新的 API。 本指南稍後的 Android 版本運行時間檢查說明如何將這些運行時間檢查新增至您的程式代碼。
若要存取 Visual Studio 中的 [最低 Android 版本] 設定，請在 方案總管 中開啟專案屬性，然後選取 [Android 指令清單] 頁面。 在 [最低 Android 版本] 下的下拉功能表中，您可以選取應用程式的 [最低 Android 版本]：
如果您選取 [ 使用 SDK 進行編譯] 版本，則 [最低 Android 版本] 會與 [目標 Framework] 設定相同。
目標 Android 版本
目標 Android 版本 （也稱為 targetSdkVersion） 是應用程式預期執行之 Android 裝置的 API 層級。 Android 會使用此設定來判斷是否要啟用任何相容性行為 – 這可確保您的應用程式會繼續以預期的方式運作。 Android 使用應用程式的目標 Android 版本設定來找出哪些行為變更可以套用至您的應用程式，而不會中斷它（這是 Android 提供向前相容性的方式）。
Target Framework 和 Target Android 版本雖然名稱非常類似，但並不相同。 [目標架構] 設定會將目標 API 層級資訊傳達給 Xamarin.Android，以供編譯時間使用，而目標 Android 版本則會將目標 API 層級資訊傳達給 Android，以在運行時間使用（在裝置上安裝並執行應用程式時）。
若要在 Visual Studio 中存取此設定，請在 方案總管 中開啟專案屬性，然後選取 [Android 指令清單] 頁面。 在 [目標 Android 版本] 下的下拉功能表中，您可以選取應用程式的 [目標 Android 版本]：
我們建議您明確地將目標 Android 版本設定為您用來測試應用程式的最新版本 Android。 在理想情況下，它應該設定為最新的 Android SDK 版本 – 這可讓您在處理行為變更之前使用新的 API。 對於大多數開發人員，不建議將 [目標 Android 版本] 設定為 [使用 SDK 編譯] 版本。
一般而言，目標 Android 版本應該受到最低 Android 版本和目標 Framework 的限制。 也就是說：
最低 Android 版本 <= 目標 Android 版本 <= 目標 Framework
如需 SDK 層級的詳細資訊，請參閱 Android 開發人員 uses-sdk 檔。
Android 版本的運行時間檢查
隨著每個新版本的 Android 發行，架構 API 會更新以提供新的或取代功能。 除了少數例外狀況，舊版的 API 功能會轉送至較新的 Android 版本，而不需要修改。 因此，如果您的應用程式在特定 Android API 層級上執行，通常能夠在較新的 Android API 層級上執行，而不需要修改。 但是，如果您想要在舊版 Android 上執行應用程式，該怎麼辦？
如果您選取低於目標 Framework 設定的最低 Android 版本，某些 API 可能無法在運行時間提供給您的應用程式。 不過，您的應用程式仍然可以在舊版裝置上執行，但功能降低。 針對對應至最低 Android 版本設定的 Android 平台上無法使用的每個 API，您的程式代碼必須明確檢查 屬性的值 Android.OS.Build.VERSION.SdkInt ，以判斷應用程式執行平臺的 API 層級。 如果 API 層級低於支援您想要呼叫之 API 的最低 Android 版本，則您的程式代碼必須找到一種方法來正常運作，而不需進行此 API 呼叫。
例如，假設我們想要使用 NotificationBuilder.SetCategory 方法，在 Android 5.0 Lollipop 上執行時分類通知，但我們仍然希望我們的應用程式在舊版 Android 上執行，例如 Android 4.1 Jelly Bean （其中SetCategory無法使用）。 在本指南開頭參考 Android 版本數據表時，我們看到 Android 5.0 Lollipop 的組建版本代碼是 Android.OS.BuildVersionCodes.Lollipop。 為了支持無法使用的舊版 Android SetCategory ，我們的程式代碼可以在運行時間偵測 API 層級，並且只有在 API 層級大於或等於 Lollipop 組建版本代碼時，才有條件地呼叫 SetCategory ：
if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
builder.SetCategory(Notification.CategoryEmail);
}
在此範例中，應用程式的目標 Framework 會設定為 Android 5.0（API 層級 21），而其最低 Android 版本設定為 Android 4.1（API 層級 16）。 因為 SetCategory API 層級和更新版本中提供，所以此範例程式代碼只會在實際可用時呼叫 SetCategory ，而不會嘗試在 API 層級Android.OS.BuildVersionCodes.Lollipop為 16、17、18、19 或 20 時呼叫SetCategory。 這些舊版 Android 上的功能只會降低到通知未正確排序的程度（因為它們未依類型分類），但通知仍會發佈給警示使用者。 我們的應用程式仍可運作，但其功能會稍微降低。
一般而言，組建版本檢查可協助您的程式代碼在運行時間決定以新方式與舊方式執行動作。 例如：
if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
// Do things the Lollipop way
}
else
{
// Do things the pre-Lollipop way
}
沒有快速且簡單的規則，說明如何在缺少一或多個 API 的舊版 Android 版本上執行時，減少或修改應用程式的功能。 在某些情況下（例如在 SetCategory 上述範例中），在無法使用 API 呼叫時就已足夠省略。 不過，在其他情況下，您可能需要針對偵測到小於應用程式呈現最佳體驗的 API 層級，實作替代功能 Android.OS.Build.VERSION.SdkInt 。
API 層級和連結庫
當您建立 Xamarin.Android 連結庫專案（例如類別庫或系結連結庫），您只能設定 Target Framework 設定 – [最低 Android 版本] 和 [目標 Android 版本] 設定無法使用。 這是因為沒有 Android 指令清單 頁面：
「最低 Android 版本」和「目標 Android 版本」設定無法使用，因為產生的連結庫不是獨立應用程式， 連結庫可以在任何 Android 版本上執行，視它封裝的應用程式而定。 您可以指定連結庫的 編譯方式，但無法預測連結庫將在哪個平臺 API 層級上執行。 考慮到這一點，在取用或建立連結庫時，應該觀察下列最佳做法：
取用 Android 連結庫時 – 如果您要在應用程式中取用 Android 連結庫，請務必將應用程式的目標 Framework 設定設為至少與連結庫的目標 Framework 設定一樣高的 API 層級。
建立 Android 連結庫時 – 如果您要建立 Android 連結庫 以供其他應用程式使用，請務必將其目標 Framework 設定設定為編譯所需的最低 API 層級。
建議使用這些最佳做法來協助防止連結庫嘗試呼叫在運行時間無法使用的 API 的情況（這可能會導致應用程式當機）。 如果您是連結庫開發人員，您應該努力將 API 呼叫的使用限制為 API 介面區總計小且已建立的子集。 這樣做有助於確保您的連結庫可在更廣泛的 Android 版本之間安全地使用。
摘要
本指南說明如何使用Android API層級來管理不同Android版本的應用程式相容性。 它提供設定 Xamarin.Android 目標 Framework、 最低 Android 版本和 目標 Android 版本 專案設定的詳細步驟。 它提供使用 Android SDK 管理員來安裝 SDK 套件的指示，包括如何在運行時間撰寫程式代碼來處理不同 API 層級的範例，並說明如何在建立或取用 Android 連結庫時管理 API 層級。 它也提供了一個完整的清單，將 API 層級與 Android 版本號碼（例如 Android 4.4）、Android 版本名稱（例如 Kitkat）和 Xamarin.Android 組建版本代碼產生關聯。