Migrieren von ASP.NET Core in .NET 10 zu ASP.NET Core in .NET 11

In diesem Artikel wird erläutert, wie Sie eine ASP.NET Core in .NET 10 auf ASP.NET Core in .NET 11 aktualisieren.

Voraussetzungen

Aktualisieren Sie die .NET SDK-Version in global.json

Wenn Sie auf eine global.json Datei angewiesen sind, um eine bestimmte .NET SDK-Version zu verwenden, aktualisieren Sie die version Eigenschaft auf die .NET 11 SDK-Version, die installiert ist. Beispiel:

{
  "sdk": {
-    "version": "10.0.102"
+    "version": "11.0.100"
  }
}

Aktualisieren des Zielframeworks

Aktualisieren Sie das Target Framework Moniker (TFM) der Projektdatei auf net11.0:

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

  <PropertyGroup>
-    <TargetFramework>net10.0</TargetFramework>
+    <TargetFramework>net11.0</TargetFramework>
  </PropertyGroup>

</Project>

Aktualisieren von Paketverweisen

Aktualisieren Sie in der Projektdatei das Microsoft.AspNetCore.*-Attribut jedes Paketverweises vom Typ Microsoft.EntityFrameworkCore.*, Microsoft.Extensions.*, System.Net.Http.Json und Version auf 11.0.0 oder höher. Beispiel:

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

Blazor

Blazor Versionshinweise

Informationen zur neuen Featureabdeckung finden Sie unter Neuigkeiten in ASP.NET Core in .NET 11.

Einführung des Inlineereignishandlers JS aus der NavMenu-Komponente entfernt

Dieser Abschnitt gilt nur für Blazor Web Apps.

Der Inlineereignishandler JS für den Navigationsleisten-Umschalter ist in der NavMenu-Komponente der Blazor Web App-Projektvorlage in .NET 11 oder höher nicht vorhanden. Apps, die aus der Projektvorlage generiert wurden, verwenden einen verbundbasierten JS Modulansatz , um die Navigationslinks auf der gerenderten Seite ein- oder auszublenden. Der Ansatz verbessert die Compliance der Inhaltssicherheitsrichtlinie (Content Security Policy, CSP), da die CSP keinen unsicheren Hash für die Inline JSenthalten muss.

Verwenden Sie die folgenden Anweisungen, um den neuen JS Modulansatz für den Toggler der Navigationslinks in einer vorhandenen App anzuwenden.

Fügen Sie ein nebeneinanderliegendes JS Modul neben der NavMenu App-Komponente hinzu.

NavMenu.razor.js:

// Handle navigation menu toggle
const navScrollable = document.getElementById("nav-scrollable");
const navToggler = document.querySelector(".navbar-toggler");

if (navScrollable && navToggler) {
    navScrollable.addEventListener("click", function() {
        navToggler.click();
    });
}

Fügen Sie oben in der App-Komponente NavMenu (NavMenu.razor) ein <script> Tag für das verbundene JS Modul hinzu:

• Wenn die App clientseitiges Rendering verwendet (ein Projekt hat .Client ) mit globaler Interaktivität (der Rendermodus wird global für die App durch die App-Komponente App festgelegt), verwenden Sie das folgende Tag, das den Pfad zum Modul im Layout Ordner angibt:

<script type="module" src="@Assets["Layout/NavMenu.razor.js"]"></script>

• Verwenden Sie andernfalls das folgende Tag, das den Pfad zum Modul im Components/Layout Ordner angibt:

<script type="module" src="@Assets["Components/Layout/NavMenu.razor.js"]"></script>

Ändern Sie darüber hinaus in der Komponente NavMenu der App die Zeile, die die Inline-JS hat, um die Navigationslinks umzuschalten:

- <div class="nav-scrollable" onclick="document.querySelector('.navbar-toggler').click()">
+ <div id="nav-scrollable" class="nav-scrollable">

Wenn die App über eine Inhaltssicherheitsrichtlinie (Content Security Policy, CSP) mit einem unsicheren Hash für die Inline JS verfügt, die im vorherigen Schritt entfernt wurde, entfernen Sie den unsicheren Hash:

- 'unsafe-hashes' 'sha256-qnHnQs7NjQNHHNYv/I9cW+I62HzDJjbnyS/OFzqlix0='

QuickGrid verwendet URL-basierte Paginierung und Sortierung

QuickGrid Komponente speichert Paginierungs- und Sortierzustand im URL-Abfragestring (zum Beispiel ?page=2&sort=Name&order=asc), was das Teilen von Links, die Rückwärts-/Vorwärtsnavigation im Browser und den Betrieb unter statischem serverseitigem Rendering (static SSR) ermöglicht. Dieses Verhalten ist standardmäßig aktiviert.

Um ohne eine JavaScript-Laufzeit zu arbeiten, rendern sortierbare Spaltenüberschriften und Paginatorsteuerelemente jetzt anstelle von <a> Elementen als <button> (Link)-Elemente. Aktualisieren Sie alle benutzerdefinierten CSS-Dateien, die auf das vorherige Markup ausgerichtet sind:

- button.col-title { ... }
+ button.col-title, a.col-title { ... }
- nav button:disabled { ... }
+ nav button:disabled, nav a[aria-disabled="true"] { ... }

Deaktivierte Paginatorlinks verwenden aria-disabled="true" anstelle des HTML-Attributs disabled , das für <a> Elemente nicht gültig ist. Das integrierte QuickGrid CSS deckt bereits beide Markupformatvorlagen ab.

Wenn mehr als ein QuickGrid auf derselben Seite gerendert wird, legen Sie für jedes Raster ein eindeutiges QueryParameterNamePrefix fest (und geben Sie jedem ein eigenes PaginationState), um zu verhindern, dass die Raster dieselben Abfrageparameter für Seite, Sortierung und Reihenfolge verwenden:

- <QuickGrid Items="@cities" Pagination="@pagination2">...</QuickGrid>
+ <QuickGrid Items="@cities" Pagination="@pagination2" QueryParameterNamePrefix="cities">...</QuickGrid>

Wenn Sie zum vorherigen <button>- basierten Markup zurückkehren möchten, für das ein interaktiver Rendermodus erforderlich ist, legen Sie den folgenden AppContext-Switch auf "false" fest:

AppContext.SetSwitch(
    "Microsoft.AspNetCore.Components.QuickGrid.EnableUrlBasedQuickGridNavigationAndSorting",
    false);

Der Schalter steuert nur das gerenderte HTML-Element; Sortier- und Seitenzustand wird unabhängig von der Einstellung aus gelesen und in die URL-Abfragezeichenfolge geschrieben.

Sicherheit

Automatischer CSRF-Schutz

.NET 11 fügt automatischen Cross-Site Request Forgery (CSRF)-Schutz hinzu. Wenn eine App mit WebApplication.CreateBuilder erstellt wird und Endpunkte hat, wird standardmäßig eine Middleware konfiguriert, die die Header Sec-Fetch-Site und Origin überprüft und ein Validierungsergebnis für die Anfrage aufzeichnet.

Die Middleware validiert Endpunkte, die für die Antiforgery-Validierung aktiviert sind – also Endpunkte mit Metadaten, die IAntiforgeryMetadata implementieren, wobei RequiresValidationtrue ist. Das Framework legt dies automatisch für Folgendes fest:

• Alle Blazor Endpunkte für serverseitiges Rendering (SSR). Jede ist standardmäßig geschützt; eine Seite kann sich abmelden mit @attribute [RequireAntiforgeryToken(false)].
• Minimale API-Endpunkte, die Formulardaten binden.
• MVC-Aktionen, bei denen die Antiforgery-Überprüfung verwendet wird, beispielsweise solche, die mit [ValidateAntiForgeryToken] oder [AutoValidateAntiforgeryToken] versehen sind.

Endpunkte, die JSON binden, z. B. eine einfache MapPost oder eine Web-API-Aktion [HttpPost] , haben keine Verhaltensänderung.

In Zukunft ist der automatische CSRF-Schutz die empfohlene Verteidigung, und die meisten Apps benötigen das tokenbasierte Antiforgery-System nicht mehr. Behalten Sie das tokenbasierte System bei, wenn die App Browser unterstützen muss, die Sec-Fetch-Site nicht senden, IAntiforgeryAdditionalDataProvider verwenden oder den tokenbasierten Schutz aufgrund einer Compliance-Anforderung als unabhängige Ebene beibehalten müssen. Beide Schutzmaßnahmen können koexistieren.

Um eine App zu vereinfachen, die den Fälschungsschutz explizit konfiguriert, entfernen Sie die Aufrufe AddAntiforgery und UseAntiforgery und setzen Sie stattdessen auf den automatischen Schutz. Für die meisten Apps ist dies eine einzeilige Änderung ohne andere Codeaktualisierungen. Bei Blazor statischem SSR wird durch das Entfernen von app.UseAntiforgery() auch die Generierung von Antiforgery-Token für gerenderte Formulare beendet. Weitere Informationen finden Sie unter BlazorServerseitiges Rendering verschiebt die Antiforgery-Validierung auf die Middleware.

Ein 400 - Bad Request bei einem ursprungsübergreifenden Formularbeitrag bedeutet, dass der CSRF-Schutz wie vorgesehen funktioniert. Wenn die Anforderung von einem legitimen Ursprung stammt, erlauben Sie diesen Ursprung, anstatt die Überprüfung zu unterdrücken:

• Konfigurieren Sie CORS so, dass die für den Endpunkt ermittelte Richtlinie die Origin des Aufrufers enthält. Die CSRF-Middleware berücksichtigt diese Richtlinie und lässt die Anforderung zu.
• Deaktivieren Sie einen Endpunkt nur mit .DisableAntiforgery() (minimalen APIs) oder [IgnoreAntiforgeryToken] (MVC), wenn er nicht anfällig für CSRF ist, z. B. einen Endpunkt, der nicht über einen Browser erreichbar ist oder sich mit einem Nicht-Mechanismuscookie authentifiziert (z. B. Bearerauthentifizierung).

Eine vollständige Beschreibung der Middleware, der Validierungsregeln und deren Interaktion mit dem tokenbasierten Antiforgery-System finden Sie unter "Automatischer CSRF-Schutz in ASP.NET Core".

Bahnbrechende Änderungen

Verwenden Sie die Artikel in "Breaking changes in .NET ", um nach wichtigen Änderungen zu suchen, die beim Aktualisieren einer App auf eine neuere Version von .NET gelten können.