App adattive per la versione: usare le nuove API, mantenendo al tempo stesso la compatibilità con le versioni precedentiVersion adaptive apps: Use new APIs while maintaining compatibility with previous versions

In ogni versione di Windows 10 SDK vengono aggiunte nuove funzionalità interessanti che vorrai usare.Each release of the Windows 10 SDK adds exciting new functionality that you'll want to take advantage of. Non tutti i clienti, tuttavia, aggiorneranno i loro dispositivi alla versione più recente di Windows 10 nello stesso momento e quindi vorrai assicurarti che la tua app funzioni nella più ampia gamma possibile di dispositivi.However, not all your customers will update their devices to the latest version of Windows 10 at the same time, and you want to make sure your app works on the broadest possible range of devices. In questo articolo illustreremo come progettare l'app in modo che possa essere eseguita nelle versioni precedenti di Windows 10, ma anche avvalersi di nuove funzionalità quando viene usata in un dispositivo in cui è installato l'aggiornamento più recente.Here, we show you how to design your app so that it runs on earlier versions of Windows 10, but also takes advantage of new features whenever your app runs on a device with the latest update installed.

Sono 3 i passaggi necessari per assicurarti che l'app supporti la più ampia gamma di dispositivi Windows 10.There are 3 steps to take to make sure your app supports the broadest range of Windows 10 devices.

  • Prima di tutto, configura il tuo progetto di Visual Studio per l'uso delle API più recenti.First, configure your Visual Studio project to target the latest APIs. Questo aspetto ha effetti sulla compilazione dell'app.This affects what happens when you compile your app.
  • In secondo luogo, esegui dei controlli di runtime per assicurarti di chiamare solo le API presenti nel dispositivo in cui viene eseguita la tua app.Second, perform runtime checks to ensure that you only call APIs that are present on the device your app is running on.
  • Infine, testa l'app nella versione minima e nella versione di destinazione di Windows 10.Third, test your app on the Minimum Version and the Target Version of Windows 10.

Configurare il progetto di Visual StudioConfigure your Visual Studio project

Il primo passaggio per il supporto di più versioni di Windows 10 consiste nello specificare le versioni Destinazione e Minima del sistema operativo e dell'SDK supportate nel progetto di Visual Studio.The first step in supporting multiple Windows 10 versions is to specify the Target and Minimum supported OS/SDK versions in your Visual Studio project.

  • Destinazione: versione dell'SDK di riferimento per la compilazione del codice dell'app e l'esecuzione di tutti gli strumenti in Visual Studio.Target: The SDK version that Visual Studio compiles your app code and run all tools against. Tutte le API e le risorse in questa versione dell'SDK sono disponibili nel codice dell'app in fase di compilazione.All APIs and resources in this SDK version are available in your app code at compile time.
  • Minimo: versione dell'SDK che supporta la versione minima del sistema operativo su cui può essere eseguita la tua app (e in cui verrà distribuita dallo Store) e la versione di riferimento per la compilazione del codice di markup dell'app in Visual Studio.Minimum: The SDK version that supports the earliest OS version that your app can run on (and will be deployed to by the store) and the version that Visual Studio compiles your app markup code against.

Durante il runtime, la tua app sarà eseguita nella versione del sistema operativo per cui è distribuita, quindi genererà eccezioni se usi risorse o chiami API non disponibili in tale versione.During runtime your app will run against the OS version that it is deployed to, so your app will throw exceptions if you use resources or call APIs that are not available in that version. Ti mostreremo come usare i controlli di runtime per chiamare le API corrette più avanti in questo articolo.We show you how to use runtime checks to call the correct APIs later in this article.

Le impostazioni Destinazione e Minima specificano le estremità dell'intervallo di versioni del sistema operativo e dell'SDK.The Target and Minimum settings specify the ends of a range of OS/SDK versions. Se testi la tua app nella versione minima, tuttavia, puoi essere certo che verrà eseguita in qualsiasi versione compresa tra quella minima e quella di destinazione.However, if you test your app on the minimum version, you can be sure it will run on any versions between the Minimum and Target.

Suggerimento

Visual Studio non genera avvisi in merito alla compatibilità delle API.Visual Studio does not warn you about API compatibility. È tua responsabilità eseguire test e assicurarti che le prestazioni della tua app siano adeguate in tute le versioni del sistema operativo nell'intervallo da Minima a Destinazione, incluse.It is your responsibility to test and ensure that your app performs as expected on all OS versions between and including the Minimum and Target.

Quando crei un nuovo progetto in Visual Studio 2015 Update 2 o versioni successive, ti viene richiesto di impostare le versioni di destinazione e minima supportate dall'app.When you create a new project in Visual Studio 2015, Update 2 or later, you are prompted to set the Target and Minimum versions that your app supports. Per impostazione predefinita, la versione di destinazione è la versione più recente dell'SDK installata e la versione minima è quella meno recente.By default, the Target Version is the highest installed SDK version, and the Minimum Version is the lowest installed SDK version. Puoi scegliere la versione di destinazione e minima solo tra le versioni dell'SDK installate nel tuo computer.You can choose Target and Minimum only from SDK versions that are installed on your machine.

Impostare la versione di destinazione dell'SDK in Visual Studio

In genere consigliamo di non cambiare le impostazioni predefinite.We typically recommend that you leave the defaults. Se hai installato una versione di anteprima dell'SDK e stai scrivendo codice di produzione, tuttavia, devi cambiare l'impostazione della versione di destinazione da Preview SDK all'ultima versione ufficiale dell'SDK.However, if you have a Preview version of the SDK installed and you are writing production code, you should change the Target Version from the Preview SDK to the latest official SDK version.

Per modificare la versione minima e di destinazione per un progetto già creato in Visual Studio, vai a Progetto -> Proprietà -> scheda Applicazione -> Destinazione.To change the Minimum and Target version for a project that has already been created in Visual Studio, go to Project -> Properties -> Application tab -> Targeting.

Modificare l'SDK di destinazione in Visual Studio

Come riferimento, nella tabella seguente vengono illustrati i numeri di build di ogni SDK.For reference, the following table shows the build numbers for each SDK.

Nome descrittivoFriendly name VersionVersion Build sistema operativo/SDKOS/SDK build
RTMRTM 15071507 1024010240
Aggiornamento di novembreNovember Update 15111511 1058610586
Aggiornamento dell'anniversarioAnniversary Update 16071607 1439314393
Creators UpdateCreators Update 17031703 1506315063
Fall Creators UpdateFall Creators Update 17091709 1629916299
Aggiornamento di aprile 2018April 2018 Update 18031803 1713417134
Aggiornamento di ottobre 2018October 2018 Update 18091809 1776317763
Aggiornamento di maggio 2019May 2019 Update 19031903 1836218362

Puoi scaricare qualsiasi versione rilasciata dell'SDK da Archivio per Windows SDK ed emulatori.You can download any released version of the SDK from the Windows SDK and emulator archive. Puoi scaricare la versione più recente di Windows Insider Preview SDK dalla sezione per gli sviluppatori del sito Windows Insider.You can download the latest Windows Insider Preview SDK from the developer section of the Windows Insider site.

Per altre informazioni sugli aggiornamenti di Windows 10, vedi Informazioni sulla versione di Windows 10.For more info about Windows 10 updates, see Windows 10 release information. Per informazioni importanti sul ciclo di vita del supporto di Windows 10, vedi la scheda informativa sul ciclo di vita di Windows.For important information about the Windows 10 support lifecycle, see the Windows lifecycle fact sheet.

Eseguire i controlli delle APIPerform API checks

La chiave per le app adattive per la versione è la combinazione dei contratti API e della classe ApiInformation.The key to version adaptive apps is the combination of API contracts and the ApiInformation class. Questa classe consente di rilevare la presenza di un membro, di un tipo o di un contratto API specificato, per poter effettuare chiamate API in modo sicuro in un'ampia gamma di dispositivi e di versioni del sistema operativo.This class lets you detect whether a specified API contract, type, or member is present so that you can safely make API calls across a variety of devices and OS versions.

Contratti APIAPI contracts

Il set di API all'interno di una famiglia di dispositivi è organizzato in suddivisioni note come contratti API.The set of APIs within a device family is broken down into subdivisions known as API contracts. Puoi verificare la presenza di un contratto API usando il metodo ApiInformation.IsApiContractPresent.You can use the ApiInformation.IsApiContractPresent method to test for the presence of an API contract. Ciò è utile se vuoi verificare la presenza di un numero elevato di API tutte appartenenti alla stessa versione di un contratto API.This is useful if you want to test for the presence of many APIs that all exist in the same version of an API contract.

    bool isScannerDeviceContract_1_Present =
        Windows.Foundation.Metadata.ApiInformation.IsApiContractPresent
            ("Windows.Devices.Scanners.ScannerDeviceContract", 1);

Che cos'è un contratto API?What’s an API contract? In pratica, un contratto API rappresenta una funzionalità, un set di API correlate che insieme offrono alcune funzionalità particolari.Essentially, an API contract represents a feature – a set of related APIs that together deliver some particular functionality. Un contratto API ipotetico potrebbe rappresentare un set di API contenente due classi, cinque interfacce, una struttura, due enumerazioni e così via.A hypothetical API contract could represent a set of APIs containing two classes, five interfaces, one structure, two enums, and so on.

I tipi correlati logicamente vengono raggruppati in un contratto API e a partire da Windows 10, ogni API di Windows Runtime è un membro di un contratto API.Logically related types are grouped into an API contract, and starting with Windows 10, every Windows Runtime API is a member of some API contract. Con i contratti API, verifichi la disponibilità nel dispositivo di una funzionalità specifica o di un'API, verifichi in modo efficiente le funzionalità di un dispositivo anziché un dispositivo o un sistema operativo specifici.With API Contracts, you are checking for the availability of a specific feature or API on the device, effectively checking a device’s capabilities rather than checking for a specific device or OS. Per implementare ogni API in un determinato contratto API, è necessaria una piattaforma che implementi qualsiasi API in un contratto API.A platform that implements any API in an API contract is required to implement every API in that API contract. Ciò significa che puoi verificare se il sistema operativo in esecuzione supporta un contratto API specifico e, in caso affermativo, puoi chiamare una delle API in tale contratto API senza controllarle una per volta.This means you can test whether the running OS supports a particular API contract and, if it does, call any of the APIs in that API contract without checking each one individually.

Il contratto API più grande e usato con maggiore frequenza è Windows.Foundation.UniversalApiContract.The largest and most commonly used API contract is the Windows.Foundation.UniversalApiContract. Contiene la maggior parte delle API della piattaforma UWP (Universal Windows Platform).It contains the majority of the APIs in the Universal Windows Platform. La documentazione Contratti API e SDK di estensione della famiglia di dispositivi descrive la varietà di contratti API disponibili.The Device family extension SDKs and API contracts documentation describes the variety of API contracts available. Si noterà che la maggior parte di tali contratti rappresenta un set di API correlate alle funzionalità.You’ll see that most of them represent a set of functionally related APIs.

Nota

Se si dispone di una versione di anteprima di Windows Software Development Kit (Windows SDK) non ancora documentata, è possibile trovare informazioni sul supporto dei contratti API anche nel file Platform.xml, che si trova nella cartella di installazione dell'SDK in "(Programmi (x86))\Windows Kits\10\Platforms<platform><SDK version>\Platform.xml".If you have a preview Windows Software Development Kit (SDK) installed that isn’t documented yet, you can also find information about API contract support in the ‘Platform.xml’ file located in the SDK installation folder at ‘(Program Files (x86))\Windows Kits\10\Platforms<platform><SDK version>\Platform.xml’.

Codice adattivo per la versione e XAML condizionaleVersion adaptive code and conditional XAML

Per testare la presenza dell'API che vuoi chiamare, in tutte le versioni di Windows 10 puoi usare la classe ApiInformation in una condizione del codice.In all versions of Windows 10, you can use the ApiInformation class in a condition in your code to test for the presence of the API you want to call. Nel codice adattivo, puoi usare diversi metodi della classe, ad esempio IsTypePresent, IsEventPresent, IsMethodPresent e IsPropertyPresent, per verificare la presenza delle API al livello di granularità necessario.In your adaptive code, you can use various methods of the class, such as IsTypePresent, IsEventPresent, IsMethodPresent, and IsPropertyPresent, to test for APIs at the granularity you need.

Per altre informazioni ed esempi, vedi Codice adattivo per la versione .For more info and examples, see Version adaptive code.

Se la versione minima delle app è la build 15063 (Creators Update) o versioni successive, puoi usare XAML condizionale per impostare le proprietà e creare istanze degli oggetti nel markup senza dover usare code-behind.If your apps Minimum Version is build 15063 (Creators Update) or later, you can use conditional XAML to set properties and instantiate objects in markup without needing to use code behind. XAML condizionale consente di usare il metodo ApiInformation.IsApiContractPresent nel markup.Conditional XAML provides a way to use the ApiInformation.IsApiContractPresent method in markup.

Per altre informazioni ed esempi, vedi XAML condizionale .For more info and examples, see Conditional XAML.

Testare l'app adattiva per la versioneTest your version adaptive app

Quando usi il codice adattivo per la versione o XAML condizionale per scrivere un'app adattiva per la versione, devi testarla in un dispositivo che esegue la versione minima di Windows 10 e in un dispositivo che esegue la versione di destinazione.When you use version adaptive code or conditional XAML to write a version adaptive app, you need to test it on a device running the Minimum Version and on a device running the Target Version of Windows 10.

Non puoi testare tutti i percorsi del codice condizionale in un singolo dispositivo.You can't test all conditional code paths on a single device. Per garantire che vengano testati tutti i percorsi del codice, devi distribuire e testare l'app in un dispositivo remoto (o in una macchina virtuale) che esegue la versione minima supportata del sistema operativo.To ensure that all code paths are tested, you need to deploy and test your app on a remote device (or virtual machine) running the minimum supported OS version. Per altre informazioni sul debug remoto, vedi Distribuzione e debug di app UWP.For more info about remote debugging, see Deploying and debugging UWP apps.