Partilhar via

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

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

Pré-requisitos

Atualize a versão do SDK do .NET em global.json

Caso confie em um arquivo global.json para apontar para uma versão específica do SDK do .NET Core, atualize a propriedade version para a versão do SDK do .NET 8 instalada. Por exemplo:

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

Atualizar a estrutura de destino

Atualize o Target Framework Moniker (TFM) do arquivo de projeto para net8.0:

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

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

</Project>

Atualizar referências de pacotes

No arquivo de projeto, atualize o atributo Microsoft.AspNetCore.* de cada referência de pacote Microsoft.EntityFrameworkCore.*, Microsoft.Extensions.*, System.Net.Http.Json e 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 cobertos:

Para obter orientação sobre como adicionar Blazor suporte a um aplicativo ASP.NET Core, consulte Integrar componentes ASP.NET Core Razor com MVC ou Razor Pages.

Atualizar uma Blazor Server aplicação

Recomendamos usar Blazor Web Apps no .NET 8, mas Blazor Server é suportado. Para continuar usando Blazor Server o .NET 8, siga as orientações nas três primeiras seções deste artigo:

Os novos Blazor recursos introduzidos para Blazor Web Apps não estão disponíveis para uma aplicação Blazor Server atualizada para correr sob o .NET 8. Se você deseja adotar os novos recursos do .NET 8 Blazor , siga as orientações em uma das seguintes seções:

Adotar todas as Blazor Web App convenções

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

  • Crie um novo aplicativo a partir do Blazor Web App modelo de projeto. 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 Blazor Web App, fazendo modificações para adotar novos recursos.
  • Atualize o layout e os estilos do Blazor Web App.

Os novos recursos do .NET 8 são abordados em Novidades no 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 o que há de novo) para as versões intermediárias.

Converter uma Blazor Server aplicação num Blazor Web App

Blazor Server os aplicativos são suportados 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, que disponibiliza todos os novos recursos do .NET 8 .

Importante

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

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

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

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

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

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

    Observação

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

    Remova as seguintes linhas da parte superior do ficheiro:

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

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

    @inject IHostEnvironment Env

    Remova o til (~) do elemento ~ da tag href e substitua-o pelo caminho base do seu aplicativo:

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

    Remova o Helper de marca do componente HeadOutlet e substitua-o pelo componente HeadOutlet.

    Remova a seguinte linha:

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

    Substitua a linha anterior pelo seguinte:

    <HeadOutlet @rendermode="InteractiveServer" />

    Remova o Helper de marca do componente App e substitua-o pelo componente Routes.

    Remova a seguinte linha:

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

    Substitua a linha anterior pelo 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 Modos de renderização principaisBlazor.

    Remova os "Tag Helpers" de Ambiente para a interface de utilizador de erro 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 pelo seguinte:

    @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 Blazor script 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 Pages/_Host.cshtml arquivo.

  6. Atualização Program.cs:

    Observação

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

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

    using BlazorServerApp;

    Substitua AddServerSideBlazor por AddRazorComponents e faça uma chamada encadeada para AddInteractiveServerComponents.

    Remova a seguinte linha:

    - builder.Services.AddServerSideBlazor();

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

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

    Remova a seguinte linha:

    - app.MapBlazorHub();

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

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

    Remova a seguinte linha:

    - app.MapFallbackToPage("/_Host");

    Remova o middleware de roteamento:

    - app.UseRouting();

    Adicionar Antiforgery Middleware ao pipeline de processamento de solicitações após a linha que adiciona HTTPS Redirection Middleware (app.UseHttpsRedirection):

    app.UseAntiforgery();

    A chamada anterior 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 pelo AddRazorComponents, que foi coberto anteriormente.

  7. Se a aplicação estiver configurada para desativar a pré-renderização, pode continuar a desativar a pré-renderização para a aplicação atualizada. No componente App, altere o valor atribuído aos atributos da diretiva @rendermodeRazor para os componentes HeadOutlet e Routes.

    Altere o valor do atributo da diretiva @rendermode tanto para o componente HeadOutlet quanto para o componente Routes para desativar a prerenderização.

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

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

Atualizar uma Blazor WebAssembly aplicação

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

Para aplicações que adotam carregamento lento de assembly, altere a extensão de ficheiro de .dll para .wasm na implementação da aplicação, refletindo a adoção do Blazor WebAssembly por .

Antes do lançamento do .NET 8, as diretrizes na configuração de implantação para aplicativos Blazor WebAssembly hospedados em ASP.NET Core tratam de ambientes que impedem os clientes de baixar e executar DLLs com uma abordagem de agregação de várias partes. No .NET 8 ou posterior, Blazor usa o formato de arquivo Webcil para resolver esse problema. O agrupamento multipartes usando o pacote NuGet experimental descrito no artigo sobre o layout de implantação do WebAssembly não é suportado para apps no .NET 8 ou versões posteriores. Se desejar continuar a usar o pacote de agrupamento de várias partes em aplicações .NET 8 ou posteriores, pode seguir as orientações no artigo para criar o seu próprio pacote NuGet de agrupamento de várias partes, mas não terá suporte da Microsoft.

Converter um aplicativo hospedado Blazor WebAssembly em um Blazor Web App

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

Importante

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

  1. Siga as orientações 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 .Client projeto (.csproj), adicione as seguintes propriedades do MSBuild:

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

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

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

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

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

    Em Routes.razor, atualize o valor do atributo AppAssembly para typeof(Program).Assembly.

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

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

    Faça uma cópia do ficheiro do projeto .Client_Imports.razor e adicione-o ao projeto .Server.

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

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

    - <title>...</title>

    Onde você removeu o título, coloque um HeadOutlet componente atribuindo o modo de renderização Interactive WebAssembly (pré-renderizaçã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 precedente:

    • {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 a seguinte <div>...</div> marcação HTML:

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

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

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

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

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

  6. Abra o .Client arquivo de layout do projeto (.Client/Shared/MainLayout.razor) e adicione um PageTitle componente 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 PageTitle componente com o título padrão do site.

    Para obter mais informações, consulte Controlar o conteúdo do cabeçote em aplicativos ASP.NET CoreBlazor.

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

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

  8. Atualização .Server/Program.cs:

    Adicione o componente Razor e os serviços de componente WebAssembly interativo ao projeto. Ligue AddRazorComponents com uma chamada encadeada para AddInteractiveWebAssemblyComponents. A chamada AddRazorComponents adiciona serviços antifalsificação (AddAntiforgery) por predefinição.

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

    Adicione o Antiforgery Middleware ao pipeline de processamento de solicitações.

    Insira a linha a seguir 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 pelo AddRazorComponents, que foi coberto 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 App componente 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 {CLIENT APP NAMESPACE} placeholder é o namespace do .Client projeto (por exemplo, HostedBlazorApp.Client).

  9. Execute a solução a partir do .Server projeto:

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

    Se estiver a utilizar a CLI do .NET, execute o projeto a partir do diretório da pasta do projeto .Server.

Atualizar a configuração da opção de serviço e de endpoint

Com o lançamento de componentes no .NET 8, a configuração de opções de serviço e de ponto final é atualizada com a introdução de novas APIs para serviços de componentes interativos e configuração de ponto final de componentes.

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

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

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

Migrar CascadingValue componentes em componentes de layout

Os parâmetros em cascata não passam dados através dos limites do modo de renderização e os layouts são renderizados de forma estática em aplicações que de outra forma seriam interativas. Portanto, os aplicativos que procuram usar parâmetros em cascata em componentes renderizados interativamente não poderão cascatar os valores de um layout.

As duas abordagens em matéria de migração são as seguintes:

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 aplicações que desativam a compressão e visam o .NET 7 ou versões anteriores, mas são criadas com o SDK do .NET 8, a BlazorEnableCompression propriedade MSBuild foi alterada para CompressionEnabled:

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

Ao usar o comando publish da .NET CLI, utilize a nova propriedade:

dotnet publish -p:CompressionEnabled=false

Para obter mais informações, consulte os seguintes recursos:

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

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

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

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

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

Em vez disso, adicione serviços de estado de autenticação em série à coleção de serviços chamando AddCascadingAuthenticationState no arquivo Program.

builder.Services.AddCascadingAuthenticationState();

Para obter mais informações, consulte os seguintes recursos:

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 aplicativos Blazor nas principais versões e como resolver problemas de cache HTTP.

Para obter mais informações, consulte 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)

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

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

Descubra componentes de montagens adicionais

Ao migrar de uma Blazor Server aplicação para uma Blazor Web App, aceda às orientações em roteamento e navegação do ASP.NET Core Blazor se a aplicação utilizar componentes roteáveis de assemblies adicionais, como bibliotecas de classes de componentes.

Remover 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 Política de autorização 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 Middleware de Arquivos Estáticos (UseStaticFiles) no pipeline de processamento de pedidos antes da chamada para Middleware de Autorização (UseAuthorization) é o suficiente em aplicações .NET 7 para que o Blazor script seja servido a utilizadores anónimos.

No .NET 8, o Blazor Server script é servido por seu próprio ponto de extremidade, usando roteamento de ponto de extremidade. Esta alteração foi introduzida por Correção de erro - Passar opções para UseStaticFiles causa problemas Blazor Server (dotnet/aspnetcore #45897).

Considere um cenário multilocatário onde:

  • As políticas padrão e de fallback são definidas de forma idêntica.
  • O locatário é determinado usando o primeiro segmento no trajeto do pedido (por exemplo, tld.com/tenant-name/...).
  • As solicitações para endpoints do locatário são autenticadas por um esquema de autenticação adicional, que acrescenta uma identidade extra à entidade da solicitação.
  • A política de autorização de fallback 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 no /_framework/blazor.server.js, que é predefinido 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, que resulta no retorno de um resultado não autorizado.

Esse problema está em avaliação para um novo recurso de estrutura 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 da aplicação. Para pontos de extremidade não-blazor, use explicitamente [Authorize] ou RequireAuthorization.

  • Adicione [AllowAnonymous] ao /_framework/blazor.server.js endpoint no Program ficheiro:

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

  • Registe um AuthorizationHandler personalizado que verifica o HttpContext para permitir a passagem do ficheiro /_framework/blazor.server.js.

Docker

Atualizar imagens do Docker

Para aplicativos que usam o Docker, atualize as instruções e os scripts do DockerfileFROM . Use uma imagem base que inclua o tempo de execução 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 porta do Docker

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

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

Para obter mais informações, consulte:

Rever as alterações que quebram

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