Estruturas de destino em projetos no estilo SDK
Ao direcionar uma estrutura em um aplicativo ou biblioteca, você está especificando o conjunto de APIs que deseja disponibilizar para o aplicativo ou biblioteca. Você especifica a estrutura de destino em seu arquivo de projeto usando um moniker de estrutura de destino (TFM).
Um aplicativo ou biblioteca pode direcionar uma versão do .NET Standard. As versões padrão do .NET representam conjuntos padronizados de APIs em todas as implementações do .NET. Por exemplo, uma biblioteca pode direcionar o .NET Standard 1.6 e obter acesso a APIs que funcionam no .NET Core e no .NET Framework usando a mesma base de código.
Um aplicativo ou biblioteca também pode direcionar uma implementação .NET específica para obter acesso a APIs específicas de implementação. Por exemplo, um aplicativo destinado ao Xamarin.iOS (por exemplo, Xamarin.iOS10) tem acesso aos wrappers da API do iOS fornecidos pelo Xamarin para iOS 10, ou um aplicativo destinado à Plataforma Universal do Windows (UWP, uap10.0) tem acesso a APIs que compilam para dispositivos que executam o Windows 10.
Para algumas estruturas de destino, como o .NET Framework, as APIs são definidas pelos assemblies que a estrutura instala em um sistema e podem incluir APIs de estrutura de aplicativo (por exemplo, ASP.NET).
Para estruturas de destino baseadas em pacote (por exemplo, .NET 5+, .NET Core e .NET Standard), as APIs são definidas pelos pacotes NuGet incluídos no aplicativo ou na biblioteca.
Últimas versões
A tabela a seguir define as estruturas de destino mais comuns, como elas são referenciadas e qual versão do .NET Standard elas implementam. Essas versões de estrutura de destino são as versões estáveis mais recentes. As versões de pré-lançamento não são mostradas. Um moniker de estrutura de destino (TFM) é um formato de token padronizado para especificar a estrutura de destino de um aplicativo ou biblioteca .NET.
| Quadro de objetivos | Últimas notícias versão estável |
Apelido da estrutura de destino (TFM) | Implementada Versão padrão do .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/A |
| .NET Core | 3.1 | NetcoreApp3,1 | 2.1 |
| .NET Framework | 4.8.1 | Net481 | 2.0 |
Estruturas de destino suportadas
Uma estrutura de destino é normalmente referenciada por um TFM. A tabela a seguir mostra as estruturas de destino suportadas pelo SDK do .NET e pelo cliente NuGet. Os equivalentes são apresentados entre parênteses. Por exemplo, win81 é um TFM equivalente a netcore451.
| Estrutura de Destino | TFM |
|---|---|
| .NET 5+ (e .NET Core) | NetcoreApp1,0 NetcoreApp1,1 netcoreapp2.0 NetcoreApp2,1 NetcoreApp2,2 NetcoreApp3.0 NetcoreApp3,1 net5.0* net6.0* Líquido7,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 | líquido11 líquido20 net35 net40 Net403 net45 Net451 Net452 net46 net461 Net462 Net47 Net471 Net472 Net48 Net481 |
| Microsoft Store | netcore [netcore45] netcore45 [vitória] [win8] Netcore451 [Win81] |
| .NET Micro Framework | netmf |
| Silverlight | SL4 SL5 |
| Windows Phone | WP [WP7] WP7 WP75 WP8 WP81 WPA81 |
| Plataforma Universal do Windows | UAP [UAP10.0] UAP10.0 [Win10] [Netcore50] |
* .NET 5 e TFMs posteriores incluem algumas variações específicas do sistema operacional. Para obter mais informações, consulte a seção a seguir, TFMs específicos do .NET 5+ OS.
TFMs específicos do .NET 5+ OS
O net5.0, net6.0, net7.0e net8.0 TFMs incluem tecnologias que funcionam em diferentes plataformas. A especificação de um TFM específico do sistema operacional torna as APIs específicas de um sistema operacional disponíveis para seu aplicativo, por exemplo, ligações do Windows Forms ou do iOS. TFMs específicos do sistema operacional também herdam todas as APIs disponíveis para seu TFM base, por exemplo, o net6.0 TFM.
O .NET 5 introduziu o TFM específico do net5.0-windows sistema operacional, que inclui associações específicas do Windows para WinForms, WPF e APIs UWP. O .NET 6 e versões posteriores têm TFMs adicionais específicos do sistema operacional, por exemplo, net6.0-ios.
A tabela a seguir mostra a compatibilidade dos TFMs do .NET 5+.
| TFM | Compatível com |
|---|---|
| net5.0 | líquido1.. 4 (com aviso NU1701) NetcoreApp1.. 3.1 (aviso quando WinForms ou WPF é referenciado) netstandard1.. 2.1 |
| net5.0-janelas | NetcoreApp1.. 3.1 (mais tudo o resto herdado de net5.0) |
| net6,0 | (Versão subsequente do net5.0) |
| net6.0-androide | xamarin.android (mais tudo o resto herdado de net6.0) |
| NET6.0-IOS | xamarin.ios (mais tudo o resto herdado de net6.0) |
| NET6.0-MacCatalyst | xamarin.ios (mais tudo o resto herdado de net6.0) |
| net6.0-macOS | xamarin.mac (mais tudo o resto herdado de net6.0) |
| net6.0-tvos | xamarin.tvos (mais tudo o resto herdado de net6.0) |
| net6.0-janelas | (Versão subsequente do net5.0-windows) |
| net7,0 | (Versão subsequente do net6.0) |
| net7.0-androide | (Versão subsequente do net6.0-android) |
| NET7.0-IOS | (Versão subsequente do net6.0-ios) |
| net7.0-maccatalyst | | (Versão subsequente do net6.0-maccatalyst) |
| net7.0-macOS | (Versão subsequente do net6.0-macos) |
| net7.0-tizen | tizen40 (mais tudo o resto herdado de net7.0) |
| net7.0-tvos | (Versão subsequente do net6.0-tvos) |
| net7.0-janelas | (Versão subsequente do net6.0-windows) |
| net8.0 | (Versão subsequente do net7.0) |
| net8.0-androide | (Versão subsequente do net7.0-android) |
| net8.0-navegador | Tudo herdado de net8.0 |
| NET8.0-IOS | (Versão subsequente do net7.0-ios) |
| NET8.0-MACContutor | (Versão subsequente do net7.0-maccatalyst) |
| net8.0-macOS | (Versão subsequente do net7.0-macos) |
| net8.0-tizen | (Versão subsequente do net7.0-tizen) |
| net8.0-tvos | (Versão subsequente do net7.0-tvos) |
| net8.0-janelas | (Versão subsequente do net7.0-windows) |
Para tornar seu aplicativo portátil em diferentes plataformas, mas ainda ter acesso a APIs específicas do sistema operacional, você pode direcionar vários TFMs específicos do sistema operacional e adicionar protetores de plataforma em torno de chamadas de API específicas do sistema operacional usando #if diretivas de pré-processador. Para obter uma lista dos símbolos disponíveis, consulte Símbolos do pré-processador.
Metas sugeridas
Use estas diretrizes para determinar qual TFM usar em seu aplicativo:
Os aplicativos que são portáteis para várias plataformas devem ter como alvo um TFM base, por exemplo,
net8.0. Isso inclui a maioria das bibliotecas, mas também ASP.NET Core e Entity Framework.As bibliotecas específicas da plataforma devem ter como alvo tipos específicos da plataforma. Por exemplo, os projetos WinForms e WPF devem ter como alvo
net8.0-windowso .Os modelos de aplicativos entre plataformas (Xamarin Forms, ASP.NET Core) e pacotes de ponte (Xamarin Essentials) devem, pelo menos, visar o TFM base, por exemplo,
net8.0mas também podem visar sabores adicionais específicos da plataforma para iluminar mais APIs ou recursos.
Versão do SO em TFMs
Você também pode especificar uma versão opcional do sistema operacional no final de um TFM específico do sistema operacional, por exemplo, net6.0-ios15.0. A versão indica quais APIs estão disponíveis para seu aplicativo ou biblioteca. Ele não controla a versão do sistema operacional que seu aplicativo ou biblioteca suporta em tempo de execução. Ele é usado para selecionar os assemblies de referência que seu projeto compila e para selecionar ativos de pacotes NuGet. Pense nesta versão como a "versão da plataforma" ou "versão da API do sistema operacional" para desambiguá-la da versão do sistema operacional em tempo de execução.
Quando um TFM específico do sistema operacional não especifica a versão da plataforma explicitamente, ele tem um valor implícito que pode ser inferido do TFM base e do nome da plataforma. Por exemplo, o valor de plataforma padrão para iOS no .NET 6 é 15.0, o que significa que net6.0-ios é uma abreviação para o TFM canônico net6.0-ios15.0 . A versão de plataforma implícita para um TFM base mais recente pode ser maior, por exemplo, um TFM futuro net8.0-ios pode ser mapeado para net8.0-ios16.0. O formulário abreviado destina-se ao uso apenas em arquivos de projeto e é expandido para o formulário canônico pelos destinos MSBuild do SDK do .NET antes de ser passado para outras ferramentas, como o NuGet.
A tabela a seguir mostra os valores de plataforma de destino (TPV) padrão para cada versão do .NET.
| Versão .NET | Plataforma | TPV padrão |
|---|---|---|
| .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 | Catalisador Mac | 15.0 |
| .NET 7 | Catalisador Mac | 16.1 |
| .NET 8 | Catalisador Mac | 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 |
O SDK do .NET foi projetado para oferecer suporte a APIs recém-lançadas para uma plataforma individual sem uma nova versão do TFM base. Isso permite que você acesse a funcionalidade específica da plataforma sem esperar por uma versão principal do .NET. Você pode obter acesso a essas APIs recém-lançadas incrementando a versão da plataforma no TFM. Por exemplo, se a plataforma iOS adicionou APIs do iOS 15.1 em uma atualização do SDK do .NET 6.0.x, você poderá acessá-las usando o TFM net6.0-ios15.1.
Precedência
Se seu aplicativo fizer referência a um pacote que tenha vários ativos para TFMs diferentes, os ativos que estão mais próximos em número de versão serão preferidos. Por exemplo, se o seu aplicativo segmenta net6.0-ios e o pacote oferece ativos para net6.0 e net5.0-ios, os net6.0 ativos são usados. Para obter mais informações, consulte Precedências.
Suporta versões mais antigas do SO
Embora um aplicativo ou biblioteca específico da plataforma seja compilado em APIs de uma versão específica desse sistema operacional, você pode torná-lo compatível com versões anteriores do sistema operacional adicionando a SupportedOSPlatformVersion propriedade ao seu arquivo de projeto. A SupportedOSPlatformVersion propriedade indica a versão mínima do sistema operacional necessária para executar seu aplicativo ou biblioteca. Se você não especificar explicitamente essa versão mínima do sistema operacional em tempo de execução no projeto, o padrão será para a versão da plataforma do TFM.
Para que seu aplicativo seja executado corretamente em uma versão mais antiga do sistema operacional, ele não pode chamar APIs que não existem nessa versão do sistema operacional. No entanto, você pode adicionar proteções em torno de chamadas para APIs mais recentes para que elas só sejam chamadas quando executadas em uma versão do sistema operacional que as suporte. Esse padrão permite que você projete seu aplicativo ou biblioteca para suportar a execução em versões mais antigas do sistema operacional, aproveitando a funcionalidade mais recente do sistema operacional ao executar em versões mais recentes do sistema operacional.
O SupportedOSPlatformVersion valor (explícito ou padrão) é usado pelo analisador de compatibilidade de plataforma, que deteta e avisa sobre chamadas não protegidas para APIs mais recentes. Ele é gravado no assembly compilado do projeto como um UnsupportedOSPlatformAttribute atributo assembly, para que o analisador de compatibilidade de plataforma possa detetar chamadas não protegidas para APIs desse assembly de projetos com um valor mais baixo SupportedOSPlatformVersion . Em algumas plataformas, o valor afeta os SupportedOSPlatformVersion processos de empacotamento e compilação de aplicativos específicos da plataforma, que são abordados na documentação dessas plataformas.
Aqui está um trecho de exemplo de um arquivo de projeto que usa as TargetFramework propriedades e SupportedOSPlatformVersion MSBuild para especificar que o aplicativo ou biblioteca tem acesso às APIs do iOS 15.0, mas suporta execução no iOS 13.0 e superior:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net6.0-ios15.0</TargetFramework>
<SupportedOSPlatformVersion>13.0</SupportedOSPlatformVersion>
</PropertyGroup>
...
</Project>
Como especificar uma estrutura de destino
As estruturas de destino são especificadas em um arquivo de projeto. Quando uma única estrutura de destino for especificada, use o elemento TargetFramework. O seguinte arquivo de projeto de aplicativo de console demonstra como direcionar o .NET 8:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net8.0</TargetFramework>
</PropertyGroup>
</Project>
Ao especificar várias estruturas de destino, você pode condicionalmente fazer referência a assemblies para cada estrutura de destino. Em seu código, você pode compilar condicionalmente nesses assemblies usando símbolos de pré-processador com lógica if-then-else .
O projeto de biblioteca a seguir tem como alvo APIs do .NET Standard (netstandard1.4) e do .NET Framework (net40 e net45). Use o elemento plural TargetFrameworks com várias estruturas de destino. Os Condition atributos incluem pacotes específicos de implementação quando a biblioteca é compilada para os dois TFMs do .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>
Em sua biblioteca ou aplicativo, você escreve código condicional usando diretivas de pré-processador para compilar para cada estrutura de destino:
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
}
}
Símbolos do pré-processador
O sistema de compilação está ciente dos símbolos do pré-processador que representam as estruturas de destino mostradas na tabela Versões da estrutura de destino suportadas quando você estiver usando projetos no estilo SDK. Para converter um .NET Standard, .NET Core ou .NET 5+ TFM em um símbolo de pré-processador, substitua pontos e hífenes por um sublinhado e altere letras minúsculas para maiúsculas (por exemplo, o símbolo de netstandard1.4 é NETSTANDARD1_4).
Você pode desativar a geração desses símbolos através da DisableImplicitFrameworkDefines propriedade. Para obter mais informações sobre essa propriedade, consulte DisableImplicitFrameworkDefines.
A lista completa de símbolos de pré-processador para estruturas de destino .NET é:
| Estruturas de destino | Símbolos | Símbolos adicionais (disponível em SDKs do .NET 5+) |
Símbolos da plataforma (disponível apenas quando você especifica um TFM específico do sistema operacional) |
|---|---|---|---|
| .NET Framework | NETFRAMEWORK, NET48, , NET472, , NET462NET452NET47NET46NET35NET461NET451NET45NET40NET471NET20 |
NET48_OR_GREATER, NET472_OR_GREATER, , NET471_OR_GREATER, , NET461_OR_GREATERNET45_OR_GREATERNET46_OR_GREATERNET35_OR_GREATERNET462_OR_GREATERNET452_OR_GREATERNET451_OR_GREATERNET40_OR_GREATERNET47_OR_GREATERNET20_OR_GREATER |
|
| .NET Standard | NETSTANDARD, NETSTANDARD2_1, , NETSTANDARD2_0, NETSTANDARD1_6, NETSTANDARD1_4NETSTANDARD1_5, NETSTANDARD1_3, NETSTANDARD1_2NETSTANDARD1_1,NETSTANDARD1_0 |
NETSTANDARD2_1_OR_GREATER, NETSTANDARD2_0_OR_GREATER, NETSTANDARD1_6_OR_GREATER, , NETSTANDARD1_5_OR_GREATER, NETSTANDARD1_3_OR_GREATERNETSTANDARD1_4_OR_GREATER, NETSTANDARD1_2_OR_GREATER, NETSTANDARD1_1_OR_GREATER,NETSTANDARD1_0_OR_GREATER |
|
| .NET 5+ (e .NET Core) | NET, NET8_0, , NET7_0, , NETCOREAPPNETCOREAPP2_1NETCOREAPP3_1NETCOREAPP1_1NET5_0NETCOREAPP3_0NETCOREAPP2_2NETCOREAPP2_0NET6_0NETCOREAPP1_0 |
NET8_0_OR_GREATER, NET7_0_OR_GREATER, , NET5_0_OR_GREATERNET6_0_OR_GREATER, NETCOREAPP3_1_OR_GREATER, NETCOREAPP3_0_OR_GREATER, NETCOREAPP2_2_OR_GREATER, NETCOREAPP2_1_OR_GREATERNETCOREAPP2_0_OR_GREATERNETCOREAPP1_1_OR_GREATERNETCOREAPP1_0_OR_GREATER |
ANDROID, BROWSER, , IOS, MACOSMACCATALYST, TVOS, WINDOWS,[OS][version] (por exemplo IOS15_1),[OS][version]_OR_GREATER (por exemplo IOS15_1_OR_GREATER) |
Nota
- Os símbolos sem versão são definidos independentemente da versão que você está segmentando.
- Os símbolos específicos da versão são definidos apenas para a versão que você está segmentando.
- Os
<framework>_OR_GREATERsímbolos são definidos para a versão que você está segmentando e todas as versões anteriores. Por exemplo, se você estiver direcionando o .NET Framework 2.0, os seguintes símbolos serão definidos:NET20,NET20_OR_GREATER,NET11_OR_GREATEReNET10_OR_GREATER. - Os
NETSTANDARD<x>_<y>_OR_GREATERsímbolos são definidos apenas para destinos .NET Standard e não para destinos que implementam o .NET Standard, como .NET Core e .NET Framework. - Eles são diferentes dos monikers de estrutura de destino (TFMs) usados pela propriedade MSBuild
TargetFrameworke NuGet.
Estruturas de destino preteridas
As estruturas de destino a seguir foram preteridas. Os pacotes destinados a essas estruturas de destino devem migrar para as substituições indicadas.
| TFM preterido | Substituição |
|---|---|
| ASPNET50 ASPNETCORE50 DNXCORE50 DNX DNX45 DNX451 DNX452 |
NetcoreApp |
| dotnet dotnet50 dotnet51 dotnet52 dotnet53 dotnet54 dotnet55 dotnet56 |
NetStandard |
| Netcore50 | UAP10,0 |
| vitória | Netcore45 |
| Vitória8 | Netcore45 |
| Win81 | Netcore451 |
| Vitória10 | UAP10,0 |
| Winrt | Netcore45 |
Consulte também
- Nomes de estrutura de destino no .NET 5
- Chamar APIs do Tempo de Execução do Windows em aplicativos da área de trabalho
- Desenvolvendo bibliotecas com ferramentas multiplataforma
- .NET Standard
- Controle de versão do .NET Core
- Repositório GitHub do NuGet Tools
- Perfis do Framework no .NET
- Analisador de compatibilidade de plataforma
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários