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 | Più recente Versione stabile |
Moniker della versione di .NET Framework di destinazione (TFM, Target Framework Moniker) | Implementato Versione standard di .NET |
|---|---|---|---|
| .NET 8 | 8 | net8.0 | 2.1 |
| .NET 7 | 7 | net7.0 | 2.1 |
| .NET 6 | 6 | net6.0 | 2.1 |
| .NET 5 | 5 | net5.0 | 2.1 |
| .NET Standard | 2.1 | netstandard2.1 | N/D |
| .NET Core | 3.1 | netcoreapp3.1 | 2.1 |
| .NET Framework | 4.8.1 | net481 | 2.0 |
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.
| Framework di destinazione | TFM |
|---|---|
| .NET 5+ (e .NET Core) | netcoreapp1.0 netcoreapp1.1 netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1 net5.0* net6.0* net7.0* net8.0* |
| .NET Standard | netstandard1.0 netstandard1.1 netstandard1.2 netstandard1.3 netstandard1.4 netstandard1.5 netstandard1.6 netstandard2.0 netstandard2.1 |
| .NET Framework | net11 net20 net35 net40 net403 net45 net451 net452 net46 net461 net462 net47 net471 net472 net48 net481 |
| Windows Store | netcore [netcore45] netcore45 [win] [win8] netcore451 [win81] |
| .NET Micro Framework | netmf |
| Silverlight | sl4 sl5 |
| Windows Phone | wp [wp7] wp7 wp75 wp8 wp81 wpa81 |
| Piattaforma UWP (Universal Windows Platform) | uap [uap10.0] uap10.0 [win10] [netcore50] |
* 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 TFM net5.0, net6.0, net7.0 e net8.0 includono tecnologie che funzionano su 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 net6.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+.
| TFM | Compatibile con |
|---|---|
| net5.0 | net1..4 (con avviso NU1701) netcoreapp1..3.1 (avviso quando viene fatto riferimento a WinForms o WPF) netstandard1..2.1 |
| net5.0-windows | netcoreapp1..3.1 (più tutto il resto ereditato da net5.0) |
| net6.0 | (Versione successiva di net5.0) |
| net6.0-android | xamarin.android (più tutto il resto ereditato da net6.0) |
| net6.0-ios | xamarin.ios (più tutto il resto ereditato da net6.0) |
| net6.0-maccatalyst | xamarin.ios (più tutto il resto ereditato da net6.0) |
| net6.0-macos | xamarin.mac (più tutto il resto ereditato da net6.0) |
| net6.0-tvos | xamarin.tvos (più tutto il resto ereditato da net6.0) |
| net6.0-windows | (Versione successiva di net5.0-windows) |
| net7.0 | (Versione successiva di net6.0) |
| net7.0-android | (Versione successiva di net6.0-android) |
| net7.0-ios | (Versione successiva di net6.0-ios) |
| net7.0-maccatalyst | (Versione successiva di net6.0-maccatalyst) |
| net7.0-macos | (Versione successiva di net6.0-macos) |
| net7.0-tizen | tizen40 (più tutto il resto ereditato da net7.0) |
| net7.0-tvos | (Versione successiva di net6.0-tvos) |
| net7.0-windows | (Versione successiva di net6.0-windows) |
| net8.0 | (Versione successiva di net7.0) |
| net8.0-android | (Versione successiva di net7.0-android) |
| net8.0-browser | Tutto ereditato da net8.0 |
| net8.0-ios | (Versione successiva di net7.0-ios) |
| net8.0-maccatalyst | (Versione successiva di net7.0-maccatalyst) |
| net8.0-macos | (Versione successiva di net7.0-macos) |
| net8.0-tizen | (Versione successiva di net7.0-tizen) |
| net8.0-tvos | (Versione successiva di net7.0-tvos) |
| net8.0-windows | (Versione successiva di net7.0-windows) |
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
net8.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
net8.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
net8.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 iOS in .NET 6 è 15.0, ovvero net6.0-ios è la sintassi abbreviata per il TFM net6.0-ios15.0 canonico. La versione della piattaforma implicita per un TFM di base più recente potrebbe essere superiore, ad esempio, un TFM futuro net8.0-ios potrebbe eseguire il mapping a net8.0-ios16.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.
| Versione di .NET | Piattaforma | TPV predefinito |
|---|---|---|
| .NET 6 | Android | 31.0 |
| .NET 7 | Android | 33.0 |
| .NET 8 | Android | 34.0 |
| .NET 6 | iOS | 15.0 |
| .NET 7 | iOS | 16.1 |
| .NET 8 | iOS | 17.2 |
| .NET 6 | Mac Catalyst | 15.0 |
| .NET 7 | Mac Catalyst | 16.1 |
| .NET 8 | Mac Catalyst | 17.2 |
| .NET 6 | macOS | 12.0 |
| .NET 7 | macOS | 13.0 |
| .NET 8 | macOS | 14.2 |
| .NET 6 | tvOS | 15.1 |
| .NET 7 | tvOS | 16.1 |
| .NET 8 | tvOS | 17.1 |
| .NET 7 | Tizen | 7.0 |
| .NET 8 | Tizen | 8.0 |
| .NET 6 | Windows | 7.0 |
| .NET 7 | Windows | 7.0 |
| .NET 8 | Windows | 7.0 |
.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 iOS ha aggiunto API iOS 15.1 in un aggiornamento di .NET 6.0.x SDK, è possibile accedervi usando TFM net6.0-ios15.1.
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 8 come destinazione:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net8.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 | Simboli | Simboli aggiuntivi (disponibile in .NET 5+ SDK) |
Simboli della piattaforma (disponibile solo quando si specifica un TFM specifico del sistema operativo) |
|---|---|---|---|
| .NET Framework | NETFRAMEWORK, NET48, NET472, NET471, NET47, NET462, NET461, NET46, NET452, NET451, NET45, NET40, NET35, NET20 |
NET48_OR_GREATER, NET472_OR_GREATER, NET471_OR_GREATER, NET47_OR_GREATER, NET462_OR_GREATER, NET461_OR_GREATER, NET46_OR_GREATER, NET452_OR_GREATER, NET451_OR_GREATER, NET45_OR_GREATER, NET40_OR_GREATER, NET35_OR_GREATER, NET20_OR_GREATER |
|
| .NET Standard | NETSTANDARD, NETSTANDARD2_1, NETSTANDARD2_0, NETSTANDARD1_6, NETSTANDARD1_5, NETSTANDARD1_4, NETSTANDARD1_3, NETSTANDARD1_2, NETSTANDARD1_1, NETSTANDARD1_0 |
NETSTANDARD2_1_OR_GREATER, NETSTANDARD2_0_OR_GREATER, NETSTANDARD1_6_OR_GREATER, NETSTANDARD1_5_OR_GREATER, NETSTANDARD1_4_OR_GREATER, NETSTANDARD1_3_OR_GREATER, NETSTANDARD1_2_OR_GREATER, NETSTANDARD1_1_OR_GREATER, NETSTANDARD1_0_OR_GREATER |
|
| .NET 5+ (e .NET Core) | NET, NET8_0, NET7_0, NET6_0, NET5_0, NETCOREAPP, NETCOREAPP3_1, NETCOREAPP3_0, NETCOREAPP2_2, NETCOREAPP2_1, NETCOREAPP2_0, NETCOREAPP1_1, NETCOREAPP1_0 |
NET8_0_OR_GREATER, NET7_0_OR_GREATER, NET6_0_OR_GREATER, NET5_0_OR_GREATER, NETCOREAPP3_1_OR_GREATER, NETCOREAPP3_0_OR_GREATER, NETCOREAPP2_2_OR_GREATER, NETCOREAPP2_1_OR_GREATER, NETCOREAPP2_0_OR_GREATER, NETCOREAPP1_1_OR_GREATER, NETCOREAPP1_0_OR_GREATER |
ANDROID, BROWSER, IOS, MACCATALYST, MACOS, TVOS, WINDOWS,[OS][version] (ad esempio IOS15_1),[OS][version]_OR_GREATER (ad esempio, IOS15_1_OR_GREATER) |
Nota
- I simboli senza versione vengono definiti indipendentemente dalla versione di destinazione.
- I simboli specifici della versione sono definiti solo per la versione di destinazione.
- I simboli
<framework>_OR_GREATERsono definiti per la versione di destinazione e per tutte le versioni precedenti. Ad esempio, se si ha come destinazione .NET Framework 2.0, vengono definiti i simboli seguenti:NET20,NET20_OR_GREATER,NET11_OR_GREATEReNET10_OR_GREATER. - I simboli
NETSTANDARD<x>_<y>_OR_GREATERsono definiti solo per le destinazioni .NET Standard e non per le destinazioni che implementano .NET Standard, ad esempio .NET Core e .NET Framework. - Questi sono diversi dai moniker del framework di destinazione (TFMs) usati dalla proprietà
TargetFrameworkMSBuild e Da NuGet.
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.
| Moniker framework di destinazione deprecati | Sostituzione |
|---|---|
| aspnet50 aspnetcore50 dnxcore50 dnx dnx45 dnx451 dnx452 |
netcoreapp |
| dotnet dotnet50 dotnet51 dotnet52 dotnet53 dotnet54 dotnet55 dotnet56 |
netstandard |
| netcore50 | uap10.0 |
| win | netcore45 |
| win8 | netcore45 |
| win81 | netcore451 |
| win10 | uap10.0 |
| winrt | netcore45 |
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
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per