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ò mirare a una versione di .NET Standard. .NET versioni standard rappresentano set standardizzati di API in tutte le implementazioni di .NET. Ad esempio, una libreria può avere come destinazione .NET Standard 1.6 e ottenere l'accesso alle API che funzionano in .NET Core e .NET Framework usando la stessa codebase.

Un'app o una libreria può anche avere come destinazione un'implementazione di .NET specifica per ottenere l'accesso alle API specifiche dell'implementazione. Ad esempio, un'app destinata a piattaforma UWP (Universal Windows Platform) (UWP, uap10.0) ha accesso alle API compilate per i dispositivi che eseguono Windows 10.

Per alcuni framework di destinazione, ad esempio .NET Framework, le API sono definite dagli assembly installati dal framework in un sistema e possono includere API del framework dell'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 viene fatto riferimento e quale versione di .NET Standard implementano. 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 illustra 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.

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

TFM specifici del sistema operativo

I net8.0TFM , net9.0e net10.0 includono tecnologie che funzionano su piattaforme diverse. Se si specifica un TFM specifico al sistema operativo (OS), le API specifiche di un sistema operativo sono disponibili per l'app, ad esempio Windows Forms o binding iOS. I TFM specifici del sistema operativo ereditano anche tutte le API disponibili per il TFM di base, ad esempio TFM net10.0.

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

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 net10.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 macchine virtuali Windows devono essere destinati a net10.0-windows.
• I modelli di applicazione multipiattaforma (ad esempio, ASP.NET Core) devono avere come destinazione almeno il TFM di base, ad esempio net10.0, ma potrebbero anche puntare ad altre versioni specifiche della piattaforma per accendere 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 net8.0-ios17.2. 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 la "versione della piattaforma" o "versione dell'API del sistema operativo" per disambiguarla dalla versione del sistema operativo di runtime.

L'SDK di .NET è 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 34 in un aggiornamento dell'SDK di .NET 8.0.x, è possibile accedervi usando tfm net8.0-android34.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 è , il che significa che è abbreviazione per il TFM canonico. Il modulo abbreviato è destinato solo ai file di progetto e viene espanso al formato canonico dai target MSBuild dell'SDK .NET prima di essere passato ad altri strumenti, ad esempio NuGet.

La tabella seguente illustra la versione predefinita della piattaforma di destinazione (TPV) per Android e iOS per ogni release di .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 major numero di versione come quando la versione .NET è stata rilasciata inizialmente, il TPV supportato meno recente per tale versione .NET rimarrà supportato. Ad esempio, per .NET 9, la versione iOS supportata più 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 tuo 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 net9.0-ios e il pacchetto offre asset per net9.0 e net8.0-ios, vengono usati gli asset net9.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 di runtime 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.

L'esempio seguente è un estratto di un file di progetto che usa le TargetFramework proprietà e SupportedOSPlatformVersion MSBuild 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 impostare come destinazione .NET 10:

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

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

</Project>

Quando si specificano più framework di destinazione, è possibile fare riferimento condizionalmente 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 TFM 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
    }
}

I valori targetFramework sono alias

Il valore della proprietà TargetFramework (ad esempio, net10.0) è un nome descrittivo, ovvero un alias, che .NET SDK converte in proprietà di moniker canoniche. In particolare, l'SDK imposta le proprietà seguenti dal valore TargetFramework:

• TargetFrameworkMoniker (ad esempio, .NETCoreApp,Version=v10.0)
• TargetFrameworkIdentifier (ad esempio, .NETCoreApp)
• TargetFrameworkVersion (ad esempio, v10.0)
• TargetPlatformMoniker, TargetPlatformIdentifiere TargetPlatformVersion (quando la destinazione è una piattaforma specifica)

NuGet e .NET SDK usano queste proprietà del moniker, non la stringa TargetFramework, per i controlli di compatibilità dei pacchetti e la logica di compilazione. Questa traduzione avviene già per i TFM specifici del sistema operativo. Ad esempio, net10.0-windows viene convertito in TargetFrameworkMoniker = .NETCoreApp,Version=v10.0 e TargetPlatformMoniker = Windows,Version=7.0.

Poiché l'alias è solo un nome, il TargetFramework valore può essere qualsiasi stringa alfanumerica, purché le proprietà del moniker corrispondenti siano impostate correttamente. Il file di progetto seguente usa un alias personalizzato denominato banana e imposta in modo esplicito le proprietà del moniker in modo che il progetto compili e ripristini per .NET 10.0:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>banana</TargetFramework>
  </PropertyGroup>

  <PropertyGroup Condition=" '$(TargetFramework)' == 'banana' ">
    <TargetFrameworkIdentifier>.NETCoreApp</TargetFrameworkIdentifier>
    <TargetFrameworkVersion>v10.0</TargetFrameworkVersion>
    <TargetFrameworkMoniker>.NETCoreApp,Version=v10.0</TargetFrameworkMoniker>
  </PropertyGroup>
</Project>

Per altre informazioni su queste proprietà, vedere le informazioni di riferimento sulla proprietà MSBuild TargetFramework .

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 un .NET Standard, .NET Core o .NET 5+ TFM in un simbolo di preprocessore, sostituire punti e trattini con un carattere di sottolineatura e modificare lettere minuscole in maiuscolo (ad esempio, il simbolo per netstandard2.0 è NETSTANDARD2_0).

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

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

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
• Versionamento .NET
• Informazioni sulla versione di Windows 11