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. Specifica il framework di destinazione nel tuo file di progetto usando un indicatore 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 destinata alla piattaforma UWP (Universal Windows Platform) uap10.0ha accesso alle API compilate per i 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 del framework di destinazione (TFM) è 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 è generalmente indicato con un TFM. 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 TFM (Target Framework Moniker) 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 specifici del sistema operativo per .NET 5+

I net5.0TFM , net6.0net7.0net8.0, , e net9.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 (ad esempio, ASP.NET Core) devono avere come destinazione almeno il TFM di base, net9.0ad esempio , ma potrebbero anche essere destinati a versioni specifiche della piattaforma aggiuntive per attivare più API o funzionalità.

Versione del sistema operativo nei 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.

.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.

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, la versione della piattaforma predefinita per Android in .NET 9 è 35.0, ovvero net9.0-android la sintassi abbreviata per il TFM canonico netp.0-android35.0 . Il modulo abbreviato è destinato esclusivamente ai file di progetto ed è convertito nel formato canonico dai target di MSBuild dell'SDK di .NET prima di essere passato ad altri strumenti, come NuGet.

La tabella seguente illustra la versione TPV (Target Platform Version) predefinita per ogni versione .NET. Se si vogliono usare le associazioni più recenti, usare il valore predefinito , ovvero non specificare una versione del sistema operativo.

A partire da .NET 9, quando le versioni del servizio introducono il supporto per un TPV successivo (che avrà sempre lo stesso numero di versione principale di quando è stata rilasciata inizialmente la versione .NET), il TPV supportato meno recente per tale versione di .NET rimarrà supportato. Ad esempio, per .NET 9, la versione iOS supportata meno recente, 18.0, rimarrà supportata, anche quando una versione del servizio aggiunge il supporto per la versione più recente di iOS 18.x. Se è necessario usare le associazioni più antiche per una versione di .NET, utilizzare un numero di versione specifico del sistema operativo nel TFM.

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 inserito nell'assembly del progetto compilato come attributo dell'assembly UnsupportedOSPlatformAttribute, in modo che l'analizzatore della compatibilità della piattaforma possa rilevare chiamate non protette alle API dell'assembly da 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 plurale TargetFrameworks con multipli framework di destinazione. Gli attributi Condition includono pacchetti specifici dell'implementazione quando la libreria viene compilata per i due 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 seguenti framework di destinazione sono obsoleti. I pacchetti destinati a questi framework target dovrebbero migrare verso le sostituzioni indicate.

Vedi anche

• Nomi dei framework di destinazione in .NET 5
• .NET Standard
• Controllo delle versioni di .NET
• Informazioni sulla versione di Windows 11