Compartilhar via

Microsoft.AspNetCore.App para ASP.NET Core

  • Artigo

Observação

Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão .NET 9 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, confira .NET e a Política de Suporte do .NET Core. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para a versão atual, consulte a versão .NET 9 deste artigo.

A estrutura compartilhada do ASP.NET Core (Microsoft.AspNetCore.App) contém assemblies que são desenvolvidos pela Microsoft e compatíveis com ela. Microsoft.AspNetCore.App será instalado quando o SDK do .NET Core 3.0 ou posterior for instalado. A estrutura compartilhada é o conjunto de assemblies (arquivos .dll) que estão instalados no computador e inclui um componente de runtime e um pacote de destino. Saiba mais em A estrutura compartilhada.

  • Projetos direcionados ao SDK Microsoft.NET.Sdk.Web referenciam a estrutura Microsoft.AspNetCore.App implicitamente.

Não são necessárias referências adicionais para esses projetos:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>
    ...
</Project>

A estrutura compartilhada do ASP.NET Core:

  • Não inclui dependências de terceiros.
  • Inclui todos os pacotes com suporte da equipe do ASP.NET Core.

Este recurso exige o ASP.NET Core 2.x direcionado ao .NET Core 2.x.

O Microsoft.AspNetCore.App (metapacote) para ASP.NET Core:

  • Não tem dependências de terceiros, com exceção de Json.NET, Remotion.Linq e IX-Async. Essas dependências de terceiros são consideradas necessárias para garantir o funcionamento dos principais recursos das estruturas.
  • Inclui todos os pacotes com suporte pela equipe do ASP.NET Core, exceto aqueles que contêm dependências de terceiros (que não sejam aqueles mencionados anteriormente).
  • Inclui todos os pacotes com suporte pela equipe do Entity Framework Core, exceto aqueles que contêm dependências de terceiros (que não sejam aqueles mencionados anteriormente).

Todos os recursos do ASP.NET Core 2.x e do Entity Framework Core 2.x são incluídos no pacote Microsoft.AspNetCore.App. Os modelos de projeto padrão direcionados para o ASP.NET Core 2 usam esse pacote. Recomendamos que os aplicativos direcionados ao ASP.NET Core 2.x e ao Entity Framework Core 2.x usem o pacote Microsoft.AspNetCore.App.

O número de versão do metapacote Microsoft.AspNetCore.App representa a versão mínima do ASP.NET Core e a versão do Entity Framework Core.

O uso do metapacote Microsoft.AspNetCore.App fornece restrições de versões que protegem seu aplicativo:

  • Se um pacote incluído tem uma dependência (não direta) transitiva em um pacote no Microsoft.AspNetCore.App, e os números de versão forem diferentes, o NuGet gera um erro.
  • Outros pacotes adicionados ao seu aplicativo não podem alterar a versão dos pacotes incluídos no Microsoft.AspNetCore.App.
  • A consistência de versão garante uma experiência confiável. Microsoft.AspNetCore.App foi projetado para evitar combinações de versão não testado de bits relacionados que estão sendo usados juntos no mesmo aplicativo.

Aplicativos que usam o metapacote Microsoft.AspNetCore.App aproveitam automaticamente a estrutura compartilhada do ASP.NET Core. Ao usar o metapacote Microsoft.AspNetCore.App, nenhum ativo dos pacotes NuGet do ASP.NET Core referenciados é implantado com o aplicativo, porque a estrutura compartilhada do ASP.NET Core contém esses ativos. Os ativos na estrutura compartilhada são pré-compilados para melhorar o tempo de inicialização do aplicativo. Saiba mais em A estrutura compartilhada.

O seguinte arquivo de projeto referencia o metapacote Microsoft.AspNetCore.App do ASP.NET Core e representa um modelo típico do ASP.NET Core 2.2:

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

  <PropertyGroup>
    <TargetFramework>netcoreapp2.2</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

A marcação anterior representa um modelo típico do ASP.NET Core 2.x. Ela não especifica um número de versão para a referência de pacote Microsoft.AspNetCore.App. Quando a versão não for especificada, uma versão implícita será especificada pelo SDK, ou seja, Microsoft.NET.Sdk.Web. Recomendamos que você conte com a versão implícita especificada pelo SDK, e não defina explicitamente o número de versão na referência de pacote. Se tiver dúvidas sobre essa abordagem, deixe um comentário do GitHub na Discussão para a versão implícita do Microsoft.AspNetCore.App.

A versão implícita é definida como major.minor.0 para aplicativos portátil. O mecanismo de roll forward estrutura compartilhada executará o aplicativo na versão compatível mais recente entre as estruturas compartilhadas instaladas. Para garantir que a mesma versão seja usada no desenvolvimento, no teste e na produção, certifique-se de que a mesma versão da estrutura compartilhada seja instalada em todos os ambientes. Para aplicativos independentes, o número de versão implícita é definido como major.minor.patch da estrutura compartilhada incluída no SDK instalado.

Especificar um número de versão na referência Microsoft.AspNetCore.Appnão garante que a versão da estrutura compartilhada será escolhida. Por exemplo, suponha que a versão "2.2.1" foi especificada, mas é a "2.2.3" que está instalada. Nesse caso, o aplicativo usará a "2.2.3". Embora não seja recomendado, você pode desabilitar o roll forward (patch e/ou secundária). Para obter mais informações sobre como efetuar roll forward do host dotnet e como configurar seu comportamento, veja Efetuar roll forward do host dotnet.

<Project Sdk deve ser definido como Microsoft.NET.Sdk.Web para usar o Microsoft.AspNetCore.App da versão implícita. Quando <Project Sdk="Microsoft.NET.Sdk"> (sem o .Web à direita) é usado:

  • O aviso a seguir é gerado:

    Aviso NU1604: a dependência de projeto Microsoft.AspNetCore.App não tem um limite inferior inclusivo. Inclua um limite inferior na versão de dependência para garantir resultados consistentes de restauração.

  • Esse é um problema conhecido do SDK do .NET Core 2.1.

Atualizar o ASP.NET Core

O Microsoft.AspNetCore.App (metapacote) não é um pacote tradicional atualizado do NuGet. Semelhante ao Microsoft.NETCore.App, Microsoft.AspNetCore.App representa um runtime compartilhado, que tem semântica de controle de versão especial tratada fora do NuGet. Para obter mais informações, veja Pacotes, metapacotes e estruturas.

Para atualizar o ASP.NET Core:

Os aplicativos efetuarão roll forward para a versão mais recente instalada na reinicialização do aplicativo. Não é necessário atualizar o número de versão Microsoft.AspNetCore.App no arquivo de projeto. Para obter mais informações, consulte Roll forward de aplicativos dependentes de estrutura.

Se seu aplicativo tiver usado Microsoft.AspNetCore.All, veja Migração do Microsoft.AspNetCore.All para Microsoft.AspNetCore.App.