Versione del runtime dell'applicazione, sysroot e API beta

Una versione di Azure Sphere SDK potrebbe contenere sia API di produzione che API beta. Le API di produzione sono considerate stabili a lungo termine (LTS), mentre le API beta sono ancora in fase di sviluppo e possono cambiare in una versione successiva o essere rimosse. Nella maggior parte dei casi, le nuove API sono contrassegnate come beta nella prima versione e passano in produzione in una versione successiva. Le API beta consentono di accedere in anteprima alle nuove funzionalità e quindi di creare prototipi e fornire commenti e suggerimenti prima che vengano finalizzate. Le applicazioni che usano le API beta richiederanno solitamente modifiche dopo la pubblicazione di versioni future del sistema operativo e dell'SDK di Azure Sphere per continuare a funzionare correttamente.

Le funzionalità beta sono contrassegnate come funzionalità BETA nella documentazione. Ogni applicazione di alto livello di Azure Sphere specifica se è destinata solo alle API di produzione o sia alle API di produzione che alle API beta.

Set di API di destinazione, versione di runtime dell'applicazione e sysroot

Il set di API di destinazione indica quali API usa l'applicazione, ovvero solo le API di produzione oppure le API di produzione e beta. Il valore del set di API di destinazione è un intero che rappresenta la versione di runtime dell'applicazione oppure la versione di runtime dell'applicazione più una stringa che identifica la versione API beta. Il valore numerico da solo specifica esclusivamente le API di produzione nella versione di runtime dell'applicazione, mentre "valore+BetaNumero" specifica le API di produzione e beta in una particolare release. Ad esempio, ARV 8 indica la versione 21.01 e "8+Beta2101" specifica le API di produzione e beta nella versione 20.01. Nelle versioni future verranno aggiunte altre versioni del runtime dell'applicazione.

Azure Sphere SDK implementa più set di API tramite sysroot. Un sysroot specifica le librerie, i file di intestazione e gli strumenti usati per compilare e collegare un'applicazione destinata a uno specifico set di API. I sysroot vengono installati nella sottocartella sysroots della directory Microsoft Azure Sphere SDK.

Impostare o aggiornare il set di API di destinazione per un'app di alto livello

Se l'applicazione è basata su un esempio di Azure Sphere, il set di API di destinazione per impostazione predefinita è quello usato dall'esempio. Se l'esempio usa solo le API di produzione, il set di API di destinazione verrà impostato sul valore ARV corrente. Se l'esempio usa sia le API di produzione che beta per la versione corrente, il set di API di destinazione sarà "valore+NumeroBeta" per includere le API beta.

Se l'applicazione non è basata su un esempio, sarà necessario impostare il set di API di destinazione nelle istruzioni di compilazione per l'app.

Se è già stata creata un'applicazione, potrebbe essere necessario cambiare il set di API di destinazione se l'app viene ricompilata per una nuova versione del sistema operativo. Se l'app usa API beta, è necessario aggiornarla quando cambiano le opzioni del set di API di destinazione, cosa che si verifica in genere a ogni rilascio di funzionalità. Le API beta possono passare direttamente dallo stato beta a quello di produzione, determinando la creazione di una nuova versione di runtime dell'applicazione, oppure possono essere modificate e mantenute nello stato beta. Se si aggiorna un'applicazione che usa le API Beta per impostare come destinazione un set di API di destinazione più recente, è possibile che si verifichino errori o avvisi relativi alle API rimosse o ritirate.

Ogni volta che si cambia il set di API di destinazione, è necessario eliminare il file CMakeCache.txt prima di compilare l'applicazione. Questo file è archiviato nella directory out\ARM-Debug o out\ARM-Release per il progetto.

Specificare il set di API di destinazione

Impostare il set di API di destinazione in CMakePresets.json:

• Usare "AZURE_SPHERE_TARGET_API_SET" per configurare il set di API di destinazione. Ad esempio:

  "AZURE_SPHERE_TARGET_API_SET": "5" oppure "AZURE_SPHERE_TARGET_API_SET": "5+Beta2004"

Se l'app è destinata al set di API più recente, è sufficiente impostare questa variabile su "latest-lts", se non lo è già. Se l'app è destinata al set di API Beta più recente, è sufficiente impostare questa variabile su "latest-beta", se non lo è già. Tuttavia, se l'app è destinata a un set di API meno recente, è necessario impostare questa variabile in modo che corrisponda al valore specifico che usa.

• Per specificare la variabile esterna AZURE_SPHERE_TARGET_API_SET in un progetto di Visual Studio, impostare quanto segue nel file CMakeSettings.json, all'interno delle configurazioni ARM-Debug e ARM-Release:

  "variables": [
    {
      "name": "AZURE_SPHERE_TARGET_API_SET",
      "value": "latest-beta"
    }
  ]
  

• Per specificare la variabile esterna AZURE_SPHERE_TARGET_API_SET in un progetto di Visual Studio Code, impostare quanto segue nel file .vscode/settings.json:

      "cmake.configureSettings": {
        "AZURE_SPHERE_TARGET_API_SET": "latest-lts"
    },
  

• Per specificare la variabile esterna AZURE_SPHERE_TARGET_API_SET sulla riga di comando, includere il parametro quando si richiama CMake:

  -DAZURE_SPHERE_TARGET_API_SET="latest-lts"

  Sostituire "latest-lts" con "latest-beta" o con un valore specifico meno recente, ad esempio "4" o "5+Beta2004" come descritto prima.

Compatibilità con i set di API di destinazione e il sistema operativo

La compatibilità di un'applicazione con il sistema operativo di Azure Sphere dipende dal set di API di destinazione con cui è stata compilata l'applicazione e dalla versione di runtime dell'applicazione più recente supportata dal sistema operativo. Un'applicazione o un sistema operativo di livello inferiore usa una versione di runtime dell'applicazione precedente (con un numero inferiore), mentre un'applicazione o un sistema operativo di livello superiore usa una versione di runtime dell'applicazione più recente (con un numero superiore). Le sezioni seguenti descrivono cosa accade in ogni scenario possibile.

Applicazioni di livello inferiore con sistema operativo di livello superiore

Le immagini di livello inferiore esistenti che usano solo API di produzione sono supportate nelle versioni di livello superiore del sistema operativo Azure Sphere. Ad esempio, un'applicazione compilata con il set di API di destinazione 1 viene eseguita correttamente in un sistema operativo Azure Sphere che supporta la versione di runtime dell'applicazione 2. Di conseguenza, le applicazioni distribuite esistenti continueranno a funzionare correttamente dopo gli aggiornamenti del sistema operativo. È possibile trasferire localmente o distribuire sul cloud immagini di livello inferiore, solo di produzione, a un sistema operativo di livello superiore senza errori.

Le immagini di livello inferiore che usano API beta non sono supportate e potrebbero non funzionare per progettazione nelle versioni di livello superiore del sistema operativo Azure Sphere. Ad esempio, un'applicazione compilata con il set di API di destinazione 1+Beta1902 potrebbe non essere eseguita correttamente in un sistema operativo Azure Sphere con la versione di runtime dell'applicazione 2. Tenta di trasferire localmente un'immagine di questo tipo restituisce un errore a meno che non si usi il flag nel --force comando azsphere device sideload deploy. Analogamente, il comando azsphere image add richiede il --force flag per caricare tale immagine. I controlli correnti non impediscono di distribuire un'immagine di livello inferiore caricata in precedenza che usa le API beta insieme a un sistema operativo di livello superiore che non supporta tali API beta.

Applicazioni di livello superiore con sistema operativo di livello inferiore

È impossibile distribuire applicazioni di livello superiore in versioni di livello inferiore del sistema operativo Azure Sphere, indipendentemente dal fatto che usino o meno le API beta. Il tentativo di trasferire localmente un'immagine di questo tipo avrà esito negativo con un errore. I tentativi di distribuzione in modalità over-the-air non sono attualmente possibili, in quanto l'SDK e il sistema operativo di livello superiore vengono rilasciati contemporaneamente.