Understanding Android API Levels (Informazioni sui livelli API Android)

Xamarin.Android include diverse impostazioni a livello di API Android che determinano la compatibilità dell'app con più versioni di Android. Questa guida spiega cosa significano queste impostazioni, come configurarle e quali effetti hanno sull'app in fase di esecuzione.

Avvio rapido

Xamarin.Android espone tre impostazioni del progetto a livello di API Android:

• Framework di destinazione: specifica il framework da usare per la compilazione dell'applicazione. Questo livello api viene usato in fase di compilazione da Xamarin.Android.

• Versione minima di Android: specifica la versione android meno recente che si vuole supportare per l'app. Questo livello api viene usato in fase di esecuzione da Android.

• Versione android di destinazione: specifica la versione di Android in cui deve essere eseguita l'app. Questo livello api viene usato in fase di esecuzione da Android.

Prima di poter configurare un livello API per il progetto, è necessario installare i componenti della piattaforma SDK per tale livello di API. Per altre informazioni sul download e l'installazione di componenti android SDK, vedere Installazione di Android SDK.

Se l'app supporta più versioni di Android, il codice deve includere controlli di runtime per assicurarsi che l'app funzioni con l'impostazione Versione minima di Android (vedi Controlli di runtime per le versioni Android di seguito per informazioni dettagliate). Se si usa o si crea una libreria, vedere Livelli API e librerie di seguito per le procedure consigliate per la configurazione delle impostazioni a livello di API per le librerie.

Versioni di Android e livelli api

Man mano che la piattaforma Android evolve e vengono rilasciate nuove versioni di Android, a ogni versione di Android viene assegnato un identificatore integer univoco, denominato livello API. Di conseguenza, ogni versione di Android corrisponde a un singolo livello API Android. Poiché gli utenti installano app in versioni precedenti e nelle versioni più recenti di Android, le app Android reali devono essere progettate per funzionare con più livelli di API Android.

Versioni di Android

Ogni versione di Android passa da più nomi:

• La versione di Android, ad esempio Android 9.0
• Un nome di codice (o dessert), ad esempio Pie
• Livello API corrispondente, ad esempio il livello API 28

Un nome di codice Android può corrispondere a più versioni e livelli di API (come illustrato nella tabella seguente), ma ogni versione di Android corrisponde esattamente a un livello API.

Inoltre, Xamarin.Android definisce i codici di versione di compilazione che eseguono il mapping ai livelli api Android attualmente noti. La tabella seguente consente di tradurre tra il livello API, la versione android, il nome del codice e il codice della versione di compilazione di Xamarin.Android (i codici di versione della build sono definiti nello spazio dei Android.OS nomi):

Come indicato in questa tabella, le nuove versioni di Android vengono rilasciate frequentemente, a volte più di una versione all'anno. Di conseguenza, l'universo dei dispositivi Android che potrebbero eseguire l'app include un'ampia gamma di versioni precedenti e più recenti di Android. Come puoi garantire che l'app venga eseguita in modo coerente e affidabile su così tante versioni diverse di Android? I livelli API di Android consentono di gestire questo problema.

Livelli di API Android

Ogni dispositivo Android viene eseguito esattamente a un livello API: questo livello di API è garantito che sia univoco per ogni versione della piattaforma Android. Il livello API identifica con precisione la versione del set di API in cui l'app può chiamare; identifica la combinazione di elementi manifesto, autorizzazioni e così via, rispetto a cui si esegue il codice come sviluppatore. Il sistema android dei livelli API aiuta Android a determinare se un'applicazione è compatibile con un'immagine di sistema Android prima di installare l'applicazione in un dispositivo.

Quando un'applicazione viene compilata, contiene le informazioni seguenti sul livello API:

• Livello API di destinazione di Android in cui viene compilata l'app.

• Il livello minimo di API Android che un dispositivo Android deve eseguire l'app.

Queste impostazioni vengono usate per assicurarsi che le funzionalità necessarie per eseguire correttamente l'app siano disponibili nel dispositivo Android in fase di installazione. In caso contrario, l'app non è in esecuzione nel dispositivo. Ad esempio, se il livello API di un dispositivo Android è inferiore al livello api minimo specificato per l'app, il dispositivo Android impedirà all'utente di installare l'app.

Impostazioni a livello di API del progetto

Le sezioni seguenti illustrano come usare SDK Manager per preparare l'ambiente di sviluppo per i livelli api di destinazione, seguiti da spiegazioni dettagliate su come configurare framework di destinazione, versione minima di Android e Impostazioni della versione android di destinazione in Xamarin.Android.

Piattaforme Android SDK

Prima di poter selezionare un livello api di destinazione o minimo in Xamarin.Android, è necessario installare la versione della piattaforma Android SDK corrispondente a tale livello di API. La gamma di opzioni disponibili per Framework di destinazione, Versione minima di Android e Versione android di destinazione è limitata alla gamma di versioni di Android SDK installate. È possibile usare SDK Manager per verificare che siano installate le versioni necessarie di Android SDK ed è possibile usarlo per aggiungere nuovi livelli di API necessari per l'app. Se non si ha familiarità con come installare i livelli api, vedere Installazione di Android SDK.

Framework di destinazione

Il framework di destinazione (noto anche come compileSdkVersion) è la versione specifica del framework Android (livello API) per cui l'app viene compilata in fase di compilazione. Questa impostazione specifica le API che l'app prevede di usare durante l'esecuzione, ma non ha alcun effetto sulle API effettivamente disponibili per l'app quando viene installata. Di conseguenza, la modifica dell'impostazione Framework di destinazione non modifica il comportamento di runtime.

Il framework di destinazione identifica le versioni della libreria a cui è collegata l'applicazione. Questa impostazione determina le API che è possibile usare nell'app. Ad esempio, se si vuole usare il metodo NotificationBuilder.SetCategory introdotto in Android 5.0 Lollipop, è necessario impostare Target Framework su Livello API 21 (Lollipop) o versione successiva. Se si imposta Il framework di destinazione del progetto su un livello API, ad esempio il livello API 19 (KitKat) e si tenta di chiamare il SetCategory metodo nel codice, si otterrà un errore di compilazione.

È consigliabile compilare sempre con la versione più recente disponibile di Framework di destinazione. In questo modo vengono forniti messaggi di avviso utili per tutte le API deprecate che potrebbero essere chiamate dal codice. L'uso della versione più recente di Framework di destinazione è particolarmente importante quando usi le versioni più recenti della libreria di supporto. Ogni libreria prevede che l'app venga compilata a livello api minimo o superiore della libreria di supporto.

Versione minima di Android

La versione minima di Android (nota anche come minSdkVersion) è la versione meno recente del sistema operativo Android (ad esempio, il livello API più basso) che può installare ed eseguire l'applicazione. Per impostazione predefinita, un'app può essere installata solo nei dispositivi che corrispondono all'impostazione Framework di destinazione o versione successiva; se l'impostazione Versione minima di Android è inferiore all'impostazione Framework di destinazione, l'app può essere eseguita anche nelle versioni precedenti di Android. Ad esempio, se si imposta Target Framework su Android 7.1 (Nougat) e si imposta la versione minima di Android su Android 4.0.3 (Ice Cream Sandwich), l'app può essere installata in qualsiasi piattaforma dal livello API 15 al livello API 25, incluso.

Anche se l'app può essere compilata e installata correttamente in questa gamma di piattaforme, ciò non garantisce che venga eseguito correttamente in tutte queste piattaforme. Ad esempio, se l'app è installata in Android 5.0 (Lollipop) e il codice chiama un'API disponibile solo in Android 7.1 (Nougat) e versioni successive, l'app riceverà un errore di runtime e probabilmente si arresterà in modo anomalo. Di conseguenza, il codice deve assicurarsi, in fase di esecuzione, di chiamare solo le API supportate dal dispositivo Android in cui è in esecuzione. In altre parole, il codice deve includere controlli di runtime espliciti per assicurarsi che l'app usi API più recenti solo nei dispositivi sufficientemente recenti per supportarli. I controlli di runtime per le versioni android, più avanti in questa guida, illustrano come aggiungere questi controlli di runtime al codice.

Versione di Android di destinazione

La versione android di destinazione (nota anche come targetSdkVersion) è il livello API del dispositivo Android in cui l'app prevede l'esecuzione. Android usa questa impostazione per determinare se abilitare eventuali comportamenti di compatibilità. Ciò garantisce che l'app continui a funzionare nel modo previsto. Android usa l'impostazione Versione android di destinazione dell'app per determinare quali modifiche di comportamento possono essere applicate all'app senza interromperla (questo è il modo in cui Android offre compatibilità con l'inoltro).

Il framework di destinazione e la versione di Android di destinazione, pur avendo nomi molto simili, non sono la stessa cosa. L'impostazione Framework di destinazione comunica le informazioni a livello di API di destinazione a Xamarin.Android da usare in fase di compilazione, mentre la versione android di destinazione comunica le informazioni sul livello API di destinazione ad Android per l'uso in fase di esecuzione (quando l'app viene installata e in esecuzione in un dispositivo).

In generale, la versione android di destinazione deve essere vincolata dalla versione minima di Android e dal framework di destinazione. Ovvero:

Versione <minima di Android = Versione <android di destinazione = Framework di destinazione

Per altre informazioni sui livelli SDK, vedere la documentazione relativa agli sviluppatori Android uses-sdk .

Controlli di runtime per le versioni di Android

Man mano che viene rilasciata ogni nuova versione di Android, l'API del framework viene aggiornata per fornire funzionalità nuove o sostitutive. Con poche eccezioni, la funzionalità API delle versioni precedenti di Android viene portata avanti in versioni più recenti di Android senza modifiche. Di conseguenza, se l'app viene eseguita in un determinato livello api Android, in genere sarà in grado di essere eseguita in un livello api Android successivo senza modifiche. Ma cosa succede se si vuole anche eseguire l'app in versioni precedenti di Android?

Se si seleziona una versione minima di Android inferiore all'impostazione Framework di destinazione, alcune API potrebbero non essere disponibili per l'app in fase di esecuzione. Tuttavia, l'app può comunque essere eseguita in un dispositivo precedente, ma con funzionalità ridotte. Per ogni API non disponibile nelle piattaforme Android corrispondenti all'impostazione Versione minima di Android, il codice deve controllare in modo esplicito il valore della Android.OS.Build.VERSION.SdkInt proprietà per determinare il livello API della piattaforma in cui è in esecuzione l'app. Se il livello API è inferiore alla versione minima di Android che supporta l'API che si vuole chiamare, il codice deve trovare un modo per funzionare correttamente senza effettuare questa chiamata API.

Si supponga, ad esempio, di voler usare il metodo NotificationBuilder.SetCategory per classificare una notifica durante l'esecuzione in Android 5.0 Lollipop (e versioni successive), ma si vuole comunque che l'app venga eseguita in versioni precedenti di Android, ad esempio Android 4.1 Jelly Bean (dove SetCategory non è disponibile). Facendo riferimento alla tabella delle versioni di Android all'inizio di questa guida, si noterà che il codice della versione di compilazione per Android 5.0 Lollipop è Android.OS.BuildVersionCodes.Lollipop. Per supportare le versioni precedenti di Android in cui SetCategory non è disponibile, il codice può rilevare il livello API in fase di esecuzione e chiamare SetCategory in modo condizionale solo quando il livello API è maggiore o uguale al codice della versione di compilazione Lollipop:

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

In questo esempio il framework di destinazione dell'app è impostato su Android 5.0 (livello API 21) e la versione minima di Android è impostata su Android 4.1 (livello API 16). Poiché SetCategory è disponibile a livello Android.OS.BuildVersionCodes.Lollipop di API e versioni successive, questo codice di esempio chiamerà SetCategory solo quando è effettivamente disponibile. Non tenterà di chiamare SetCategory quando il livello API è 16, 17, 18, 19 o 20. La funzionalità viene ridotta in queste versioni precedenti di Android solo nella misura in cui le notifiche non vengono ordinate correttamente (perché non sono classificate per tipo), ma le notifiche vengono comunque pubblicate per avvisare l'utente. La nostra app funziona ancora, ma la sua funzionalità è leggermente diminuita.

In generale, il controllo della versione di compilazione consente al codice di decidere in fase di esecuzione tra l'esecuzione di un metodo nuovo rispetto al vecchio modo. Ad esempio:

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

Non esiste una regola veloce e semplice che spiega come ridurre o modificare le funzionalità dell'app quando viene eseguita in versioni precedenti di Android che mancano di una o più API. In alcuni casi, ad esempio nell'esempio SetCategory precedente, è sufficiente omettere la chiamata API quando non è disponibile. In altri casi, tuttavia, potrebbe essere necessario implementare funzionalità alternative per quando Android.OS.Build.VERSION.SdkInt viene rilevato che è minore del livello API che l'app deve presentare l'esperienza ottimale.

Livelli e librerie delle API

Le impostazioni Versione minima di Android e Versione android di destinazione non sono disponibili perché la libreria risultante non è un'app autonoma. La libreria può essere eseguita in qualsiasi versione di Android, a seconda dell'app con cui è incluso. È possibile specificare la modalità di compilazione della libreria, ma non è possibile stimare il livello api della piattaforma in cui verrà eseguita la libreria. Tenendo presente questo aspetto, è consigliabile osservare le procedure consigliate seguenti quando si usano o si creano librerie:

• Quando si usa una libreria Android: se si usa una libreria Android nell'applicazione, assicurarsi di impostare l'impostazione Framework di destinazione dell'app su un livello API almeno elevato dell'impostazione Framework di destinazione della libreria.

• Quando si crea una libreria Android: se si crea una libreria Android per l'uso da parte di altre applicazioni, assicurarsi di impostare l'impostazione Framework di destinazione sul livello API minimo necessario per la compilazione.

Queste procedure consigliate sono consigliate per evitare la situazione in cui una libreria tenta di chiamare un'API non disponibile in fase di esecuzione (che può causare l'arresto anomalo dell'app). Gli sviluppatori di librerie devono cercare di limitare l'utilizzo delle chiamate API a un subset ridotto e ben stabilito della superficie totale dell'API. In questo modo è possibile assicurarsi che la libreria possa essere usata in modo sicuro in un'ampia gamma di versioni di Android.

Riepilogo

Questa guida ha illustrato come vengono usati i livelli api Android per gestire la compatibilità delle app tra versioni diverse di Android. Sono stati forniti passaggi dettagliati per configurare il framework di destinazione Xamarin.Android, la versione minima di Android e le impostazioni del progetto versione android di destinazione. Sono state fornite istruzioni per l'uso di Android SDK Manager per installare pacchetti SDK, inclusi esempi di come scrivere codice per gestire diversi livelli di API in fase di esecuzione e come gestire i livelli API durante la creazione o l'utilizzo di librerie Android. Ha anche fornito un elenco completo che mette in relazione i livelli API con i numeri di versione di Android (ad esempio Android 4.4), i nomi delle versioni di Android (ad esempio Kitkat) e i codici di versione della build di Xamarin.Android.

Collegamenti correlati

• Installazione di Android SDK
• Modifiche agli strumenti dell'interfaccia della riga di comando dell'SDK
• Selezione di compileSdkVersion, minSdkVersion e targetSdkVersion
• Che cos'è il livello API?
• Nomi di codice, tag e numeri di compilazione