Android API-EbenenUnderstanding Android API levels

Xamarin. Android verfügt über mehrere Einstellungen der Android-API-Ebene, mit denen die Kompatibilität Ihrer APP mit mehreren Versionen von Android bestimmt wird. In diesem Handbuch wird erläutert, was diese Einstellungen bedeuten, wie Sie konfiguriert werden und welche Auswirkungen Sie zur Laufzeit auf Ihre APP haben.Xamarin.Android has several Android API level settings that determine your app's compatibility with multiple versions of Android. This guide explains what these settings mean, how to configure them, and what effect they have on your app at run time.

SchnellstartQuick start

Xamarin. Android stellt drei Projekteinstellungen auf Android-API-Ebene bereit:Xamarin.Android exposes three Android API level project settings:

  • Ziel Framework – Gibt an, welches Framework beim Entwickeln der Anwendung verwendet werden soll.Target Framework – Specifies which framework to use in building your application. Diese API-Ebene wird zur Kompilier Zeit von xamarin. Android verwendet.This API level is used at compile time by Xamarin.Android.

  • Android-Mindestversion – Gibt die älteste Android-Version an, die von ihrer App unterstützt werden soll.Minimum Android Version – Specifies the oldest Android version that you want your app to support. Diese API-Ebene wird zur Laufzeit von Android verwendet.This API level is used at run time by Android.

  • Android-Ziel Version – Gibt die Android-Version an, auf der Ihre APP ausgeführt werden soll.Target Android Version – Specifies the version of Android that your app is intended to run on. Diese API-Ebene wird zur Laufzeit von Android verwendet.This API level is used at run time by Android.

Bevor Sie eine API-Ebene für Ihr Projekt konfigurieren können, müssen Sie die SDK-Platt Form Komponenten für diese API-Ebene installieren.Before you can configure an API level for your project, you must install the SDK platform components for that API level. Weitere Informationen zum herunterladen und Installieren von Android SDK-Komponenten finden Sie unter Android SDK Setup.For more information about downloading and installing Android SDK components, see Android SDK Setup.

Hinweis

Ab August 2018 erfordert die Google Play Konsole, dass neue apps auf API Level 26 (Android 8,0) oder höher ausgerichtet sind.Beginning in August 2018, the Google Play Console will require that new apps target API level 26 (Android 8.0) or higher. Vorhandene apps müssen ab dem 2018 auf API-Ebene 26 oder höher ausgerichtet sein.Existing apps will be required to target API level 26 or higher beginning in November 2018. Weitere Informationen finden Sie unter verbessern der App-Sicherheit und-Leistung auf Google Play für Jahre.For more information, see Improving app security and performance on Google Play for years to come.

Normalerweise werden alle drei xamarin. Android-API-Ebenen auf denselben Wert festgelegt.Normally, all three Xamarin.Android API levels are set to the same value. Legen Sie auf der Seite Anwendung Kompilierung mit Android-Version (Ziel Framework) auf die neueste stabile API-Version (oder zumindest auf die Android-Version mit allen benötigten Features) fest.On the Application page, set Compile using Android version (Target Framework) to the latest stable API version (or, at a minimum, to the Android version that has all of the features you need). Im folgenden Screenshot ist das Ziel Framework auf Android 7,1 (API-Ebene 25-Nougat) festgelegt:In the following screenshot, the Target Framework is set to Android 7.1 (API Level 25 - Nougat):

Standard-Framework-Version für die Kompilierung mit der Android-VersionTarget Framework version defaults to Compile using Android version

Legen Sie auf der Seite Android-Manifest die Android-Mindestversion für die Verwendung von Kompilieren mit der SDK-Version fest, und legen Sie die Android-Zielversion auf denselben Wert fest wie die Zielframeworkversion (im folgenden Screenshot ist das Android-Ziel Framework auf festgelegt. Android 7,1 (Nougat) ):On the Android Manifest page, set the Minimum Android version to Use Compile using SDK version and set the Target Android version to the same value as the Target Framework version (in the following screenshot, the Target Android Framework is set to Android 7.1 (Nougat)):

Mindestens für die Ziel Framework-Version festgelegte Android-Ziel VersionenMinimum and Target Android versions set to Target Framework version

Wenn Sie die Abwärtskompatibilität mit einer früheren Version von Android gewährleisten möchten, legen Sie die Android-Mindestversion auf die älteste Version von Android fest, die von ihrer App unterstützt werden soll.If you want to maintain backward compatibility with an earlier version of Android, set Minimum Android version to target to the oldest version of Android that you want your app to support. (Beachten Sie, dass API-Ebene 14 die minimale API-Ebene ist, die für Google Play Dienste und Firebase-Unterstützungerforderlich ist. Die folgende Beispielkonfiguration unterstützt Android-Versionen von API-Ebene 14 bis API-Ebene 25:(Note that API Level 14 is the minimum API level required for Google Play services and Firebase support.) The following example configuration supports Android versions from API Level 14 through API level 25:

Kompilieren mit API-Ebene 25 Nougat, Android-Mindestversion ist auf API-Ebene 14 festgelegtCompile using API level 25 Nougat, Minimum Android version set to API level 14

Wenn Ihre APP mehrere Android-Versionen unterstützt, muss Ihr Code Laufzeitüberprüfungen enthalten, um sicherzustellen, dass Ihre APP mit der Android-Mindestversion funktioniert (Weitere Informationen finden Sie weiter unten unter Lauf Zeit Prüfungen für Android-Versionen ).If your app supports multiple Android versions, your code must include runtime checks to ensure that your app works with the Minimum Android version setting (see Runtime Checks for Android Versions below for details). Wenn Sie eine Bibliothek nutzen oder erstellen, finden Sie unter API-Ebenen und-Bibliotheken unten bewährte Methoden für die Konfiguration von API-Ebenen-Einstellungen für Bibliotheken.If you are consuming or creating a library, see API Levels and Libraries below for best practices in configuring API level settings for libraries.

Android-Versionen und API-EbenenAndroid versions and API levels

Wenn die Android-Plattform weiterentwickelt wird und neue Android-Versionen veröffentlicht werden, wird jeder Android-Version ein eindeutiger ganzzahliger Bezeichner ( API-Ebene) zugewiesen.As the Android platform evolves and new Android versions are released, each Android version is assigned a unique integer identifier, called the API Level. Daher entspricht jede Android-Version einer einzelnen Android-API-Ebene.Therefore, each Android version corresponds to a single Android API Level. Da Benutzer apps sowohl auf älteren als auch in den neuesten Versionen von Android installieren, müssen reale Android-Apps für die Verwendung mit mehreren Android-API-Ebenen entworfen werden.Because users install apps on older as well as the most recent versions of Android, real-world Android apps must be designed to work with multiple Android API levels.

Android-VersionenAndroid versions

Jede Version von Android wird durch mehrere Namen geleitet:Each release of Android goes by multiple names:

  • Die Android-Version, z. b. Android 9,0The Android version, such as Android 9.0
  • Ein Code (oder ein Nachtisch), z . b. KreisA code (or dessert) name, such as Pie
  • Eine entsprechende API-Ebene, z. b. API-Ebene 28A corresponding API level, such as API level 28

Ein Android-Codename kann mehreren Versionen und API-Ebenen entsprechen (wie in der folgenden Tabelle gezeigt), jede Android-Version entspricht jedoch genau einer API-Ebene.An Android code name may correspond to multiple versions and API levels (as seen in the table below), but each Android version corresponds to exactly one API level.

Außerdem definiert xamarin. Android buildversionscodes, die den derzeit bekannten Android-API-Ebenen entsprechen.In addition, Xamarin.Android defines build version codes that map to the currently known Android API levels. In der folgenden Tabelle finden Sie Unterstützung bei der Übersetzung zwischen API-, Android-Version, Codename und xamarin. Android-buildversionscode (buildversionscodes sind im Android.OS -Namespace definiert):The following table can help you translate between API level, Android version, code name, and Xamarin.Android build version code (build version codes are defined in the Android.OS namespace):

NameName VersionVersion API-EbeneAPI Level FreigegebenReleased Build-Versions CodeBuild Version Code
KreisPie 9.09.0 2828 2018Aug 2018 BuildVersionCodes.P
OreoOreo 8.18.1 2727 Dezember 2017Dec 2017 BuildVersionCodes.OMr1
OreoOreo 8.08.0 2626 2017Aug 2017 BuildVersionCodes.O
NougatNougat 7.17.1 2525 Dezember 2016Dec 2016 BuildVersionCodes.NMr1
NougatNougat 7.07.0 2424 2016Aug 2016 BuildVersionCodes.N
MarshmallowMarshmallow 6.06.0 2323 2015Aug 2015 BuildVersionCodes.M
LollipopLollipop 5.15.1 2222 2015Mar 2015 BuildVersionCodes.LollipopMr1
LollipopLollipop 5.05.0 2121 2014. NovemberNov 2014 BuildVersionCodes.Lollipop
Kitkat-ÜberwachungKitkat Watch 4.4 W4.4W 2020 Jun 2014Jun 2014 BuildVersionCodes.KitKatWatch
KitkatKitkat 4,44.4 1919 2013. OktOct 2013 BuildVersionCodes.KitKat
Gelee BeanJelly Bean 4.34.3 1818 Jul 2013Jul 2013 BuildVersionCodes.JellyBeanMr2
Gelee BeanJelly Bean 4.2-4.2.24.2-4.2.2 1717 2012. NovemberNov 2012 BuildVersionCodes.JellyBeanMr1
Gelee BeanJelly Bean 4.1-4.1.14.1-4.1.1 1616 Jun 2012Jun 2012 BuildVersionCodes.JellyBean
Ice Cream SandwichIce Cream Sandwich 4.0.3-4.0.44.0.3-4.0.4 1515 Dezember 2011Dec 2011 BuildVersionCodes.IceCreamSandwichMr1
Ice Cream SandwichIce Cream Sandwich 4.0-4.0.24.0-4.0.2 1414 2011. OktOct 2011 BuildVersionCodes.IceCreamSandwich
HoneycombHoneycomb 3.23.2 1313 Jun 2011Jun 2011 BuildVersionCodes.HoneyCombMr2
HoneycombHoneycomb 3.1. x3.1.x 1212 Mai 2011May 2011 BuildVersionCodes.HoneyCombMr1
HoneycombHoneycomb 3.0. x3.0.x 1111 2011Feb 2011 BuildVersionCodes.HoneyComb
TeeGingerbread 2.3.3-2.3.42.3.3-2.3.4 1010 2011Feb 2011 BuildVersionCodes.GingerBreadMr1
TeeGingerbread 2.3-2.3.22.3-2.3.2 99 2010. NovemberNov 2010 BuildVersionCodes.GingerBread
FroyoFroyo 2.2. x2.2.x 88 Jun 2010Jun 2010 BuildVersionCodes.Froyo
EclairEclair 2.1. x2.1.x 77 Jan. 2010Jan 2010 BuildVersionCodes.EclairMr1
EclairEclair 2.0.12.0.1 66 Dezember 2009Dec 2009 BuildVersionCodes.Eclair01
EclairEclair 2.02.0 55 2009. NovemberNov 2009 BuildVersionCodes.Eclair
RingDonut 1.61.6 44 Sep 2009Sep 2009 BuildVersionCodes.Donut
CupcakeCupcake 1.51.5 33 Mai 2009May 2009 BuildVersionCodes.Cupcake
BaseBase 1.11.1 22 2009Feb 2009 BuildVersionCodes.Base11
BaseBase 1.01.0 11 2008. OktOct 2008 BuildVersionCodes.Base

Wie diese Tabelle zeigt, werden neue Android-Versionen häufig – häufig mehr als eine Version pro Jahr veröffentlicht.As this table indicates, new Android versions are released frequently – sometimes more than one release per year. Folglich umfasst das Universum von Android-Geräten, die Ihre APP möglicherweise ausführen, eine Vielzahl von älteren und neueren Android-Versionen.As a result, the universe of Android devices that might run your app includes of a wide variety of older and newer Android versions. Wie können Sie sicherstellen, dass Ihre APP in so vielen verschiedenen Versionen von Android konsistent und zuverlässig ausgeführt wird?How can you guarantee that your app will run consistently and reliably on so many different versions of Android? Die API-Ebenen von Android können Sie bei der Verwaltung dieses Problems unterstützen.Android's API levels can help you manage this problem.

Android-API-EbenenAndroid API levels

Jedes Android-Gerät wird auf genau einer API – -Ebene ausgeführt. diese API-Ebene ist für jede Version der Android-Plattform garantiert eindeutig.Each Android device runs at exactly one API level – this API level is guaranteed to be unique per Android platform version. Die API-Ebene identifiziert exakt die Version des API-Satzes, in der Ihre APP aufgerufen werden kann. Es identifiziert die Kombination von manifeselementen, Berechtigungen usw., die Sie als Entwickler codieren.The API level precisely identifies the version of the API set that your app can call into; it identifies the combination of manifest elements, permissions, etc. that you code against as a developer. Das Android-System mit API-Ebenen unterstützt Android bei der Ermittlung, ob eine Anwendung mit einem Android-System Abbild kompatibel ist, bevor die Anwendung auf einem Gerät installiert wird.Android's system of API levels helps Android determine whether an application is compatible with an Android system image prior to installing the application on a device.

Wenn eine Anwendung erstellt wird, enthält Sie die folgenden API-Ebeneninformationen:When an application is built, it contains the following API level information:

  • Die Ziel -API-Ebene von Android, auf der die app ausgeführt werden soll.The target API level of Android that the app is built to run on.

  • Die minimale Android-API-Ebene, die ein Android-Gerät zum Ausführen der APP benötigt.The minimum Android API level that an Android device must have to run your app.

Diese Einstellungen werden verwendet, um sicherzustellen, dass die erforderliche Funktionalität zum ordnungsgemäßen Ausführen der APP auf dem Android-Gerät zur Installationszeit verfügbar ist.These settings are used to ensure that the functionality needed to run the app correctly is available on the Android device at installation time. Andernfalls wird die Ausführung der APP auf diesem Gerät blockiert.If not, the app is blocked from running on that device. Wenn die API-Ebene eines Android-Geräts beispielsweise niedriger ist als die API-Ebene, die Sie für Ihre APP angeben, hindert das Android-Gerät den Benutzer daran, Ihre APP zu installieren.For example, if the API level of an Android device is lower than the minimum API level that you specify for your app, the Android device will prevent the user from installing your app.

Einstellungen der Projekt-API-EbeneProject API level settings

In den folgenden Abschnitten wird erläutert, wie Sie den SDK-Manager verwenden, um Ihre Entwicklungsumgebung für die API-Ebenen vorzubereiten, auf die Sie abzielen möchten, gefolgt von detaillierten Erläuterungen zum Konfigurieren des Ziel Frameworks, der Android-Mindestversionund Ziel Einstellungen für Android-Version in xamarin. Android.The following sections explain how to use the SDK Manager to prepare your development environment for the API levels you want to target, followed by detailed explanations of how to configure Target Framework, Minimum Android version, and Target Android version settings in Xamarin.Android.

Android SDK PlattformenAndroid SDK platforms

Bevor Sie ein Ziel oder eine minimale API-Ebene in xamarin. Android auswählen können, müssen Sie die Android SDK Platt Form Version installieren, die dieser API-Ebene entspricht.Before you can select a Target or Minimum API level in Xamarin.Android, you must install the Android SDK platform version that corresponds to that API level. Der Bereich der verfügbaren Optionen für das Ziel Framework, die Android-Mindestversion und die Android-Zielversion sind auf den Bereich von Android SDK Versionen beschränkt, die Sie installiert haben.The range of available choices for Target Framework, Minimum Android version, and Target Android version is limited to the range of Android SDK versions that you have installed. Sie können den SDK-Manager verwenden, um zu überprüfen, ob die erforderlichen Android SDK Versionen installiert sind, und Sie können Sie verwenden, um alle neuen API-Ebenen hinzuzufügen, die Sie für Ihre APP benötigen.You can use the SDK Manager to verify that the required Android SDK versions are installed, and you can use it to add any new API levels that you need for your app. Wenn Sie mit der Installation von API-Ebenen nicht vertraut sind, finden Sie weitere Informationen unter Android SDK Setup.If you are not familiar with how to install API levels, see Android SDK Setup.

ZielframeworkTarget Framework

Das Ziel Framework (auch als compileSdkVersionbezeichnet) ist die spezifische Android Framework-Version (API-Ebene), für die Ihre APP zur Buildzeit kompiliert wird.The Target Framework (also known as compileSdkVersion) is the specific Android framework version (API level) that your app is compiled for at build time. Mit dieser Einstellung wird festgelegt, welche APIs von Ihrer APP bei der Ausführung erwartet werden, aber Sie hat keine Auswirkung darauf, welche APIs bei der Installation Ihrer APP tatsächlich zur Verfügung stehen.This setting specifies what APIs your app expects to use when it runs, but it has no effect on which APIs are actually available to your app when it is installed. Folglich ändert sich das Laufzeitverhalten nicht durch Ändern der Ziel Framework-Einstellung.As a result, changing the Target Framework setting does not change runtime behavior.

Das Ziel Framework identifiziert, welche Bibliotheksversionen Ihre Anwendung mit – dieser Einstellung verknüpft ist, bestimmt die APIs, die Sie in Ihrer APP verwenden können.The Target Framework identifies which library versions your application is linked against – this setting determines which APIs you can use in your app. Wenn Sie z. b. die in Android 5,0 Lollipop eingeführte notificationbuilder. setcategory -Methode verwenden möchten, müssen Sie das Ziel Framework auf API- Ebene 21 (Lollipop) oder höher festlegen.For example, if you want to use the NotificationBuilder.SetCategory method that was introduced in Android 5.0 Lollipop, you must set the Target Framework to API Level 21 (Lollipop) or later. Wenn Sie das Ziel Framework des Projekts auf eine API-Ebene wie API-Ebene 19 (KitKat) festlegen und versuchen, die SetCategory -Methode im Code aufzurufen, erhalten Sie einen Kompilierungsfehler.If you set your project's Target Framework to an API level such as API Level 19 (KitKat) and try to call the SetCategory method in your code, you will get a compile error.

Es wird empfohlen, immer mit der neuesten verfügbaren Zielframeworkversion zu kompilieren.We recommend that you always compile with the latest available Target Framework version. Auf diese Weise erhalten Sie hilfreiche Warnmeldungen für alle veralteten APIs, die möglicherweise von Ihrem Code aufgerufen werden.Doing so provides you with helpful warning messages for any deprecated APIs that might be called by your code. Die Verwendung der neuesten Version des Ziel-Frameworks ist besonders wichtig, wenn Sie die – neueste Version der Unterstützungs Bibliothek verwenden. jede Bibliothek erwartet, dass Ihre APP auf der mindestens vorhandenen API-Ebene der unterstützten Bibliothek kompiliert wird.Using the latest Target Framework version is especially important when you use the latest support library releases – each library expects your app to be compiled at that support library's minimum API level or greater.

Wenn Sie in Visual Studio auf die Einstellung für das Ziel Framework zugreifen möchten, öffnen Sie die Projekteigenschaften in Projektmappen-Explorer und wählen Sie die Anwendungs Seite aus:To access the Target Framework setting in Visual Studio, open the project properties in Solution Explorer and select the Application page:

Anwendungsseite der ProjekteigenschaftenApplication page of project Properties

Legen Sie das Ziel Framework fest, indem Sie eine API-Ebene im Dropdown Menü unter mit Android-Version kompilieren auswählen, wie oben gezeigt.Set the Target Framework by selecting an API level in the drop-down menu under Compile using Android version as shown above.

Android-MindestversionMinimum Android Version

Die Android-Mindestversion (auch bekannt minSdkVersionals) ist die älteste Version des Android-Betriebssystems (d. h. die niedrigste API-Ebene), mit der Ihre Anwendung installiert und ausgeführt werden kann.The Minimum Android version (also known as minSdkVersion) is the oldest version of the Android OS (i.e., the lowest API level) that can install and run your application. Standardmäßig kann eine app nur auf Geräten installiert werden, die mit der Ziel Framework-Einstellung oder höher übereinstimmen. Wenn die Android-Mindestversion niedriger ist als die Einstellung für das Ziel Framework, kann Ihre APP auch unter früheren Versionen von Android ausgeführt werden.By default, an app can only be installed on devices matching the Target Framework setting or higher; if the Minimum Android version setting is lower than the Target Framework setting, your app can also run on earlier versions of Android. Wenn Sie z. b. das Ziel Framework auf Android 7,1 (Nougat) festlegen und die Android-Mindestversion auf Android 4.0.3 (Ice Cream Sandwich) festlegen, kann Ihre APP auf einer beliebigen Plattform von API-Ebene 15 bis einschließlich API-Ebene 25 installiert werden.For example, if you set the Target Framework to Android 7.1 (Nougat) and set the Minimum Android version to Android 4.0.3 (Ice Cream Sandwich), your app can be installed on any platform from API level 15 to API level 25, inclusive.

Obwohl Ihre APP auf diesem Platt Formbereich erfolgreich erstellt und installiert werden kann, ist dies nicht gewährleistet, dass Sie auf allen diesen Plattformen erfolgreich ausgeführt werden kann.Although your app may successfully build and install on this range of platforms, this does not guarantee that it will successfully run on all of these platforms. Wenn Ihre APP beispielsweise auf Android 5,0 (Lollipop) installiert ist und Ihr Code eine API aufruft, die nur in Android 7,1 (Nougat) und neuer verfügbar ist, erhält Ihre APP einen Laufzeitfehler und kann möglicherweise abstürzen.For example, if your app is installed on Android 5.0 (Lollipop) and your code calls an API that is available only in Android 7.1 (Nougat) and newer, your app will get a runtime error and possibly crash. Daher muss der Code zur Laufzeit – – sicherstellen, dass nur die APIs aufgerufen werden, die von dem Android-Gerät unterstützt werden, auf dem es ausgeführt wird.Therefore, your code must ensure – at runtime – that it calls only those APIs that are supported by the Android device that it is running on. Anders ausgedrückt: der Code muss explizite Laufzeitüberprüfungen enthalten, um sicherzustellen, dass Ihre APP neuere APIs nur auf Geräten verwendet, die zur Unterstützung der Anwendungen aktuell genug sind.In other words, your code must include explicit runtime checks to ensure that your app uses newer APIs only on devices that are recent enough to support them. Lauf Zeit Prüfungen für Android-Versionenweiter unten in diesem Handbuch wird erläutert, wie Sie diese Laufzeitüberprüfungen zu Ihrem Code hinzufügen.Runtime Checks for Android Versions, later in this guide, explains how to add these runtime checks to your code.

Um auf die Android-mindestversionseinstellung in Visual Studio zuzugreifen, öffnen Sie die Projekteigenschaften in Projektmappen-Explorer und wählen Sie die Seite Android-Manifest aus.To access the Minimum Android version setting in Visual Studio, open the project properties in Solution Explorer and select the Android Manifest page. Im Dropdown Menü unter Android- Mindestversion können Sie die Android-Mindestversion für die Anwendung auswählen:In the drop-down menu under Minimum Android version you can select the Minimum Android version for your application:

Mindestens für die Kompilierung mit der SDK-Version festgelegt.Minimum Android to target option set to Compile using SDK version

Wenn Sie Kompilierung mit SDK-Version verwendenauswählen, entspricht die Android-Mindestversion der Ziel Framework-Einstellung.If you select Use Compile using SDK version, the Minimum Android version will be the same as the Target Framework setting.

Android-Ziel VersionTarget Android Version

Die Android-Ziel Version (auch als targetSdkVersionbezeichnet) ist die API-Ebene des Android-Geräts, auf dem die app ausgeführt werden soll.The Target Android Version (also known as targetSdkVersion) is the API level of the Android device where the app expects to run. Android verwendet diese Einstellung, um zu bestimmen, ob Kompatibilitäts – Verhalten aktiviert werden soll. Dadurch wird sichergestellt, dass Ihre APP weiterhin erwartungsgemäß funktioniert.Android uses this setting to determine whether to enable any compatibility behaviors – this ensures that your app continues to work the way you expect. Android verwendet die Ziel-Android-Versions Einstellung Ihrer APP, um herauszufinden, welche Verhaltensänderungen auf Ihre APP angewendet werden können, ohne Sie zu unterbrechen (auf diese Weise wird die Kompatibilität von Android bereitgestellt).Android uses the Target Android version setting of your app to figure out which behavior changes can be applied to your app without breaking it (this is how Android provides forward compatibility).

Das Ziel Framework und die Android-Zielversion, die sehr ähnliche Namen aufweisen, sind nicht identisch.The Target Framework and the Target Android version, while having very similar names, are not the same thing. Die Ziel Framework-Einstellung kommuniziert API-Ziel Informationen zur Verwendung zur Kompilierzeitan xamarin. Android, während die Android-Zielversion Informationen zur Ziel-API-Ebene an Android zur Laufzeit kommuniziert (wenn die APP auf einem Gerät installiert und ausgeführt wird.)The Target Framework setting communicates target API level information to Xamarin.Android for use at compile time, while the Target Android version communicates target API level information to Android for use at run time (when the app is installed and running on a device).

Um auf diese Einstellung in Visual Studio zuzugreifen, öffnen Sie die Projekteigenschaften in Projektmappen-Explorer und wählen Sie die Seite Android-Manifest aus.To access this setting in Visual Studio, open the project properties in Solution Explorer and select the Android Manifest page. Im Dropdown Menü unter Android- Zielversion können Sie die Android-Zielversion für die Anwendung auswählen:In the drop-down menu under Target Android version you can select the Target Android version for your application:

Android-Zielversion für die Kompilierung mit SDK-Version festgelegtTarget Android version set to Compile using SDK version

Es wird empfohlen, dass Sie die Android-Zielversion explizit auf die neueste Version von Android festlegen, die Sie zum Testen Ihrer APP verwenden.We recommend that you explicitly set the Target Android version to the latest version of Android that you use to test your app. Im Idealfall sollte es auf die neueste Android SDK Version – festgelegt werden, sodass Sie neue APIs verwenden können, bevor Sie die Verhaltensänderungen durcharbeiten.Ideally, it should be set to the latest Android SDK version – this allows you to use new APIs prior to working through the behavior changes. Für die meisten Entwickler empfiehlt es sich nicht , die Android-Zielversion für die Verwendung von Compile mithilfe der SDK-Versionfestzulegen.For most developers, we do not recommend setting the Target Android version to Use Compile using SDK version.

Im Allgemeinen sollte die Android-Zielversion durch die Android-Mindestversion und das Ziel Framework begrenzt werden.In general, the Target Android Version should be bounded by the Minimum Android Version and the Target Framework. Dies bedeutet:That is:

Android-Mindestversion < = Ziel-Android-Version < = Ziel FrameworkMinimum Android Version <= Target Android Version <= Target Framework

Weitere Informationen zu SDK-Ebenen finden Sie in der Dokumentation zum Android Developer verwendet-SDK .For more information about SDK levels, see the Android Developer uses-sdk documentation.

Lauf Zeit Prüfungen für Android-VersionenRuntime checks for Android versions

Wenn jede neue Version von Android veröffentlicht wird, wird die Framework-API aktualisiert, um neue oder Ersatz Funktionen bereitzustellen.As each new version of Android is released, the framework API is updated to provide new or replacement functionality. Mit wenigen Ausnahmen wird die API-Funktionalität früherer Android-Versionen ohne Änderungen in neuere Android-Versionen weitergeführt.With few exceptions, API functionality from earlier Android versions is carried forward into newer Android versions without modifications. Wenn Ihre APP auf einer bestimmten Android-API-Ebene ausgeführt wird, kann Sie daher in der Regel ohne Änderungen auf einer späteren Android-API-Ebene ausgeführt werden.As a result, if your app runs on a particular Android API level, it will typically be able to run on a later Android API level without modifications. Aber was geschieht, wenn Sie Ihre APP auch in früheren Versionen von Android ausführen möchten?But what if you also want to run your app on earlier versions of Android?

Wenn Sie eine minimale Android-Version auswählen, die niedriger ist als die Einstellung für das Ziel Framework, sind einige APIs möglicherweise zur Laufzeit nicht für Ihre app verfügbar.If you select a Minimum Android version that is lower than your Target Framework setting, some APIs may not be available to your app at runtime. Ihre APP kann jedoch weiterhin auf einem früheren Gerät ausgeführt werden, aber mit eingeschränkter Funktionalität.However, your app can still run on an earlier device, but with reduced functionality. Für jede API, die auf Android-Plattformen nicht verfügbar ist, die ihrer Mindesteinstellung für die Android-Version entspricht, muss der Android.OS.Build.VERSION.SdkInt Code den Wert der-Eigenschaft explizit überprüfen, um die API-Ebene der Plattform zu ermitteln, auf der die app ausgeführt wird.For each API that is not available on Android platforms corresponding to your Minimum Android version setting, your code must explicitly check the value of the Android.OS.Build.VERSION.SdkInt property to determine the API level of the platform the app is running on. Wenn die API-Ebene niedriger ist als die Android-Mindestversion, die die API unterstützt, die aufgerufen werden soll, muss Ihr Code eine Möglichkeit finden, ordnungsgemäß zu funktionieren, ohne diesen API-Befehl durchführen zu müssen.If the API level is lower than the Minimum Android version that supports the API you want to call, then your code has to find a way to function properly without making this API call.

Angenommen, Sie möchten die notificationbuilder. setcategory -Methode verwenden, um eine Benachrichtigung zu kategorisieren, wenn Sie unter Android 5,0 Lollipop (und höher) ausgeführt wird, aber wir möchten weiterhin, dass unsere app unter früheren Versionen von Android ausgeführt wird, wie z . b. Android 4,1 Jelly Bean (wo SetCategory nicht verfügbar ist).For example, let's suppose that we want to use the NotificationBuilder.SetCategory method to categorize a notification when running on Android 5.0 Lollipop (and later), but we still want our app to run on earlier versions of Android such as Android 4.1 Jelly Bean (where SetCategory is not available). In Bezug auf die Android-Versions Tabelle am Anfang dieses Leitfadens sehen Sie, dass der buildversionscode für Android 5,0 Lollipop lautet Android.OS.BuildVersionCodes.Lollipop.Referring to the Android version table at the beginning of this guide, we see that the build version code for Android 5.0 Lollipop is Android.OS.BuildVersionCodes.Lollipop. Zur Unterstützung älterer Android-Versionen SetCategory , bei denen nicht verfügbar ist, kann der Code die API-Ebene zur Laufzeit SetCategory erkennen und bedingt nur dann aufgerufen werden, wenn die API-Ebene größer oder gleich dem Lollipop Build-Versions Code ist:To support older versions of Android where SetCategory is not available, our code can detect the API level at runtime and conditionally call SetCategory only when the API level is greater than or equal to the Lollipop build version code:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    builder.SetCategory(Notification.CategoryEmail);
}

In diesem Beispiel ist das Ziel Framework unserer App auf Android 5,0 (API-Ebene 21) und die Android-Mindestversion auf Android 4,1 (API-Ebene 16) festgelegt.In this example, our app's Target Framework is set to Android 5.0 (API Level 21) and its Minimum Android version is set to Android 4.1 (API Level 16). Da SetCategory auf API-Ebene Android.OS.BuildVersionCodes.Lollipop und höher verfügbar ist, wird in diesem Beispiel SetCategory Code nur aufgerufen, wenn er – tatsächlich verfügbar ist. es wird SetCategory nicht versucht, aufzurufen, wenn die API-Ebene 16, 17, 18, 19 oder 20 ist.Because SetCategory is available in API level Android.OS.BuildVersionCodes.Lollipop and later, this example code will call SetCategory only when it is actually available – it will not attempt to call SetCategory when the API level is 16, 17, 18, 19, or 20. Die Funktionalität wird in diesen früheren Android-Versionen nur dahingehend reduziert, dass Benachrichtigungen nicht ordnungsgemäß sortiert werden (da Sie nicht nach Typ kategorisiert werden), aber die Benachrichtigungen werden weiterhin veröffentlicht, um den Benutzer zu benachrichtigen.The functionality is reduced on these earlier Android versions only to the extent that notifications are not sorted properly (because they are not categorized by type), yet the notifications are still published to alert the user. Unsere APP funktioniert weiterhin, die Funktionalität wird jedoch geringfügig beeinträchtigt.Our app still works, but its functionality is slightly diminished.

Im Allgemeinen unterstützt die Überprüfung der Buildversion dem Code die Entscheidung zur Laufzeit zwischen der neuen Methode und der alten Methode.In general, the build version check helps your code decide at runtime between doing something the new way versus the old way. Beispiel:For example:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    // Do things the Lollipop way
}
else
{
    // Do things the pre-Lollipop way
}

Es gibt keine schnelle und einfache Regel, die erläutert, wie Sie die Funktionalität Ihrer APP reduzieren oder ändern können, wenn Sie auf älteren Android-Versionen ausgeführt wird, bei denen mindestens eine API fehlt.There's no fast and simple rule that explains how to reduce or modify your app's functionality when it runs on older Android versions that are lacking one or more APIs. In einigen Fällen (z. b. SetCategory im obigen Beispiel) genügt es, den API-Befehl auszulassen, wenn er nicht verfügbar ist.In some cases (such as in the SetCategory example above), it's sufficient to omit the API call when it's not available. In anderen Fällen müssen Sie jedoch möglicherweise Alternative Funktionen für implementieren, wenn Android.OS.Build.VERSION.SdkInt erkannt wird, dass die API-Ebene, die Ihre APP benötigt, um die optimale Umgebung zu präsentieren.However, in other cases, you may need to implement alternate functionality for when Android.OS.Build.VERSION.SdkInt is detected to be less than the API level that your app needs to present its optimum experience.

API-Ebenen und-BibliothekenAPI levels and libraries

Wenn Sie ein xamarin. Android-Bibliotheksprojekt erstellen (z. b. eine Klassenbibliothek oder eine Bindungs Bibliothek), können Sie nur die Ziel – Framework-Einstellung der Android-Mindestversion konfigurieren, und die Einstellungen der Android-Zielversion sind nicht verfügbar.When you create a Xamarin.Android library project (such as a class library or a bindings library), you can configure only the Target Framework setting – the Minimum Android version and the Target Android version settings are not available. Dies liegt daran, dass keine Android-Manifest -Seite vorhanden ist:That is because there is no Android Manifest page:

Nur die Option Kompilierung mit Android-Version ist verfügbar.Only the Compile using Android version option is available

Die Android-Mindestversion und die Android-Zielversion sind nicht verfügbar, da es sich bei der resultierenden Bibliothek nicht – um eine eigenständige App handelt, kann die Bibliothek abhängig von der APP, mit der Sie verpackt ist, unter jeder beliebigen Android-Version ausgeführt werden.The Minimum Android version and Target Android version settings are not available because the resulting library is not a stand-alone app – the library could be run on any Android version, depending on the app that it is packaged with. Sie können angeben, wie die Bibliothek kompiliertwerden soll, aber Sie können nicht vorhersagen, auf welcher Plattform-API-Ebene die Bibliothek ausgeführt werden soll.You can specify how the library is to be compiled, but you can't predict which platform API level the library will be run on. Beachten Sie, dass beim Verarbeiten oder Erstellen von Bibliotheken die folgenden bewährten Methoden beachtet werden sollten:With this in mind, the following best practices should be observed when consuming or creating libraries:

  • Bei der Nutzung einer Android-Bibliothek Wenn Sie in Ihrer Anwendung eine Android-Bibliothek verwenden, stellen Sie sicher, dass die Ziel Framework-Einstellung Ihrer APP auf eine API-Ebene festgelegt ist, die mindestens so hoch ist wie die Ziel Framework-Einstellung der Bibliothek. –When consuming an Android library – If you are consuming an Android library in your application, be sure to set your app's Target Framework setting to an API level that is at least as high as the Target Framework setting of the library.

  • Beim Erstellen einer Android-Bibliothek – Wenn Sie eine Android-Bibliothek für die Verwendung durch andere Anwendungen erstellen, achten Sie darauf, dass die Ziel Framework-Einstellung auf die minimale API-Ebene festgelegt wird, die für die Kompilierung benötigt wird.When creating an Android library – If you are creating an Android library for use by other applications, be sure to set its Target Framework setting to the minimum API level that it needs in order to compile.

Diese bewährten Methoden werden empfohlen, um die Situation zu vermeiden, in der eine Bibliothek versucht, eine API aufzurufen, die zur Laufzeit nicht verfügbar ist (was dazu führen kann, dass die APP abstürzen kann).These best practices are recommended to help prevent the situation where a library attempts to call an API that is not available at runtime (which can cause the app to crash). Wenn Sie ein Bibliotheks Entwickler sind, sollten Sie die Verwendung von API-aufrufen auf eine kleine und gut festgelegte Teilmenge der gesamten API-Oberfläche einschränken.If you are a library developer, you should strive to restrict your usage of API calls to a small and well-established subset of the total API surface area. Auf diese Weise können Sie sicherstellen, dass Ihre Bibliothek sicher in einer breiteren Palette von Android-Versionen verwendet werden kann.Doing so helps to ensure that your library can be used safely across a wider range of Android versions.

ZusammenfassungSummary

In diesem Leitfaden wurde erläutert, wie Android-API-Ebenen verwendet werden, um die APP-Kompatibilität in verschiedenen Versionen von Android zu verwaltenThis guide explained how Android API levels are used to manage app compatibility across different versions of Android. Es wurden ausführliche Schritte zum Konfigurieren des xamarin. Android- Ziel Frameworks, der Android-Mindestversionund der Projekteinstellungen für Android-Ziel Versionen bereitgestellt.It provided detailed steps for configuring the Xamarin.Android Target Framework, Minimum Android version, and Target Android version project settings. Es wurden Anweisungen zum Verwenden des Android SDK-Managers zum Installieren von SDK-Paketen bereitgestellt. Beispiele für das Schreiben von Code für die Bearbeitung verschiedener API-Ebenen zur Laufzeit sowie das Verwalten von API-Ebenen beim Erstellen oder Verarbeiten von Android-Bibliotheken.It provided instructions for using the Android SDK Manager to install SDK packages, included examples of how to write code to deal with different API levels at runtime, and explained how to manage API levels when creating or consuming Android libraries. Außerdem wurde eine umfassende Liste bereitgestellt, die API-Ebenen mit Android-Versionsnummern (z. b. Android 4,4), Android-Versionsnamen (z. b. KitKat) und xamarin. Android-buildversionscodes verknüpft.It also provided a comprehensive list that relates API levels to Android version numbers (such as Android 4.4), Android version names (such as Kitkat), and Xamarin.Android build version codes.