Migrar do ASP.NET Core no .NET 7 para o .NET 8

  • Artigo

Este artigo explica como atualizar um projeto existente do ASP.NET Core 7.0 para o ASP.NET Core 8.0.

Pré-requisitos

Atualizar a versão do SDK do .NET Core em global.json

Se você depende de um arquivo global.json para direcionar a uma versão específica do SDK do .NET Core, atualize a propriedade version para a versão do SDK do .NET 8.0 instalada. Por exemplo:

{
  "sdk": {
-    "version": "7.0.100"
+    "version": "8.0.100"
  }
}

Atualizar a estrutura de destino

Atualize o TFM (Moniker da Estrutura de Destino) do arquivo de projeto para net8.0:

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

  <PropertyGroup>
-    <TargetFramework>net7.0</TargetFramework>
+    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

</Project>

Referências do pacote de atualização

No arquivo do projeto, atualize o atributo Version de cada referência de pacote Microsoft.AspNetCore.*, Microsoft.EntityFrameworkCore.*, Microsoft.Extensions.* e System.Net.Http.Json para 8.00 ou posterior. Por exemplo:

<ItemGroup>
-   <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="7.0.12" />
-   <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="7.0.12" />
-   <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="7.0.0" />
-   <PackageReference Include="System.Net.Http.Json" Version="7.0.1" />
+   <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="8.0.0" />
+   <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="8.0.0" />
+   <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="8.0.0" />
+   <PackageReference Include="System.Net.Http.Json" Version="8.0.0" />
</ItemGroup>

Blazor

Os seguintes cenários de migração são abordados:

Para obter diretrizes sobre como adicionar suporte ao Blazor a um aplicativo ASP.NET Core, consulte Integrar componentes Razor do ASP.NET Core em aplicativos do ASP.NET Core.

Atualizar um aplicativo Blazor Server

Recomendamos o uso de Blazor Web Apps no .NET 8, mas há suporte para Blazor Server. Para continuar usando Blazor Server com o .NET 8, siga as diretrizes das três primeiras seções deste artigo:

Os novos recursos Blazor introduzidos para os Blazor Web Apps não estão disponíveis para um aplicativo Blazor Server atualizado para execução no .NET 8. Se desejar adotar os novos recursos do .NET 8 Blazor, siga as diretrizes de uma das seções a seguir:

Adotar todas as convenções do Blazor Web App

Para adotar opcionalmente todas as novas convenções do Blazor Web App, recomendamos o seguinte processo:

  • Crie um novo aplicativo com base no modelo de projeto do Blazor Web App. Para obter mais informações, confira Ferramentas para ASP.NET Core Blazor.
  • Mova os componentes e o código do seu aplicativo para o novo aplicativo Blazor Web App, fazendo modificações para adotar novos recursos.
  • Atualize o layout e os estilos do Blazor Web App.

Novos recursos do .NET 8 são abordados em Novidades do ASP.NET Core 8.0. Ao atualizar um aplicativo do .NET 6 ou anterior, consulte as notas de migração e versão (artigos Novidades) para versões intermediárias.

Converter aplicativo Blazor Server em um Blazor Web App

Há suporte para aplicativos Blazor Server no .NET 8 sem alterações de código. Use as diretrizes a seguir para converter um aplicativo Blazor Server em um Blazor Web App equivalente do .NET 8, o que disponibiliza todos os novos recursos do .NET 8.

Importante

Esta seção foca nas alterações mínimas necessárias para converter um aplicativo Blazor Server do .NET 7 em um Blazor Web App do .NET 8 . Para adotar todas as novas convenções do Blazor Web App, siga as diretrizes da seção Adotar todas as convenções do Blazor Web App.

  1. Siga as diretrizes nas três primeiras seções deste artigo:

  2. Mova o conteúdo do componente App (App.razor) para um novo arquivo do componente Routes (Routes.razor) adicionado à pasta raiz do projeto. Deixe o arquivo vazio App.razor no aplicativo na pasta raiz do projeto.

  3. Adicione uma entrada ao arquivo _Imports.razor para disponibilizar modos de renderização abreviada para o aplicativo:

    @using static Microsoft.AspNetCore.Components.Web.RenderMode

  4. Mova o conteúdo na página _Host (Pages/_Host.cshtml) para o arquivo vazio App.razor. Prossiga para fazer as seguintes alterações no componente App.

    Observação

    No exemplo a seguir, o namespace do projeto do cliente é BlazorServerApp. Ajuste o namespace para corresponder ao seu projeto.

    Remova as seguintes linhas da parte superior do arquivo:

    - @page "/"
- @using Microsoft.AspNetCore.Components.Web
- @namespace BlazorServerApp.Pages
- @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

    Substitua as linhas anteriores por uma linha que injete uma instância IHostEnvironment:

    @inject IHostEnvironment Env

    Remova o til (~) do href da marca <base> e substitua pelo caminho base do aplicativo:

    - <base href="~/" />
+ <base href="/" />

    Remova o Auxiliar de Marca de Componente do componente HeadOutlet e substitua-o pelo componente HeadOutlet.

    Remova a seguinte linha:

    - <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />

    Substitua a linha anterior pela seguinte:

    <HeadOutlet @rendermode="InteractiveServer" />

    Remova o Auxiliar de Marca de Componente do componente App e substitua-o pelo componente Routes.

    Remova a seguinte linha:

    - <component type="typeof(App)" render-mode="ServerPrerendered" />

    Substitua a linha anterior pela seguinte:

    <Routes @rendermode="InteractiveServer" />

    Observação

    A configuração anterior pressupõe que os componentes do aplicativo adotem a renderização interativa do servidor. Para obter mais informações, incluindo como adotar a renderização estática do lado do servidor (SSR), consulte ASP.NET Core Blazor modos de renderização.

    Remova os auxiliares de Marcas de Ambiente para a interface do usuário de erros e substitua-os pela seguinte marcação Razor.

    Remova as seguintes linhas:

    - <environment include="Staging,Production">
-     An error has occurred. This application may no longer respond until reloaded.
- </environment>
- <environment include="Development">
-     An unhandled exception has occurred. See browser dev tools for details.
- </environment>

    Substitua as linhas anteriores pelas seguintes:

    @if (Env.IsDevelopment())
{
    <text>
        An unhandled exception has occurred. See browser dev tools for details.
    </text>
}
else
{
    <text>
        An error has occurred. This app may no longer respond until reloaded.
    </text>
}

    Altere o script do Blazor de blazor.server.js para blazor.web.js:

    - <script src="_framework/blazor.server.js"></script>
+ <script src="_framework/blazor.web.js"></script>

  5. Exclua o arquivo Pages/_Host.cshtml.

  6. Atualizar Program.cs:

    Observação

    No exemplo a seguir, o namespace do projeto do cliente é BlazorServerApp. Ajuste o namespace para corresponder ao seu projeto.

    Adicione uma instrução using à parte superior do arquivo para o namespace do projeto:

    using BlazorServerApp;

    Substitua AddServerSideBlazor por AddRazorComponents e por uma chamada encadeada para AddInteractiveServerComponents.

    Remova a seguinte linha:

    - builder.Services.AddServerSideBlazor();

    Substitua a linha anterior pelo componente Razor e serviços de componente de servidor interativos. A chamada AddRazorComponents adiciona serviços antifalsificação (AddAntiforgery) por padrão.

    builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

    Remova a seguinte linha:

    - app.MapBlazorHub();

    Substitua a linha anterior por uma chamada para MapRazorComponents, fornecendo o componente App como o tipo de componente raiz, e adicione uma chamada encadeada para AddInteractiveServerRenderMode:

    app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

    Remova a seguinte linha:

    - app.MapFallbackToPage("/_Host");

    Remover middleware de roteamento:

    - app.UseRouting();

    Adicione o Middleware Antifalsificação ao pipeline de processamento de solicitações após a linha que adiciona o Middleware de Redirecionamento HTTPS (app.UseHttpsRedirection):

    app.UseAntiforgery();

    A chamada anterior para app.UseAntiforgery deve ser feita após chamadas, se presentes, para app.UseAuthentication e app.UseAuthorization. Não há necessidade de adicionar explicitamente serviços antifalsificação (builder.Services.AddAntiforgery), pois eles são adicionados automaticamente por AddRazorComponents, que foi abordado anteriormente.

  7. Se o aplicativo Blazor Server foi configurado para desabilitar a pré-renderização, você poderá continuar a desabilitar a pré-renderização para o aplicativo atualizado. No componente App, altere o valor atribuído aos atributos de diretiva @rendermode do Razor para os componentes HeadOutlet e Routes.

    Altere o valor do atributo da diretiva @rendermode para os componentes HeadOutlet e Routes para desabilitar a pré-renderização:

    - @rendermode="InteractiveServer"
+ @rendermode="new InteractiveServerRenderMode(prerender: false)"

    Para obter mais informações, consulte ASP.NET Core Blazor modos de renderização.

Atualizar um aplicativo Blazor WebAssembly

Siga as diretrizes nas três primeiras seções deste artigo:

Para aplicativos que adotam o carregamento lento do assembly, altere a extensão de arquivo de .dll para .wasm na implementação do aplicativo para refletir a adoção de Blazor WebAssembly do empacotamento do assembly do Webcil.

Antes do lançamento do .NET 8, a orientação em Layout de implantação para aplicativos hospedados Blazor WebAssembly do ASP.NET Core aborda ambientes que impedem os clientes de baixar e executar DLLs com uma abordagem de agrupamento de várias partes. No .NET 8 ou posterior, Blazor usa o formato de arquivo Webcil para resolver esse problema. O agrupamento de várias partes usando o pacote NuGet experimental descrito pelo artigo Layout de implantação do WebAssembly não tem suporte para aplicativos Blazor no .NET 8 ou posterior. Se você quiser continuar usando o pacote de várias partes em aplicativos .NET 8 ou posteriores, poderá usar as diretrizes no artigo para criar seu próprio pacote NuGet de agrupamento de várias partes, mas ele não terá suporte da Microsoft.

Converter um aplicativo Blazor WebAssembly hospedado em um Blazor Web App

Há suporte para aplicativos Blazor WebAssembly no .NET 8 sem alterações de código. Use as diretrizes a seguir para converter um aplicativo Blazor WebAssembly hospedado do ASP.NET Core em um Blazor Web App equivalente do .NET 8, o que disponibiliza todos os novos recursos do .NET 8.

Importante

Esta seção foca nas alterações mínimas necessárias para converter um aplicativo Blazor WebAssembly hospedado do .NET 7 ASP.NET Core em um Blazor Web App do .NET 8. Para adotar todas as novas convenções do Blazor Web App, siga as diretrizes da seção Adotar todas as convenções do Blazor Web App.

  1. Siga as diretrizes nas três primeiras seções deste artigo:

    Importante

    Usando as diretrizes anteriores, atualize os projetos .Client, .Server e .Shared da solução.

  2. No arquivo de projeto .Client (.csproj), adicione as seguintes propriedades do MSBuild:

    <NoDefaultLaunchSettingsFile>true</NoDefaultLaunchSettingsFile>
<StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode>

    Também no arquivo de projeto .Client, remova a referência ao pacote Microsoft.AspNetCore.Components.WebAssembly.DevServer:

    - <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.DevServer"... />

  3. Mova o conteúdo do arquivo .Client/wwwroot/index.html para um novo arquivo de componente App (App.razor) criado na raiz do projeto .Server. Depois de mover o conteúdo do arquivo, exclua o arquivo index.html.

    Renomeie App.razor no projeto .Client como Routes.razor.

    Em Routes.razor, defina o valor do atributoAppAssembly como typeof(Program).Assembly.

  4. No projeto .Client, adicione uma entrada ao arquivo _Imports.razor para disponibilizar modos de renderização abreviada para o aplicativo:

    @using static Microsoft.AspNetCore.Components.Web.RenderMode

    Faça uma cópia do arquivo _Imports.razor do projeto .Client e adicione-o ao projeto .Server.

  5. Faça as seguintes alterações no arquivoApp.razor:

    Substitua o título do site padrão do site (<title>...</title>) por um componente HeadOutlet. Observe o título do site para uso posterior e remova as marcas de título e o título:

    - <title>...</title>

    Quando você removeu o título, coloque um componente HeadOutlet atribuindo o modo de renderização WebAssembly interativo (pré-geração desabilitada):

    <HeadOutlet @rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" />

    Altere o pacote de estilo CSS:

    - <link href="{CLIENT PROJECT ASSEMBLY NAME}.styles.css" rel="stylesheet">
+ <link href="{SERVER PROJECT ASSEMBLY NAME}.styles.css" rel="stylesheet">

    Espaços reservados no código anterior:

    • {CLIENT PROJECT ASSEMBLY NAME}: nome do assembly do projeto do cliente. Exemplo: BlazorSample.Client
    • {SERVER PROJECT ASSEMBLY NAME}: nome do assembly do projeto do servidor. Exemplo: BlazorSample.Server

    Localize o seguinte <div>...</div> marcação HTML:

    - <div id="app">
-     ...
- </div>

    Substitua a marcação HTML <div>...</div> anterior pelo componente Routes usando o modo de renderização WebAssembly interativo (pré-geração desabilitada):

    <Routes @rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" />

    Atualize o script do blazor.webassembly.js para blazor.web.js:

    - <script src="_framework/blazor.webassembly.js"></script>
+ <script src="_framework/blazor.web.js"></script>

  6. Abra o arquivo de layout do projeto .Client (.Client/Shared/MainLayout.razor) e adicione um componente PageTitle com o título padrão do site ({TITLE} espaço reservado):

    <PageTitle>{TITLE}</PageTitle>

    Observação

    Outros arquivos de layout também devem receber um componente PageTitle com o título do site padrão.

    Para mais informações, confira oControle de Conteúdo de CabeçalhoBlazor em aplicativos do ASP.NET Core.

  7. Remova as seguinte linhas de .Client/Program.cs:

    - builder.RootComponents.Add<App>("#app");
- builder.RootComponents.Add<HeadOutlet>("head::after");

  8. Atualizar .Server/Program.cs:

    Adicione serviços de componentes Razor e componentes WebAssembly interativos ao projeto. Chame AddRazorComponents com uma chamada encadeada para AddInteractiveWebAssemblyComponents. A chamada AddRazorComponents adiciona serviços antifalsificação (AddAntiforgery) por padrão.

    builder.Services.AddRazorComponents()
    .AddInteractiveWebAssemblyComponents();

    Adicione o middleware antifalsificação ao pipeline de processamento de solicitação.

    Coloque a seguinte linha após a chamada para app.UseHttpsRedirection. A chamada para app.UseAntiforgery deve ser feita após chamadas, se houver, para app.UseAuthentication e app.UseAuthorization. Não há necessidade de adicionar explicitamente serviços antifalsificação (builder.Services.AddAntiforgery), pois eles são adicionados automaticamente por AddRazorComponents, que foi abordado anteriormente.

    app.UseAntiforgery();

    Remova a seguinte linha:

    - app.UseBlazorFrameworkFiles();

    Remova a seguinte linha:

    - app.MapFallbackToFile("index.html");

    Substitua a linha anterior por uma chamada para MapRazorComponents, fornecendo o componente App como o tipo de componente raiz, e adicione chamadas encadeadas para AddInteractiveWebAssemblyRenderMode e AddAdditionalAssemblies:

    app.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof({CLIENT APP NAMESPACE}._Imports).Assembly);

    No exemplo anterior, o espaço reservado {CLIENT APP NAMESPACE} é o namespace do projeto .Client (por exemplo, HostedBlazorApp.Client).

  9. Execute a solução no projeto .Server:

    Para o Visual Studio, confirme se o projeto .Server está selecionado no Gerenciador de Soluções ao executar o aplicativo.

    Se estiver usando a CLI do .NET, execute o projeto na pasta do projeto .Server.

Atualizar a configuração das opções de serviço e ponto de extremidade

Com o lançamento dos Blazor Web Apps no .NET 8, a configuração das opções de serviços e pontos de extremidade do Blazor é atualizada com a introdução de uma nova API para serviços de componentes interativos e a configuração de pontos de extremidade de componentes.

As diretrizes de configuração atualizadas aparecem nos seguintes locais:

Remover Blazor Server com a solução alternativa de roteamento Yarp

Se você seguiu anteriormente as diretrizes em Habilitar suporte ao ASP.NET Core Blazor Server com Yarp na migração incremental para migrar um aplicativo Blazor Server com Yarp para o .NET 6 ou .NET 7, poderá reverter as etapas de solução alternativa que adotou ao seguir a diretrizes do artigo. O roteamento e a vinculação profunda para Blazor Server com o Yarp funcionam corretamente no .NET 8.

Migrar CascadingValue componentes em componentes de layout

Os parâmetros em cascata não passam dados entre os limites do modo de renderização e os layouts são renderizados estaticamente em aplicativos interativos. Portanto, os aplicativos que buscam usar parâmetros em cascata em componentes renderizados interativamente não poderão fazer a cascata dos valores de um layout.

As duas abordagens para migração são:

Para obter mais informações, consulte valores/parâmetros em cascata e limites de modo de renderização.

Migrar a BlazorEnableCompression propriedade MSBuild

Para Blazor WebAssembly aplicativos que desabilitam a compactação e o .NET 7 de destino ou anteriores, mas são criados com o SDK do .NET 8, a propriedade BlazorEnableCompression MSBuild foi alterada para CompressionEnabled:

<PropertyGroup>
-   <BlazorEnableCompression>false</BlazorEnableCompression>
+   <CompressionEnabled>false</CompressionEnabled>
</PropertyGroup>

Ao usar o comando de publicação da CLI do .NET, use a nova propriedade:

dotnet publish -p:CompressionEnabled=false

Para saber mais, consulte os recursos a seguir:

Migrar o componente <CascadingAuthenticationState> para os serviços de estado de autenticação em cascata

No .NET 7 ou anterior, o componente CascadingAuthenticationState é encapsulado em alguma parte da árvore da interface do usuário, por exemplo, em torno do roteador Blazor, para fornecer o estado de autenticação em cascata:

<CascadingAuthenticationState>
    <Router ...>
        ...
    </Router>
</CascadingAuthenticationState>

No .NET 8, não use o componente CascadingAuthenticationState:

- <CascadingAuthenticationState>
      <Router ...>
          ...
      </Router>
- </CascadingAuthenticationState>

Em vez disso, adicione os serviços de estado de autenticação em cascata à coleção de serviços chamando AddCascadingAuthenticationState no arquivo Program:

builder.Services.AddCascadingAuthenticationState();

Para saber mais, consulte os recursos a seguir:

Novo artigo sobre problemas de cache HTTP

Adicionamos um novo artigo que discute alguns dos problemas comuns de cache HTTP que podem ocorrer ao atualizar Blazor aplicativos entre as versões principais e como resolver problemas de cache HTTP.

Para obter mais informações, confira Evitar problemas de cache HTTP ao atualizar aplicativos ASP.NET Core Blazor.

Novo artigo sobre bibliotecas de classes com renderização estática do lado do servidor (SSR estático)

Adicionamos um novo artigo que discute a autoria da biblioteca de componentes em RCLs (bibliotecas de classes) no Razor com renderização estática do lado do servidor (SSR estático).

Para obter mais informações, consulte Bibliotecas de classes (RCLs) do ASP.NET Core Razor com renderização estática do lado do servidor (SSR estático).

Descobrir componentes de assemblies adicionais

Ao migrar de um aplicativo do Blazor Server para um Blazor Web App, acesse as diretrizes em Roteamento e navegação do Blazor do ASP.NET Core se o aplicativo usar componentes roteáveis de assemblies adicionais, como bibliotecas de classe de componente.

Remova o atributo [Parameter] quando o parâmetro é fornecido a partir de uma cadeia de caracteres de consulta

O atributo [Parameter] não é mais necessário ao fornecer um parâmetro da cadeia de caracteres de consulta:

- [Parameter]
  [SupplyParameterFromQuery]

Blazor Server autorização de política de fallback de script

No .NET 7, o script Blazor Server (blazor.server.js) é servido pelo Middleware de Arquivos Estáticos. Colocar a chamada para o Middleware de Arquivos Estáticos (UseStaticFiles) no pipeline de processamento de solicitação antes da chamada para o Middleware de Autorização (UseAuthorization) é suficiente em aplicativos do .NET 7 para fornecer o script Blazor a usuários anônimos.

No .NET 8, o script Blazor Server é atendido por seu próprio ponto de extremidade, usando o roteamento de ponto de extremidade. Esta alteração é introduzida por Bug fixo – passar opções para UseStaticFiles interrompe Blazor Server (dotnet/aspnetcore nº 45897).

Considere um cenário multilocatário em que:

  • As políticas padrão e de fallback são definidas de forma idêntica.
  • O locatário é resolvido usando o primeiro segmento no caminho da solicitação (por exemplo, tld.com/tenant-name/...).
  • As solicitações para pontos de extremidade de locatário são autenticadas por um esquema de autenticação adicional, que adiciona uma identity extra à entidade de segurança de solicitação.
  • A política de autorização de fallback tem requisitos que verificam declarações por meio da identity extra.

As solicitações para o arquivo de script Blazor (blazor.server.js) são atendidas em /_framework/blazor.server.js, que é codificado na estrutura. As solicitações para o arquivo não são autenticadas pelo esquema de autenticação adicional para locatários, mas ainda são desafiadas pela política de fallback, o que resulta no retorno de um resultado não autorizado.

Este problema está em avaliação para um novo recurso de estrutura em MapRazorComponents interrompidos com FallbackPolicy RequireAuthenticatedUser (dotnet/aspnetcore 51836), que está atualmente agendado para o lançamento do .NET 9 em novembro de 2024. Até lá, você pode contornar esse problema usando qualquer uma das três abordagens a seguir:

  • Não use uma política de fallback. Aplique o atributo [Authorize] no arquivo _Imports.razor para aplicá-lo a todos os componentes do aplicativo. Para pontos de extremidade que não são do blazor, use [Authorize] ou RequireAuthorization de forma explícita.

  • Adicione [AllowAnonymous] ao ponto de extremidade /_framework/blazor.server.js no arquivo Program:

    app.MapBlazorHub().Add(endpointBuilder =>
{
    if (endpointBuilder is 
        RouteEndpointBuilder
        { 
            RoutePattern: { RawText: "/_framework/blazor.server.js" }
        })
    {
        endpointBuilder.Metadata.Add(new AllowAnonymousAttribute());
    }
});

  • Registre um AuthorizationHandler personalizado que verifica HttpContext para conceder permissão para a passagem do arquivo /_framework/blazor.server.js.

Docker

Atualizar imagens do Docker

Para aplicativos que usam o Docker, atualize as instruções e scripts FROM do Dockerfile. Use uma imagem base que inclua o runtime do ASP.NET Core 8.0. Considere a seguinte diferença de comando docker pull entre o ASP.NET Core 7.0 e 8.0:

- docker pull mcr.microsoft.com/dotnet/aspnet:7.0
+ docker pull mcr.microsoft.com/dotnet/aspnet:8.0

Atualizar a porta do Docker

A porta de ASP.NET Core padrão configurada em imagens de contêiner do .NET foi atualizada da porta 80 para 8080.

A nova ASPNETCORE_HTTP_PORTS variável de ambiente foi adicionada como uma alternativa mais simples para ASPNETCORE_URLS.

Para saber mais, veja:

Analisar as alterações interruptivas

Para ver as alterações significativas do ASP.NET Core 7.0 para 8.0, consulte Alterações significativas no .NET 8, que inclui as seções ASP.NET Core e Entity Framework Core .