Compartilhar via

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

Este artigo explica como atualizar um projeto existente do ASP.NET Core no .NET 7 para o .NET 8.

Pré-requisitos

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

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

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

Atualizar a estrutura de destino

Atualize o TFM (Target Framework Moniker) 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 de projeto, atualize cada referência de pacote Microsoft.AspNetCore.*, Microsoft.EntityFrameworkCore.*, Microsoft.Extensions.* e System.Net.Http.Json's atributo Version para 8.0.0 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 Blazor suporte a um aplicativo ASP.NET Core, consulte Integrar componentes do ASP.NET Core Razor com MVC ou Razor Pages.

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, consulte 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 nas novidades do ASP.NET Core no .NET 8. Ao atualizar um aplicativo do .NET 6 ou anterior, consulte as notas de migração e versão (artigos sobre Novidades) para lançamentos intermediários.

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 Blazor Server aplicativo em um .NET 8 Blazor Web Appequivalente, 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 Blazor Web App convenções, siga as diretrizes na seção Adotar todas as Blazor Web App convenções .

  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 SSR (renderização estática do lado do servidor), consulte ASP.NET modos de renderização coreBlazor.

    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 Antiforgery ao pipeline de processamento de solicitação após a linha que inclui 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 os modos de renderização do ASP.NET CoreBlazor.

Atualizar um aplicativo Blazor WebAssembly

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

Para aplicativos que adotam o carregamento preguiçoso de assemblies, altere a extensão de arquivo de .dll para .wasm na implementação do aplicativo para refletir Blazor WebAssemblya adoção do formato de empacotamento de assemblies do Webcil.

Antes do lançamento do .NET 8, as diretrizes no layout de implantação para aplicativos hospedados Blazor WebAssembly ASP.NET Core abordam ambientes que impedem os clientes de baixar e executar DLLs com uma abordagem de empacotamento multipartido. No .NET 8 ou posterior, Blazor usa o formato de arquivo Webcil para resolver esse problema. A agregação de múltiplas partes usando o pacote NuGet experimental descrito pelo artigo de layout de implantação do WebAssembly não tem suporte para aplicativos em .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 hospedado Blazor WebAssembly ASP.NET Core em um .NET 8 Blazor Web Appequivalente, 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 Blazor Web App convenções, siga as diretrizes na seção Adotar todas as Blazor Web App convenções .

  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 .Client do projeto _Imports.razor 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 do 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 obter mais informações, consulte Control head content in ASP.NET Core Blazor apps.

  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 Middleware Antiforgery 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 .Server projeto 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 as diretrizes anteriormente em Habilitar o suporte do ASP.NET Core Blazor Server com o Yarp na migração incremental para migrar um Blazor Server aplicativo com o Yarp para .NET 6 ou .NET 7, você poderá reverter as etapas de solução alternativa que tomou ao seguir as 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 do 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, consulte Evitar problemas de cache HTTP ao atualizar aplicativos do ASP.NET CoreBlazor.

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

Descobrir componentes de assemblies adicionais

Ao migrar de um Blazor Server aplicativo para um Blazor Web App aplicativo, acesse as diretrizes em ASP.NET Core roteamento e navegação Blazor se o aplicativo usar componentes roteáveis de assemblies adicionais, como bibliotecas de classes 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 Blazor Server script (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 Blazor Server script é atendido por seu próprio ponto de extremidade, usando o roteamento de ponto de extremidade. Essa alteração é introduzida por Correção de bug – Passar opções para UseStaticFiles quebra 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 identidade extra à entidade de segurança de solicitação.
  • A política de autorização alternativa tem requisitos que verificam as declarações por meio da identidade adicional.

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 de autenticação de arquivo não são autenticadas pelo esquema de autenticação adicional para locatários, mas ainda são submetidas à política de fallback, resultando em um resultado não autorizado.

Esse problema está em avaliação para um novo recurso de framework no MapRazorComponents quebrado com FallbackPolicy RequireAuthenticatedUser (dotnet/aspnetcore 51836), que está atualmente programado 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 não do Blazor, use explicitamente [Authorize] ou RequireAuthorization.

  • 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 verifique o HttpContext para permitir a passagem do arquivo /_framework/blazor.server.js.

Estivador

Atualizar imagens do Docker

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

- 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 alterações significativas do .NET 7 para o .NET 8, consulte Alterações significativas no .NET 8, que inclui seções ASP.NET Core e Entity Framework Core .