Framework di destinazione nei progetti in stile SDK

Quando si specifica come destinazione un framework in un'app o in una libreria, si specifica il set di API da rendere disponibile all'app o alla libreria. Specificare il framework di destinazione nel file di progetto usando un moniker del framework di destinazione (TFM).

Un'app o una libreria può specificare come destinazione una versione di .NET Standard. Le versioni di .NET Standard rappresentano set standardizzati di API in tutte le implementazioni di .NET. Una libreria, ad esempio, può specificare come destinazione .NET Standard 1.6 e ottenere l'accesso ad API che possono essere usate in .NET Core e .NET Framework tramite la stessa codebase.

Un'app o una libreria può anche indicare come destinazione un'implementazione specifica di .NET per ottenere l'accesso ad API specifiche dell'implementazione. Ad esempio, un'app che specifica come destinazione Xamarin.iOS (ad esempio Xamarin.iOS10) ha accesso ai wrapper di API iOS forniti da Xamarin per iOS 10 oppure un'app che specifica come destinazione la piattaforma UWP (UWP, uap10.0) ottiene l'accesso alle API che consentono la compilazione per dispositivi che eseguono Windows 10.

Per alcuni framework di destinazione, come .NET Framework, le API vengono definite dagli assembly installati dal framework in un sistema e potrebbero includere API del framework applicazione, ad esempio, ASP.NET.

Per i framework di destinazione basati su pacchetti ,ad esempio .NET 5+, .NET Core e .NET Standard, le API sono definite dai pacchetti NuGet inclusi nell'app o nella libreria.

Versioni più recenti

La tabella seguente definisce i framework di destinazione più comuni, il modo in cui vengono creati i relativi riferimenti e le versioni .NET Standard implementate da tali pacchetti. Queste versioni di framework di destinazione sono le versioni stabili più recenti. Le versioni non definitive non vengono visualizzate. Un moniker framework di destinazione è un formato di token standardizzato per specificare il framework di destinazione di un'app o di una libreria .NET.

Framework di destinazione supportati

Un framework di destinazione viene in genere specificato come riferimento da un moniker framework di destinazione. La tabella seguente mostra i framework di destinazione supportati da .NET SDK e dal client NuGet. Gli equivalenti sono visualizzati tra parentesi quadre. Ad esempio, win81 è un moniker framework di destinazione equivalente a netcore451.

* TFM .NET 5 e versioni successive includono alcune varianti specifiche del sistema operativo. Per altre informazioni, vedere la sezione seguente, TFM specifici del sistema operativo .NET 5+.

TFM (moniker framework di destinazione) specifici del sistema operativo .NET 5+

I net5.0TFM , net8.0net6.0net7.0, , e net.0 includono tecnologie che funzionano in piattaforme diverse. Se si specifica un TFM specifico del sistema operativo, le API specifiche di un sistema operativo sono disponibili per l'app, ad esempio le associazioni Windows Form o iOS. I TFM specifici del sistema operativo ereditano anche tutte le API disponibili per il TFM di base, ad esempio TFM net9.0.

.NET 5 ha introdotto il TFM specifico del sistema operativo net5.0-windows, che include associazioni specifiche di Windows per le API WinForms, WPF e UWP. .NET 6 e versioni successive hanno TFM aggiuntivi specifici del sistema operativo, ad esempio net6.0-ios.

La tabella seguente illustra la compatibilità dei TFM .NET 5+.

Per rendere l'app portabile in piattaforme diverse, ma avere ancora accesso alle API specifiche del sistema operativo, è possibile definire come destinazione più TFM specifiche del sistema operativo e aggiungere protezioni della piattaforma per le chiamate API specifiche del sistema operativo usando le direttive del preprocessore #if. Per un elenco dei simboli disponibili, vedere Simboli del preprocessore.

Destinazioni suggerite

Usare queste linee guida per determinare quale TFM usare nell'app:

• Le app portabili in più piattaforme devono avere come destinazione un TFM di base, ad esempio net9.0. Sono incluse la maggior parte delle librerie, ma anche ASP.NET Core ed Entity Framework.
• Le librerie specifiche della piattaforma devono essere destinate a versioni specifiche della piattaforma. Ad esempio, i progetti WinForms e WPF devono essere destinati a net9.0-windows.
• I modelli di applicazione multipiattaforma (Xamarin Forms, ASP.NET Core) e i bridge pack (Xamarin Essentials) devono avere come destinazione almeno il TFM di base, ad esempio net9.0, ma potrebbero anche essere destinati a versioni aggiuntive specifiche della piattaforma per attivare più API o funzionalità.

Versione del sistema operativo in TFM

È anche possibile specificare una versione facoltativa del sistema operativo alla fine di un TFM specifico del sistema operativo, ad esempio net6.0-ios15.0. La versione indica le API disponibili per l'app o la libreria. Non controlla la versione del sistema operativo supportata dall'app o dalla libreria in fase di esecuzione. Viene usato per selezionare gli assembly di riferimento compilati dal progetto e per selezionare gli asset dai pacchetti NuGet. Si consideri questa versione come "versione della piattaforma" o "versione dell'API del sistema operativo" per evitare ambiguità dalla versione del sistema operativo di runtime.

Quando un TFM specifico del sistema operativo non specifica in modo esplicito la versione della piattaforma, ha un valore implicito che può essere dedotto dal nome della piattaforma e TFM di base. Ad esempio, il valore predefinito della piattaforma per Android in .NET 6 è 31.0, ovvero net6.0-android è abbreviato per il TFM canonico net6.0-android31.0 . La versione della piattaforma implicita per un TFM di base più recente potrebbe essere superiore, ad esempio, un TFM futuro net8.0-android potrebbe eseguire il mapping a net8.0-android34.0. Il modulo abbreviato è destinato solo ai file di progetto ed è espanso nel formato canonico dalle destinazioni MSBuild di .NET SDK prima di essere passato ad altri strumenti, ad esempio NuGet.

La tabella seguente mostra i valori della piattaforma di destinazione predefiniti (TPV) per ogni versione .NET.

.NET SDK è progettato per supportare le API appena rilasciate per una singola piattaforma senza una nuova versione del TFM di base. In questo modo è possibile accedere a funzionalità specifiche della piattaforma senza attendere una versione principale di .NET. È possibile accedere a queste API appena rilasciate incrementando la versione della piattaforma in TFM. Ad esempio, se la piattaforma Android ha aggiunto API di livello API 32 in un aggiornamento di .NET 6.0.x SDK, è possibile accedervi usando TFM net6.0-android32.0.

Precedenza

Se l'app fa riferimento a un pacchetto con più asset per TFM diversi, gli asset più vicini al numero di versione sono preferiti. Ad esempio, se l'app è destinata a net6.0-ios e il pacchetto offre asset per net6.0 e net5.0-ios, vengono usati gli asset net6.0. Per altre informazioni, vedere Precedenze.

Supportare le versioni precedenti del sistema operativo

Anche se un'app o una libreria specifica della piattaforma viene compilata in base alle API di una versione specifica del sistema operativo, è possibile renderla compatibile con le versioni precedenti del sistema operativo aggiungendo la proprietà SupportedOSPlatformVersion al file di progetto. La proprietà SupportedOSPlatformVersion indica la versione minima del sistema operativo necessaria per eseguire l'app o la libreria. Se non si specifica in modo esplicito questa versione minima del sistema operativo in fase di esecuzione nel progetto, per impostazione predefinita viene impostata la versione della piattaforma da TFM.

Perché l'app venga eseguita correttamente in una versione precedente del sistema operativo, non può chiamare API che non esistono in tale versione del sistema operativo. Tuttavia, è possibile aggiungere dei guard intorno alle chiamate alle API più recenti in modo che vengano chiamate solo quando sono in esecuzione in una versione del sistema operativo che li supporta. Questo modello consente di progettare l'app o la libreria per supportare l'esecuzione in versioni precedenti del sistema operativo sfruttando al contempo le funzionalità del sistema operativo più recenti durante l'esecuzione in versioni più recenti del sistema operativo.

Il valore SupportedOSPlatformVersion (esplicito o predefinito) viene usato dall'analizzatore di compatibilità della piattaforma, che rileva e avvisa le chiamate non crittografate alle API più recenti. Viene masterizzato nell'assembly compilato del progetto come attributo dell'assembly UnsupportedOSPlatformAttribute, in modo che l'analizzatore della compatibilità della piattaforma possa rilevare le chiamate non sorvegliate alle API dell'assembly dai progetti con un valore SupportedOSPlatformVersion inferiore. In alcune piattaforme, il valore SupportedOSPlatformVersion influisce sui processi di compilazione e creazione di pacchetti di app specifici della piattaforma, illustrati nella documentazione per tali piattaforme.

Di seguito è riportato un esempio di estratto di un file di progetto che usa le proprietà MSBuild TargetFramework e SupportedOSPlatformVersion per specificare che l'app o la libreria ha accesso alle API iOS 15.0, ma supporta l'esecuzione in iOS 13.0 e versioni successive:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0-ios15.0</TargetFramework>
    <SupportedOSPlatformVersion>13.0</SupportedOSPlatformVersion>
  </PropertyGroup>
  ...

</Project>

Come specificare un framework di destinazione

I framework di destinazione vengono specificati in un file di progetto. Quando viene specificato un singolo framework di destinazione, usare l'elemento TargetFramework. Il file di progetto dell'app console seguente illustra come usare .NET 9 come destinazione:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

</Project>

Quando si specificano più framework di destinazione, è possibile fare riferimento in modo condizionale agli assembly per ogni framework di destinazione. Nel codice è possibile eseguire in modo condizionale la compilazione con tali assembly usando i simboli del preprocessore con logica if-then-else.

Il progetto di libreria seguente è destinato alle API di .NET Standard (netstandard1.4) e .NET Framework (net40 e net45). Usare l'elemento TargetFrameworks plurale con più framework di destinazione. Gli attributi Condition includono pacchetti specifici dell'implementazione quando la libreria viene compilata per i due moniker framework di destinazione di .NET Framework:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFrameworks>netstandard1.4;net40;net45</TargetFrameworks>
  </PropertyGroup>

  <!-- Conditionally obtain references for the .NET Framework 4.0 target -->
  <ItemGroup Condition=" '$(TargetFramework)' == 'net40' ">
    <Reference Include="System.Net" />
  </ItemGroup>

  <!-- Conditionally obtain references for the .NET Framework 4.5 target -->
  <ItemGroup Condition=" '$(TargetFramework)' == 'net45' ">
    <Reference Include="System.Net.Http" />
    <Reference Include="System.Threading.Tasks" />
  </ItemGroup>

</Project>

All'interno della libreria o dell'app si scrive codice condizionale usando le direttive del preprocessore per la compilazione per ogni framework di destinazione:

public class MyClass
{
    static void Main()
    {
#if NET40
        Console.WriteLine("Target framework: .NET Framework 4.0");
#elif NET45
        Console.WriteLine("Target framework: .NET Framework 4.5");
#else
        Console.WriteLine("Target framework: .NET Standard 1.4");
#endif
    }
}

Simboli del preprocessore

Il sistema di compilazione è compatibile con i simboli del preprocessore che rappresentano i framework di destinazione mostrati nella tabella Versioni supportate dei framework di destinazione quando si usano progetti in stile SDK. Per convertire .NET Standard, .NET Core o .NET 5+ TFM in un simbolo di preprocessore, sostituire punti e trattini con un carattere di sottolineatura e modificare le lettere minuscole in maiuscole (ad esempio, il simbolo per netstandard1.4 è NETSTANDARD1_4).

È possibile disabilitare la generazione di questi simboli tramite la proprietà DisableImplicitFrameworkDefines. Per altre informazioni su questa proprietà, vedere DisableImplicitFrameworkDefines.

L'elenco completo di simboli del preprocessore per il framework di destinazione di .NET è:

Framework di destinazione deprecati

I framework di destinazione seguenti sono deprecati. I pacchetti che hanno come destinazione questi framework di destinazione devono essere migrati alle sostituzioni indicate.

Vedi anche

• Nomi dei framework di destinazione in .NET 5
• Chiamare le API di Windows Runtime nelle app desktop
• Sviluppo di librerie con strumenti multipiattaforma
• .NET Standard
• Controllo delle versioni di .NET Core
• NuGet Tools GitHub Repository (Repository di GitHub per strumenti NuGet)
• Framework Profiles in .NET (Profili di framework in .NET)
• Analizzatore della compatibilità della piattaforma