Descripción de los niveles de API de Android

Xamarin.Android tiene varias configuraciones de nivel de API de Android que determinan la compatibilidad de la aplicación con varias versiones de Android. En esta guía se explica lo que significan estas opciones, cómo configurarlas y qué efecto tienen en la aplicación en tiempo de ejecución.

Inicio rápido

Xamarin.Android expone tres configuraciones de proyecto de nivel de API de Android:

• Plataforma de destino: especifica qué marco se va a usar para compilar la aplicación. Xamarin.Android usa este nivel de API en tiempo de compilación.

• Versión mínima de Android: especifica la versión de Android más antigua que quiere que admita la aplicación. Android usa este nivel de API en tiempo de ejecución.

• Versión de Android de destino: especifica la versión de Android en la que se va a ejecutar la aplicación. Android usa este nivel de API en tiempo de ejecución.

Para poder configurar un nivel de API para el proyecto, debe instalar los componentes de la plataforma del SDK para ese nivel de API. Para obtener más información sobre cómo descargar e instalar Android SDK componentes, vea Android SDK instalación de.

Si la aplicación admite varias versiones de Android, el código debe incluir comprobaciones en tiempo de ejecución para asegurarse de que la aplicación funciona con la configuración versión mínima de Android (consulte Comprobaciones en tiempo de ejecución para versiones de Android a continuación para obtener más información). Si va a consumir o crear una biblioteca, consulte Niveles y bibliotecas de API a continuación para obtener procedimientos recomendados para configurar las opciones de nivel de API para las bibliotecas.

Versiones de Android y niveles de API

A medida que la plataforma Android evoluciona y se lanzan nuevas versiones de Android, a cada versión de Android se le asigna un identificador entero único, denominado nivel de API. Por lo tanto, cada versión de Android corresponde a un único nivel de API de Android. Dado que los usuarios instalan aplicaciones en versiones anteriores, así como en las versiones más recientes de Android, las aplicaciones android del mundo real deben diseñarse para funcionar con varios niveles de API de Android.

Versiones de Android

Cada versión de Android va por varios nombres:

• La versión de Android, como Android 9.0
• Un nombre de código (o desaigo), como Pie
• Un nivel de API correspondiente, como el nivel de API 28

Un nombre de código de Android puede corresponder a varias versiones y niveles de API (como se muestra en la tabla siguiente), pero cada versión de Android corresponde exactamente a un nivel de API.

Además, Xamarin.Android define códigos de versión de compilación que se asignan a los niveles de API de Android conocidos actualmente. La tabla siguiente puede ayudarle a traducir entre el nivel de API, la versión de Android, el nombre de código y el código de versión de compilación de Xamarin.Android (los códigos de versión de compilación se definen en el espacio de Android.OS nombres ):

Como se indica en esta tabla, las nuevas versiones de Android se lanzan con frecuencia, a veces más de una versión al año. Como resultado, el universo de dispositivos Android que podrían ejecutar la aplicación incluye una amplia variedad de versiones de Android anteriores y más recientes. ¿Cómo se puede garantizar que la aplicación se ejecutará de forma coherente y confiable en tantas versiones diferentes de Android? Los niveles de API de Android pueden ayudarle a administrar este problema.

Niveles de API de Android

Cada dispositivo Android se ejecuta exactamente en un nivel de API: se garantiza que este nivel de API es único según la versión de la plataforma Android. El nivel de API identifica con precisión la versión del conjunto de API al que puede llamar la aplicación. identifica la combinación de elementos de manifiesto, permisos, etc. con los que se codifica como desarrollador. El sistema de niveles de API de Android ayuda a Android a determinar si una aplicación es compatible con una imagen del sistema Android antes de instalar la aplicación en un dispositivo.

Cuando se ha creado una aplicación, contiene la siguiente información de nivel de API:

• El nivel de API de destino de Android en el que se ha creado la aplicación para ejecutarse.

• El nivel mínimo de API de Android que debe tener un dispositivo Android para ejecutar la aplicación.

Esta configuración se usa para asegurarse de que la funcionalidad necesaria para ejecutar correctamente la aplicación está disponible en el dispositivo Android en el momento de la instalación. Si no es así, la aplicación no se puede ejecutar en ese dispositivo. Por ejemplo, si el nivel de API de un dispositivo Android es inferior al nivel mínimo de API que especifique para la aplicación, el dispositivo Android impedirá que el usuario instale la aplicación.

Project de nivel de API

En las secciones siguientes se explica cómo usar Administrador de SDK para preparar el entorno de desarrollo para los niveles de API de destino, seguido de explicaciones detalladas sobre cómo configurar la plataforma de destino,la versión mínima de Androidy la versión de Android de destino en Xamarin.Android.

Android SDK plataformas

Para poder seleccionar un nivel de API de destino o mínimo en Xamarin.Android, debe instalar la versión de la plataforma Android SDK correspondiente a ese nivel de API. El intervalo de opciones disponibles para la plataforma de destino, la versión mínima de Android y la versión de Android de destino se limita al intervalo de Android SDK versiones que ha instalado. Puede usar el Administrador de SDK para comprobar que están instaladas las versiones de Android SDK necesarias y puede usarlas para agregar los nuevos niveles de API que necesite para la aplicación. Si no está familiarizado con la instalación de niveles de API, consulte el Android SDK instalación de.

Versión de .NET Framework de destino

La plataforma de destino (también conocida como ) es la versión específica de Android Framework (nivel de API) para la que se compila la aplicación en tiempo de compilación. Esta configuración especifica qué API espera usar la aplicación cuando se ejecuta, pero no tiene ningún efecto en qué API están disponibles realmente para la aplicación cuando se instala. Como resultado, el cambio de la configuración de la plataforma de destino no cambia el comportamiento del entorno de ejecución.

La plataforma de destino identifica las versiones de biblioteca con las que está vinculada la aplicación: esta configuración determina qué API puede usar en la aplicación. Por ejemplo, si desea usar el método NotificationBuilder.SetCategory que se introdujo en Android 5.0 Lollipop, debe establecer la plataforma de destino en nivel de API 21 (Lollipop) o posterior. Si establece la plataforma de destino del proyecto en un nivel de API como el nivel de API 19 (Kit Qr) e intenta llamar al método en el código, se producirá un error de compilación.

Se recomienda compilar siempre con la versión más reciente disponible de La plataforma de destino. Al hacerlo, se proporcionan mensajes de advertencia útiles para cualquier API en desuso a la que pueda llamar el código. El uso de la versión más reciente de La plataforma de destino es especialmente importante cuando se usan las versiones más recientes de la biblioteca de compatibilidad: cada biblioteca espera que la aplicación se compile en el nivel mínimo de API de esa biblioteca de compatibilidad o superior.

Versión mínima de Android

La versión mínima de Android (también conocida como ) es la versión más antigua del sistema operativo Android (es decir, el nivel de API más bajo) que puede instalar y ejecutar la aplicación. De forma predeterminada, una aplicación solo se puede instalar en dispositivos que coincidan con la configuración de la plataforma de destino o superior. Si la configuración versión mínima de Android es inferior a la configuración de la plataforma de destino, la aplicación también se puede ejecutar en versiones anteriores de Android. Por ejemplo, si establece la plataforma de destino en Android 7.1 (Chocolate) y establece la versión mínima de Android en Android 4.0.3 (Ice Cream Sandwich),la aplicación se puede instalar en cualquier plataforma desde el nivel de API 15 al nivel de API 25, ambos inclusive.

Aunque la aplicación puede compilarse e instalarse correctamente en esta variedad de plataformas, esto no garantiza que se ejecutará correctamente en todas estas plataformas. Por ejemplo, si la aplicación está instalada en Android 5.0 (Lollipop) y el código llama a una API que solo está disponible en Android 7.1 (Lollipop) y versiones más recientes, la aplicación recibirá un error en tiempo de ejecución y posiblemente se bloqueará. Por lo tanto, el código debe asegurarse (en tiempo de ejecución) de que llama solo a las API compatibles con el dispositivo Android en el que se ejecuta. En otras palabras, el código debe incluir comprobaciones explícitas en tiempo de ejecución para asegurarse de que la aplicación usa API más recientes solo en dispositivos lo suficientemente recientes como para admitirlas. Comprobaciones en tiempo de ejecución paraversiones de Android, más adelante en esta guía, explica cómo agregar estas comprobaciones en tiempo de ejecución al código.

Versión de Android de destino

La versión de Android de destino (también conocida como ) es el nivel de API del dispositivo Android donde la aplicación espera ejecutarse. Android usa esta configuración para determinar si se deben habilitar los comportamientos de compatibilidad, lo que garantiza que la aplicación siga funcionando de la manera esperada. Android usa la configuración de la versión de Android de destino de la aplicación para averiguar qué cambios de comportamiento se pueden aplicar a la aplicación sin que se rompa (así es como Android proporciona compatibilidad con versiones avanzar).

La plataforma de destino y la versión de Android de destino, aunque tienen nombres muy similares, no son lo mismo. La configuración de plataforma de destino comunica información de nivel de API de destino a Xamarin.Android para su uso en tiempo de compilación, mientras que la versión de Android de destino comunica información de nivel de API de destino a Android para su uso en tiempo de ejecución (cuando la aplicación se instala y se ejecuta en un dispositivo).

En general, la versión de Android de destino debe estar limitada por la versión mínima de Android y la plataforma de destino. Es decir:

Versión mínima de Android = Versión de Android de destino = Plataforma de < destino

Para más información sobre los niveles de SDK, consulte la documentación de usos-sdk para desarrolladores de Android.

Comprobaciones en tiempo de ejecución de las versiones de Android

A medida que se lanza cada nueva versión de Android, la API del marco se actualiza para proporcionar funcionalidad nueva o de reemplazo. Con pocas excepciones, la funcionalidad de API de versiones anteriores de Android se lleva a cabo en versiones más recientes de Android sin modificaciones. Como resultado, si la aplicación se ejecuta en un nivel de API de Android determinado, normalmente podrá ejecutarse en un nivel de API de Android posterior sin modificaciones. Pero , ¿qué ocurre si también quiere ejecutar la aplicación en versiones anteriores de Android?

Si selecciona una versión mínima de Android que sea inferior a la configuración de La plataforma de destino, es posible que algunas API no estén disponibles para la aplicación en tiempo de ejecución. Sin embargo, la aplicación todavía se puede ejecutar en un dispositivo anterior, pero con una funcionalidad reducida. Para cada API que no esté disponible en las plataformas Android correspondientes a la configuración de la versión mínima de Android, el código debe comprobar explícitamente el valor de la propiedad para determinar el nivel de API de la plataforma en la que se ejecuta la Android.OS.Build.VERSION.SdkInt aplicación. Si el nivel de API es inferior a la versión mínima de Android que admite la API a la que desea llamar, el código debe encontrar una manera de funcionar correctamente sin realizar esta llamada API.

Por ejemplo, supongamos que queremos usar el método NotificationBuilder.SetCategory para clasificar una notificación cuando se ejecuta en Android 5.0 Lollipop (y versiones posteriores), pero queremos que la aplicación se ejecute en versiones anteriores de Android, como Android 4.1 Bean de bean de bean (donde no está disponible). Al hacer referencia a la tabla de versiones de Android al principio de esta guía, vemos que el código de versión de compilación para Android 5.0 Lollipop es . Para admitir versiones anteriores de Android donde no está disponible, nuestro código puede detectar el nivel de API en tiempo de ejecución y llamar condicionalmente solo cuando el nivel de API es mayor o igual que el código de versión de compilación SetCategorySetCategory de Lollipop:

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

En este ejemplo, la plataforma de destino de la aplicación se establece en Android 5.0 (nivel de API 21) y su versión mínima de Android se establece en Android 4.1 (nivel de API 16). Dado que está disponible en el nivel de API y versiones posteriores, este código de ejemplo llamará solo cuando esté disponible realmente; no intentará llamar a cuando el nivel de API sea SetCategoryAndroid.OS.BuildVersionCodes.LollipopSetCategorySetCategorySetCategory 16, 17, 18, 19 o 20. La funcionalidad se reduce en estas versiones anteriores de Android solo en la medida en que las notificaciones no se ordenan correctamente (porque no están clasificadas por tipo), pero las notificaciones se siguen publicando para alertar al usuario. Nuestra aplicación sigue funcionando, pero su funcionalidad se reduce ligeramente.

En general, la comprobación de la versión de compilación ayuda al código a decidir en tiempo de ejecución entre hacer algo nuevo frente a lo anterior. Por ejemplo:

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

No hay ninguna regla rápida y sencilla que explique cómo reducir o modificar la funcionalidad de la aplicación cuando se ejecuta en versiones anteriores de Android que carecen de una o varias API. En algunos casos (como en el ejemplo anterior), es suficiente omitir la llamada SetCategory API cuando no está disponible. Sin embargo, en otros casos, es posible que tenga que implementar una funcionalidad alternativa para cuando se detecte que es menor que el nivel de API que la aplicación necesita para presentar Android.OS.Build.VERSION.SdkInt su experiencia óptima.

Niveles de API y bibliotecas

La configuración de versión mínima de Android y versión de Android de destino no está disponible porque la biblioteca resultante no es una aplicación independiente: la biblioteca se podría ejecutar en cualquier versión de Android, en función de la aplicación con la que esté empaquetada. Puede especificar cómo se va a compilar la biblioteca,pero no puede predecir en qué nivel de API de plataforma se ejecutará la biblioteca. Con esto en mente, se deben tener en cuenta los siguientes procedimientos recomendados al consumir o crear bibliotecas:

• Al consumir una biblioteca de Android: si está consumiendo una biblioteca de Android en la aplicación, asegúrese de establecer la configuración de la plataforma de destino de la aplicación en un nivel de API que sea al menos tan alto como la configuración de la plataforma de destino de la biblioteca.

• Al crear una biblioteca de Android: si va a crear una biblioteca de Android para su uso por otras aplicaciones, asegúrese de establecer su configuración de plataforma de destino en el nivel mínimo de API que necesita para compilar.

Estos procedimientos recomendados se recomiendan para ayudar a evitar la situación en la que una biblioteca intenta llamar a una API que no está disponible en tiempo de ejecución (lo que puede hacer que la aplicación se bloquea). Si es desarrollador de bibliotecas, debe procurar restringir el uso de llamadas API a un subconjunto pequeño y bien establecido del área de superficie total de la API. Esto ayuda a garantizar que la biblioteca se puede usar de forma segura en una gama más amplia de versiones de Android.

Resumen

En esta guía se explica cómo se usan los niveles de API de Android para administrar la compatibilidad de aplicaciones en distintas versiones de Android. Se proporcionaron pasos detallados para configurar la configuración del proyecto De destino de Xamarin.Android, Versión mínima de Androidy Versión de Android de destino. Se proporcionan instrucciones para usar Administrador de Android SDK para instalar paquetes del SDK, se incluyen ejemplos de cómo escribir código para tratar con distintos niveles de API en tiempo de ejecución y se explica cómo administrar los niveles de API al crear o consumir bibliotecas de Android. También se proporcionó una lista completa que relaciona los niveles de API con los números de versión de Android (como Android 4.4), los nombres de versión de Android (como Kit qr) y los códigos de versión de compilación de Xamarin.Android.

Vínculos relacionados

• Configuración de Android SDK
• Cambios en las herramientas de la CLI del SDK
• Selección de compileSdkVersion, minSdkVersion y targetSdkVersion
• ¿Qué es el nivel de API?
• Nombres de código, etiquetas y números de compilación