Dela via

Migrera från ASP.NET Core i .NET 7 till .NET 8

I den här artikeln beskrivs hur du uppdaterar en befintlig ASP.NET Core i .NET 7-projektet till .NET 8.

Prerequisites

Uppdatera .NET SDK-versionen i global.json

Om du förlitar dig på en global.json fil för att rikta in dig på en specifik .NET SDK-version uppdaterar version du egenskapen till den .NET 8 SDK-version som är installerad. Till exempel:

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

Uppdatera målramverket

Uppdatera projektfilens Target Framework Moniker (TFM) till net8.0:

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

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

</Project>

Uppdatera paketreferenser

I projektfilen uppdaterar du attributet för varje Microsoft.AspNetCore.*, Microsoft.EntityFrameworkCore.*, Microsoft.Extensions.*och System.Net.Http.Json paketreferens Version till 8.0.0 eller senare. Till exempel:

<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

Följande migreringsscenarier beskrivs:

Mer information om hur du lägger Blazor till stöd för en ASP.NET Core-app finns i Integrera ASP.NET Core-komponenter Razor med MVC eller Razor Pages.

Uppdatera en Blazor Server app

Vi rekommenderar att du använder Blazor Web Apps i .NET 8, men Blazor Server stöds. Om du vill fortsätta använda Blazor Server med .NET 8 följer du riktlinjerna i de tre första avsnitten i den här artikeln:

Nya Blazor-funktioner som introduceras för Blazor Web App är inte tillgängliga för en Blazor Server-app som har uppdaterats för att köras under .NET 8. Om du vill använda de nya .NET 8-funktionerna Blazor följer du riktlinjerna i något av följande avsnitt:

Anta alla Blazor Web App konventioner

Om du vill anta alla nya Blazor Web App konventioner rekommenderar vi följande process:

  • Skapa en ny app från projektmallen Blazor Web App . Mer information finns i Verktyg för ASP.NET Core Blazor.
  • Flytta appens komponenter och kod till den nya Blazor Web Appoch gör ändringar för att införa nya funktioner.
  • Uppdatera layouten och formatmallarna för Blazor Web App.

Nya .NET 8-funktioner beskrivs i Nyheter i ASP.NET Core i .NET 8. När du uppdaterar en app från .NET 6 eller tidigare bör du läsa migrerings- och versionsanteckningarna (Nyhetsartiklar) för att få information om de mellanliggande släppen.

Konvertera en Blazor Server app till en Blazor Web App

Blazor Server appar stöds i .NET 8 utan några kodändringar. Använd följande vägledning för att konvertera en Blazor Server app till motsvarande .NET 8 Blazor Web App, vilket gör alla nya .NET 8-funktioner tillgängliga.

Important

Det här avsnittet fokuserar på de minimala ändringar som krävs för att konvertera en .NET 7-app Blazor Server till en .NET 8 Blazor Web App. Om du vill anta alla nya Blazor Web App konventioner följer du riktlinjerna i avsnittet Anta alla Blazor Web App konventioner .

  1. Följ riktlinjerna i de tre första avsnitten i den här artikeln:

  2. Flytta innehållet i komponenten App (App.razor) till en ny Routes komponentfil (Routes.razor) som lagts till i projektets rotmapp. Lämna den tomma App.razor filen i appen i projektets rotmapp.

  3. Lägg till en post i _Imports.razor filen för att göra korta återgivningslägen tillgängliga för appen:

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

  4. Flytta innehållet på _Host sidan (Pages/_Host.cshtml) till den tomma App.razor filen. Fortsätt med att göra följande ändringar i komponenten App .

    Note

    I följande exempel är BlazorServerAppprojektets namnområde . Justera namnområdet så att det matchar projektet.

    Ta bort följande rader överst i filen:

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

    Ersätt föregående rader med en linje som matar in en IHostEnvironment instans:

    @inject IHostEnvironment Env

    Ta bort tilde (~) från href taggen <base> och ersätt med bassökvägen för din app:

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

    Ta bort komponenttaggens hjälp för komponenten HeadOutlet och ersätt den med komponenten HeadOutlet .

    Ta bort följande rad:

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

    Ersätt föregående rad med följande:

    <HeadOutlet @rendermode="InteractiveServer" />

    Ta bort komponenttaggens hjälp för komponenten App och ersätt den med komponenten Routes .

    Ta bort följande rad:

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

    Ersätt föregående rad med följande:

    <Routes @rendermode="InteractiveServer" />

    Note

    Den föregående konfigurationen förutsätter att appens komponenter använder interaktiv serverrendering. Mer information, inklusive hur du använder statisk återgivning på serversidan (SSR), finns i ASP.NET Core-återgivningslägenBlazor.

    Ta bort miljötagghjälparna för felgränssnittet och ersätt dem med följande Razor markering.

    Ta bort följande rader:

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

    Ersätt föregående rader med följande:

    @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>
}

    Ändra skriptet Blazor från blazor.server.js till blazor.web.js:

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

  5. Pages/_Host.cshtml Ta bort filen.

  6. Uppdatera Program.cs:

    Note

    I följande exempel är BlazorServerAppprojektets namnområde . Justera namnområdet så att det matchar projektet.

    Lägg till en using -instruktion överst i filen för projektets namnområde:

    using BlazorServerApp;

    Ersätt AddServerSideBlazor med AddRazorComponents och ett länkat anrop till AddInteractiveServerComponents.

    Ta bort följande rad:

    - builder.Services.AddServerSideBlazor();

    Ersätt föregående rad med Razor komponent- och interaktiva serverkomponenttjänster. Att använda AddRazorComponents lägger till antiforgery-tjänster (AddAntiforgery) som standard.

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

    Ta bort följande rad:

    - app.MapBlazorHub();

    Ersätt föregående rad med ett anrop till MapRazorComponentsoch ange komponenten App som rotkomponenttyp och lägg till ett länkat anrop till AddInteractiveServerRenderMode:

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

    Ta bort följande rad:

    - app.MapFallbackToPage("/_Host");

    Ta bort mellanprogram för routning:

    - app.UseRouting();

    Lägg till Antiforgery Middleware i pipelinen för bearbetning av begärande efter raden som lägger till HTTPS Redirection Middleware (app.UseHttpsRedirection):

    app.UseAntiforgery();

    Föregående anrop till app.UseAntiforgery måste göras efter anrop, om det finns, till app.UseAuthentication och app.UseAuthorization. Det finns inget behov av att uttryckligen lägga till antiforgery-tjänster (builder.Services.AddAntiforgery), eftersom de läggs till automatiskt av AddRazorComponents, som beskrevs tidigare.

  7. Blazor Server Om appen har konfigurerats för att inaktivera prerendering kan du fortsätta att inaktivera prerendering för den uppdaterade appen. I komponenten App ändrar du värdet som tilldelats till @rendermodeRazor direktivattributen för komponenterna HeadOutlet och Routes .

    Ändra värdet för direktivattributet @rendermode för både komponenterna HeadOutlet och Routes för att inaktivera prerendering:

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

    Mer information finns i ASP.NET Core-återgivningslägenBlazor.

Uppdatera en Blazor WebAssembly app

Följ riktlinjerna i de tre första avsnitten i den här artikeln:

För appar som använder lata laddning av sammansättningar, ändra filtillägget från .dll till .wasm i appens implementering för att återspegla Blazor WebAssembly's införande av sammansättningspaketering i Webcil-format.

Före lanseringen av .NET 8 tar vägledningen i distributionslayouten för ASP.NET Core-värdbaserade Blazor WebAssembly appar upp miljöer som blockerar klienter från att ladda ned och köra DLL:er med en kombinationsmetod för flera delar. I .NET 8 eller senare använder Blazor filformatet Webcil för att lösa problemet. Multipart-paketering med hjälp av det experimentella NuGet-paketet som beskrivs i WebAssembly-distributionslayouten stöds inte för Blazor appar i .NET 8 eller senare. Om du vill fortsätta använda paketpaketet för flera delar i .NET 8 eller senare appar kan du använda vägledningen i artikeln för att skapa ett eget NuGet-paket med flera delar, men det stöds inte av Microsoft.

Konvertera en värdbaserad Blazor WebAssembly app till en Blazor Web App

Blazor WebAssembly appar stöds i .NET 8 utan några kodändringar. Använd följande vägledning för att konvertera en ASP.NET Core-värdbaserad Blazor WebAssembly app till motsvarande .NET 8 Blazor Web App, vilket gör alla nya .NET 8-funktioner tillgängliga.

Important

Det här avsnittet fokuserar på de minimala ändringar som krävs för att konvertera en .NET 7-ASP.NET Core-värdbaserad Blazor WebAssembly app till en .NET 8 Blazor Web App. Om du vill anta alla nya Blazor Web App konventioner följer du riktlinjerna i avsnittet Anta alla Blazor Web App konventioner .

  1. Följ riktlinjerna i de tre första avsnitten i den här artikeln:

    Important

    Med hjälp av den tidigare vägledningen uppdaterar du .Client, .Server och .Shared-projekten i lösningen.

  2. .Client Lägg till följande MSBuild-egenskaper i projektfilen (.csproj):

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

    Ta även bort paketreferensen .ClientMicrosoft.AspNetCore.Components.WebAssembly.DevServer i projektfilen:

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

  3. Flytta innehållet i filen från .Client/wwwroot/index.html till en ny komponentfil App (App.razor) som skapats i projektets rot .Server. När du har flyttat filens innehåll tar du bort index.html filen.

    Döp om App.razor i .Client-projektet till Routes.razor.

    I Routes.razoruppdaterar du värdet för attributet AppAssembly till typeof(Program).Assembly.

  4. .Client I projektet lägger du till en post i _Imports.razor filen för att göra korta återgivningslägen tillgängliga för appen:

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

    Gör en kopia av .Client projektets _Imports.razor fil och lägg till den i .Server projektet.

  5. Gör följande ändringar i App.razor filen:

    Ersätt webbplatsens standardwebbplatsrubrik (<title>...</title>) med en HeadOutlet komponent. Observera webbplatsrubriken för senare användning och ta bort rubriktaggar och rubrik:

    - <title>...</title>

    Där du tog bort rubriken placerar du en HeadOutlet komponent som tilldelar interaktiv webassembly-återgivningsläge (prerendering inaktiverad):

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

    Ändra CSS-formatpaketet:

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

    Platshållare i föregående kod:

    • {CLIENT PROJECT ASSEMBLY NAME}: Sammansättningsnamn för klientprojekt. Exempel: BlazorSample.Client
    • {SERVER PROJECT ASSEMBLY NAME}: Namn på serverprojektsammansättning. Exempel: BlazorSample.Server

    Leta upp följande <div>...</div> HTML-kod:

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

    Ersätt föregående <div>...</div> HTML-kod med komponenten Routes med hjälp av interaktiv webassembly-återgivningsläge (prerendering inaktiverad):

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

    Uppdatera skriptet blazor.webassembly.js till blazor.web.js:

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

  6. .Client Öppna projektets layoutfil (.Client/Shared/MainLayout.razor) och lägg till en PageTitle komponent med webbplatsens standardrubrik ({TITLE} platshållare):

    <PageTitle>{TITLE}</PageTitle>

    Note

    Andra layoutfiler bör också få en PageTitle komponent med standardwebbplatsrubriken.

    Mer information finns i Kontrollera huvudinnehåll i ASP.NET Core-apparBlazor.

  7. Ta bort följande rader från .Client/Program.cs:

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

  8. Uppdatera .Server/Program.cs:

    Lägg till Razor komponent- och interaktiva WebAssembly-komponenttjänster i projektet. Anropa AddRazorComponents med ett kedjat anrop till AddInteractiveWebAssemblyComponents. Att använda AddRazorComponents lägger till antiforgery-tjänster (AddAntiforgery) som standard.

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

    Lägg till Antiforgery Middleware i pipelinen för bearbetning av begäranden.

    Placera följande rad efter anropet till app.UseHttpsRedirection. Anropet till app.UseAntiforgery måste göras efter anrop, om det finns, till app.UseAuthentication och app.UseAuthorization. Det finns inget behov av att uttryckligen lägga till antiforgery-tjänster (builder.Services.AddAntiforgery), eftersom de läggs till automatiskt av AddRazorComponents, som beskrevs tidigare.

    app.UseAntiforgery();

    Ta bort följande rad:

    - app.UseBlazorFrameworkFiles();

    Ta bort följande rad:

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

    Ersätt föregående rad med ett anrop till MapRazorComponents, som anger komponenten App som rotkomponenttyp och lägger till länkade anrop till AddInteractiveWebAssemblyRenderMode och AddAdditionalAssemblies:

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

    I det föregående exemplet är platshållaren {CLIENT APP NAMESPACE} namnområdet för projektet .Client (till exempel HostedBlazorApp.Client).

  9. Kör lösningen från .Server projektet:

    För Visual Studio bekräftar du att .Server projektet har valts i Solution Explorer när du kör appen.

    Om du använder .NET CLI kör du projektet från .Server projektets mapp.

Uppdatera konfiguration av tjänst- och slutpunktsalternativ

Med lanseringen av Blazor Web App:er i .NET 8, uppdateras tjänst- och slutpunktskonfigurationen med introduktionen av nya API:er för interaktiva komponenttjänster och komponentslutpunktskonfiguration.

Uppdaterad konfigurationsvägledning visas på följande platser:

Släpp Blazor Server med en lösning för Yarp-routning

Om du tidigare följde vägledningen i Aktivera ASP.NET Core-stöd Blazor Server med Yarp i inkrementell migrering för att migrera en Blazor Server app med Yarp till .NET 6 eller .NET 7 kan du ångra de lösningar som du vidtog när du följde artikelns vägledning. Routning och djuplänkning för Blazor Server med Yarp fungerar korrekt i .NET 8.

Flytta CascadingValue-komponenter till layoutkomponenter

Sammanhängande parametrar skickar inte data över gränser för återgivningsläge och layouter återges statiskt i annars interaktiva appar. Därför kommer appar som försöker använda sammanhängande parametrar i interaktivt renderade komponenter inte att kunna överlappa värdena från en layout.

De två metoderna för migrering är:

Mer information finns i Sammanhängande värden/parametrar och gränser för återgivningsläge.

Migrera MSBuild-egenskapen BlazorEnableCompression

För Blazor WebAssembly appar som inaktiverar komprimering och riktar sig mot .NET 7 eller tidigare men som skapas med .NET 8 SDK, har BlazorEnableCompression-egenskapen för MSBuild ändrats till CompressionEnabled:

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

När du använder .NET CLI-publiceringskommandot använder du den nya egenskapen:

dotnet publish -p:CompressionEnabled=false

Mer information finns i följande resurser:

Migrera komponenten <CascadingAuthenticationState> till sammanhängande autentiseringstillståndstjänster

I .NET 7 eller tidigare omsluts komponenten CascadingAuthenticationState av någon del av gränssnittets träd, till exempel runt routern Blazor , för att tillhandahålla sammanhängande autentiseringstillstånd:

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

Använd inte komponenten CascadingAuthenticationState i .NET 8:

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

Lägg i stället till sammanhängande autentiseringstillståndstjänster i tjänstsamlingen genom att anropa AddCascadingAuthenticationState i Program filen:

builder.Services.AddCascadingAuthenticationState();

Mer information finns i följande resurser:

Ny artikel om problem med HTTP-cachelagring

Vi har lagt till en ny artikel som beskriver några av de vanliga problem med HTTP-cachelagring som kan uppstå när du uppgraderar Blazor appar i större versioner och hur du åtgärdar problem med HTTP-cachelagring.

Mer information finns i Undvik PROBLEM med HTTP-cachelagring när du uppgraderar ASP.NET Core-apparBlazor.

Ny artikel om klassbibliotek med statisk återgivning på serversidan (statisk SSR)

Vi har lagt till en ny artikel som beskriver redigering av komponentbibliotek i Razor klassbibliotek (RCL) med statisk återgivning på serversidan (statisk SSR).

Mer information finns i ASP.NET Core-klassbibliotek Razor (RCL) med statisk återgivning på serversidan (statisk SSR).

Identifiera komponenter från ytterligare sammansättningar

När du migrerar från en Blazor Server app till en Blazor Web Appfår du åtkomst till vägledningen i ASP.NET Core-routning Blazor och navigering om appen använder dirigerbara komponenter från ytterligare sammansättningar, till exempel komponentklassbibliotek.

Släpp [Parameter] attribut när parametern anges från en frågesträng

Attributet [Parameter] krävs inte längre när du anger en parameter från frågesträngen:

- [Parameter]
  [SupplyParameterFromQuery]

Blazor Server skriptåterställningsprincipauktorisering

I .NET 7 hanteras skriptet Blazor Server (blazor.server.js) av Static File Middleware. Att anropa Static File Middleware (UseStaticFiles) i pipelinen för bearbetning av begäran innan anropet till Authorization Middleware (UseAuthorization) räcker i .NET 7-appar för att hantera skriptet Blazor till anonyma användare.

I .NET 8 hanteras skriptet Blazor Serverav en egen slutpunkt med hjälp av slutpunktsroutning. Den här ändringen introduceras av Åtgärdat fel – Att skicka alternativ till UseStaticFiles orsakar fel Blazor Server (dotnet/aspnetcore #45897).

Överväg ett scenario med flera hyresgäster där:

  • Både standardprinciperna och återställningsprinciperna anges på samma sätt.
  • Hyresgästen löses med hjälp av det första segmentet i begäransökvägen (till exempel tld.com/tenant-name/...).
  • Begäranden till klientslutpunkter autentiseras av ytterligare ett autentiseringsschema, vilket lägger till ytterligare en identitet i begärandeobjektet.
  • Reservauktoriseringsprincipen har krav som kontrollerar anspråk via den ytterligare identiteten.

Begäranden för Blazor skriptfilen (blazor.server.js) hanteras på /_framework/blazor.server.js, som är hårdkodad i ramverket. Begäranden om filen autentiseras inte av det ytterligare autentiseringsschemat för klienter , men de utmanas fortfarande av reservpolicyn, vilket resulterar i att ett obehörigt resultat returneras.

Det här problemet utvärderas för en ny funktion i ramverket MapRazorComponents, som är oförenligt med FallbackPolicy RequireAuthenticatedUser (dotnet/aspnetcore 51836), och som för närvarande är planerad till .NET 9:s lansering i november 2024. Tills dess kan du kringgå det här problemet med någon av följande tre metoder:

  • Använd inte en reservstrategi. [Authorize] Använd attributet i _Imports.razor filen för att tillämpa det på alla komponenter i appen. För icke-blazor-slutpunkter använder [Authorize] du explicit eller RequireAuthorization.

  • Lägg till [AllowAnonymous] i slutpunkten /_framework/blazor.server.js i filen Program.

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

  • Registrera en anpassad AuthorizationHandler som kontrollerar HttpContext för att tillåta /_framework/blazor.server.js filen.

Docker

Uppdatera Docker-avbildningar

För appar som använder Docker uppdaterar du Dockerfile-instruktionerFROM och skript. Använd en grundbild som innehåller .NET 8-körmiljön. Överväg följande docker pull kommandoskillnad mellan ASP.NET Core i .NET 7 och .NET 8:

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

Uppdatera Docker-port

Standardporten ASP.NET Core som konfigurerats i .NET-containeravbildningar har uppdaterats från port 80 till 8080.

Den nya ASPNETCORE_HTTP_PORTS miljövariabeln lades till som ett enklare alternativ till ASPNETCORE_URLS.

Mer information finns i:

Brytande förändringar

Använd artiklarna i Icke-bakåtkompatibla ändringar i .NET för att hitta icke-bakåtkompatibla ändringar som kan gälla när du uppgraderar en app till en nyare version av .NET.