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

Uma aplicação ou biblioteca pode direcionar uma versão de .NET Standard. As versões padrão .NET representam conjuntos padronizados de APIs em todas as implementações .NET. Por exemplo, uma biblioteca pode direcionar o .NET Standard 1.6 e aceder a APIs que funcionam através do .NET Core e do .NET Framework usando a mesma base de código.

Uma aplicação ou biblioteca pode também direcionar uma implementação específica de .NET para aceder a APIs específicas da implementação. Por exemplo, uma aplicação que se destina à Plataforma Universal do Windows (UWP, uap10.0) tem acesso a APIs que são compiladas para dispositivos que executam o Windows 10.

Para alguns frameworks-alvo, como o .NET Framework, as APIs são definidas pelos assemblies que o framework instala num sistema e podem incluir APIs de framework de aplicação (por exemplo, ASP.NET).

Para frameworks de destino baseados em pacotes (por exemplo, .NET 5+, .NET Core e .NET Standard), as APIs são definidas pelos pacotes NuGet incluídos na aplicação ou biblioteca.

Últimas versões

A tabela seguinte define os frameworks-alvo mais comuns, como são referenciados e qual a versão do .NET Standard 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 nome de marca do framework de destino (TFM) é um formato de token padronizado para especificar o framework de destino de uma aplicação .NET.

Estruturas de destino suportadas

Uma estrutura de destino é normalmente referenciada por um TFM. A tabela seguinte mostra os frameworks-alvo suportados pelo SDK .NET e pelo cliente NuGet. Os equivalentes são apresentados entre parênteses. Por exemplo, win81 é um TFM equivalente a netcore451.

* Os TFMs .NET 5 e posteriores incluem algumas variações específicas do sistema operativo. Para obter mais informações, consulte a seção a seguir, TFMs específicos do sistema operacional.

TFMs específicos do SO

O net8.0, net9.0, e net10.0 TFMs incluem tecnologias que funcionam em diferentes plataformas. Especificar um TFM específico do sistema operativo disponibiliza APIs que são específicas para um sistema operativo à sua aplicação, por exemplo, bindings para Windows Forms ou iOS. TFMs específicos do sistema operativo também herdam todas as APIs disponíveis para o seu TFM base, por exemplo, o net10.0 TFM.

A tabela seguinte mostra a compatibilidade dos TFMs .NET 8+.

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, net10.0. Isto inclui a maioria das bibliotecas, mas também o ASP.NET Core e o Entity Framework.
• As bibliotecas específicas da plataforma devem ter como alvo tipos específicos da plataforma. Por exemplo, projetos WinForms e WPF devem ter como objetivo net10.0-windows.
• Modelos de aplicação multiplataforma (por exemplo, ASP.NET Core) deveriam pelo menos ter como alvo o TFM base, por exemplo, net10.0, mas também poderiam visar versões específicas da plataforma para ativarem mais APIs ou funcionalidades.

Versão do SO em TFMs

Você também pode especificar uma versão opcional do sistema operativo no final de um TFM específico desse sistema, por exemplo, net8.0-ios17.2. A versão indica quais APIs estão disponíveis para seu aplicativo ou biblioteca. Não controla a versão do sistema operativo que a sua aplicação ou biblioteca suporta em tempo de execução. É usado para selecionar os assemblies de referência que o seu projeto compila contra e para selecionar recursos de pacotes do NuGet. Pense nesta versão como a "versão da plataforma" ou "versão da API do SO" para a desambiguar da versão do sistema operativo em tempo de execução.

O SDK .NET foi concebido para suportar APIs recém-lançadas para uma plataforma individual sem uma nova versão do TFM base. Isto permite-lhe aceder a funcionalidades específicas da plataforma sem esperar por um lançamento importante 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 Android adicionasse APIs de nível API 34 numa atualização .NET do SDK 8.0.x, poderia aceder a elas usando o TFM net8.0-android34.0.

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, a versão padrão da plataforma Android em .NET 9 é 35.0, o que significa que net9.0-android é uma abreviação para o canónico net9.0-android35.0 TFM. A forma abreviada destina-se apenas a ser usada em ficheiros de projeto, e é expandida para a forma canónica pelos destinos MSBuild do SDK .NET antes de ser passada para outras ferramentas, como o NuGet.

A tabela seguinte mostra a versão default da plataforma de destino (TPV) para Android e iOS para cada .NET lançamento. Se você quiser usar as associações mais recentes, use o padrão (ou seja, não especifique uma versão do sistema operacional).

A partir de .NET 9, quando as versões de serviço introduzem suporte para um TPV posterior (que terá sempre o mesmo número de versão major que quando a versão .NET foi lançada inicialmente), o TPV mais antigo suportado para essa versão .NET continuará suportado. Por exemplo, para .NET 9, a versão mais antiga suportada para iOS, a 18.0, continuará suportada, mesmo quando uma versão de serviço adicione suporte para a versão mais recente do iOS 18.x. Se precisares de usar os bindings mais antigos para uma versão .NET, usa um número de versão específico do sistema operativo no teu TFM.

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 destina-se a net9.0-ios e o pacote oferece recursos para net9.0 e net8.0-ios, são usados os recursos de net9.0. 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 não especificares explicitamente esta versão mínima do sistema operativo necessária em tempo de execução no projeto, ela usa por padrão 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. Está gravado no assembly compilado do projeto como um UnsupportedOSPlatformAttribute atributo assembly, para que o analisador de compatibilidade de plataforma possa detetar chamadas desprotegidas para APIs desse assembly de projetos com um valor SupportedOSPlatformVersion mais baixo. Em algumas plataformas, o valor SupportedOSPlatformVersion afeta os processos de empacotamento e compilação de aplicativos específicos da plataforma, que são abordados na documentação dessas plataformas.

O exemplo a seguir é um trecho 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 oferece suporte à 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 ficheiro de projeto da aplicação de consola seguinte demonstra como direcionar o .NET 10:

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

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

</Project>

Ao especificar várias estruturas de destino, você pode condicionalmente fazer referência a assemblies para cada estrutura de destino. No teu código, podes compilar condicionalmente contra esses assemblies usando símbolos de pré-processamento com lógica if-then-else.

O projeto de biblioteca seguinte destina-se às APIs .NET Standard (netstandard1.4) e .NET Framework (net40 e net45). Utilize o elemento TargetFrameworks no plural com várias estruturas de destino. Os atributos Condition incluem pacotes específicos da 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
    }
}

Os valores do TargetFramework são pseudónimos

O valor da propriedade TargetFramework (por exemplo, net10.0) é um nome amigável — um pseudónimo — que o SDK .NET traduz em propriedades canónicas do nome. Especificamente, o SDK define as seguintes propriedades a partir do TargetFramework valor:

• TargetFrameworkMoniker (por exemplo, .NETCoreApp,Version=v10.0)
• TargetFrameworkIdentifier (por exemplo, .NETCoreApp)
• TargetFrameworkVersion (por exemplo, v10.0)
• TargetPlatformMoniker, TargetPlatformIdentifier, e TargetPlatformVersion (quando direciona uma plataforma específica)

O NuGet e o SDK .NET usam estas propriedades do nome — não a cadeia TargetFramework — para verificações de compatibilidade de pacotes e lógica de compilação. Esta tradução já acontece para TFMs específicos do sistema operativo. Por exemplo, net10.0-windows traduz-se em TargetFrameworkMoniker = .NETCoreApp,Version=v10.0 e TargetPlatformMoniker = Windows,Version=7.0.

Como o alias é apenas um nome, o TargetFramework valor pode ser qualquer cadeia alfanumérica, desde que as propriedades correspondentes do nome estejam corretamente definidas. O ficheiro de projeto seguinte utiliza um alias personalizado chamado banana e define explicitamente as propriedades do identificador para que o projeto seja compilado e restaurado para .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>

Para mais informações sobre estas propriedades, consulte a referência de propriedades TargetFramework do MSBuild.

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 num símbolo de pré-processador, substitua pontos e hífens por um sublinhado e altere as letras minúsculas para maiúsculas (por exemplo, o símbolo para netstandard2.0 é NETSTANDARD2_0).

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 os frameworks de destino .NET é:

Estruturas de destino obsoletas

Os frameworks de destino a seguir foram descontinuados. Os pacotes destinados a estas plataformas-alvo devem migrar para as substituições indicadas.

Consulte também

• Nomes de frameworks alvo em .NET 5
• .NET Standard
• .NET versionamento
• Informações sobre o lançamento do Windows 11