Migrieren von ASP.NET Core 3.1 zu 5.0

Artikel
11/30/2023

In diesem Artikel wird erläutert, wie Sie ein vorhandenes ASP.NET Core 3.1-Projekt auf ASP.NET Core 5.0 aktualisieren. Anweisungen zum Migrieren von ASP.NET Core 3.1 zu ASP.NET Core 6.0 finden Sie unter Migrieren von ASP.NET Core 3.1 zu 6.0.

Voraussetzungen

Visual Studio 2019 Version 16.8 oder höher mit der Workload ASP.NET und Webentwicklung
.NET 5.0 SDK

Aktualisieren der .NET Core SDK-Version in „global.json“

Wenn Sie eine Datei global.json für eine bestimmte .NET Core SDK-Version benötigen, aktualisieren Sie die version-Eigenschaft auf die installierte .NET 5.0 SDK-Version. Beispiel:

{
  "sdk": {
-    "version": "3.1.200"
+    "version": "5.0.100"
  }
}

Aktualisieren des Zielframeworks

Falls Sie ein Blazor WebAssembly-Projekt aktualisieren, fahren Sie mit dem Abschnitt Aktualisieren von Blazor WebAssembly-Projekten fort. Aktualisieren Sie für alle anderen ASP.NET Core-Projekttypen den Zielframeworkmoniker (Target Framework Moniker, TFM) der Projektdatei auf net5.0:

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

  <PropertyGroup>
-    <TargetFramework>netcoreapp3.1</TargetFramework>
+    <TargetFramework>net5.0</TargetFramework>
  </PropertyGroup>

</Project>

Löschen der Ordner `bin` und `obj`

Möglicherweise müssen Sie die Ordner bin und obj löschen. Führen Sie dotnet nuget locals --clear all aus, um den NuGet-Paketcache zu löschen.

Änderungen der Blazor-App-Routinglogik in Version 5.0.1 und weiteren 5.x-Versionen bis 6.0

Die Berechnung der Routingrangfolge wurde im Patchrelease ASP.NET Core 5.0.1 geändert. Dies kann Sie betreffen, wenn Sie Catch-All-Routen oder Routen mit optionalen Parametern definiert haben.

Altes Verhalten

Beim vorherigen Verhalten in ASP.NET Core 5.0.0 oder früher werden Routen mit niedrigerer Rangfolge (z. B. {*slug}) vor Routen mit höherer Rangfolge (z. B. /customer/{id}) abgeglichen.

Neues Verhalten

Das neue Verhalten in ASP.NET Core 5.0.1 oder höher entspricht eher dem Routingverhalten, das in ASP.NET Core-Apps definiert ist, wobei das Framework zuerst die Routingrangfolge für jedes Segment berechnet und festlegt und die Länge der Route nur als sekundäres Kriterium verwendet, um Verbindungen aufzulösen.

Grund für die Änderung

Das ursprüngliche Verhalten wird als Fehler in der Implementierung betrachtet, da sich das Blazor-Routingsystem für die Teilmenge der Features, die vom Blazor-Routing unterstützt werden, genauso verhalten soll wie das ASP.NET Core-Routingsystem.

Empfohlene Maßnahme

Fügen Sie der Router-Komponente in der Datei App.razor das PreferExactMatches-Attribut hinzu, um das richtige Verhalten zu aktivieren:

<Router AppAssembly="@typeof(Program).Assembly" PreferExactMatches="@true">

Wenn PreferExactMatches auf @true festgelegt ist, bevorzugt die Routenzuordnung exakte Übereinstimmungen gegenüber Platzhaltern.

Wichtig

Alle Apps sollten PreferExactMatches explizit auf @true festlegen.

Die Möglichkeit, PreferExactMatches auf @false oder nicht festzulegen, wird nur zu Zwecken der Abwärtskompatibilität bereitgestellt.

Wenn .NET 6 veröffentlicht wird, bevorzugt der Router immer genaue Übereinstimmungen, und die Option PreferExactMatches ist nicht verfügbar.

Aktualisieren von Blazor WebAssembly- und Blazor Server-Projekten

Der Leitfaden in diesem Abschnitt gilt für beide Blazor-Hostingmodelle. Die Abschnitte nach diesem Abschnitt enthalten zusätzliche spezifische Anleitungen für Hostingmodelle und App-Typen. Verwenden Sie den Leitfaden für alle relevanten Abschnitte Ihrer App.

Fügen Sie in der Datei wwwroot/index.html einer Blazor WebAssembly-App oder der Datei Pages/_Host.cshtml einer Blazor Server-App dem <head>-Element für Formatvorlagen ein <link>-Element hinzu. In den folgenden href-Attributwerten im <link>-Element ist der Platzhalter {ASSEMBLY NAME} der Assemblyname der App.
```
+<link href="{ASSEMBLY NAME}.styles.css" rel="stylesheet" />
```
Beispiel für eine eigenständige Blazor WebAssembly- oder Blazor Server-App:
```
+<link href="BlazorSample.styles.css" rel="stylesheet" />
```
Beispiel für das Client-Projekt einer gehosteten Blazor WebAssembly-Projektmappe:
```
+<link href="BlazorSample.Client.styles.css" rel="stylesheet" />
```

Fügen Sie in der Datei _Imports.razor der App einen neuen Namespace für die Komponentenvirtualisierung hinzu, Microsoft.AspNetCore.Components.Web.Virtualization. Die folgenden _Imports.razor-Dateien enthalten die Standardnamespaces in Apps, die aus den Blazor-Projektvorlagen generiert werden. Der Platzhalter {ASSEMBLY NAME} ist der Assemblyname der App.

Blazor WebAssembly (_Imports.razor):

@using System.Net.Http
@using System.Net.Http.Json
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.AspNetCore.Components.Web.Virtualization
@using Microsoft.AspNetCore.Components.WebAssembly.Http
@using Microsoft.JSInterop
@using {ASSEMBLY NAME}
@using {ASSEMBLY NAME}.Shared

Blazor Server (_Imports.razor):

@using System.Net.Http
@using Microsoft.AspNetCore.Authorization
@using Microsoft.AspNetCore.Components.Authorization
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.AspNetCore.Components.Web.Virtualization
@using Microsoft.JSInterop
@using {ASSEMBLY NAME}
@using {ASSEMBLY NAME}.Shared

Umschließen Sie in der MainLayout-Komponente (Shared/MainLayout.razor) das HTML-Markup der Komponente mit einem <div>-Element, dessen class-Attribut auf page festgelegt ist:
```
<div class="page">

    ...

</div>
```

Fügen Sie dem Ordner Shared die folgenden Dateien hinzu:

MainLayout.razor.css:

.page {
    position: relative;
    display: flex;
    flex-direction: column;
}

.main {
    flex: 1;
}

.sidebar {
    background-image: linear-gradient(180deg, rgb(5, 39, 103) 0%, #3a0647 70%);
}

.top-row {
    background-color: #f7f7f7;
    border-bottom: 1px solid #d6d5d5;
    justify-content: flex-end;
    height: 3.5rem;
    display: flex;
    align-items: center;
}

    .top-row ::deep a, .top-row .btn-link {
        white-space: nowrap;
        margin-left: 1.5rem;
    }

    .top-row a:first-child {
        overflow: hidden;
        text-overflow: ellipsis;
    }

@media (max-width: 767.98px) {
    .top-row:not(.auth) {
        display: none;
    }

    .top-row.auth {
        justify-content: space-between;
    }

    .top-row a, .top-row .btn-link {
        margin-left: 0;
    }
}

@media (min-width: 768px) {
    .page {
        flex-direction: row;
    }

    .sidebar {
        width: 250px;
        height: 100vh;
        position: sticky;
        top: 0;
    }

    .top-row {
        position: sticky;
        top: 0;
        z-index: 1;
    }

    .main > div {
        padding-left: 2rem !important;
        padding-right: 1.5rem !important;
    }
}

NavMenu.razor.css:

.navbar-toggler {
    background-color: rgba(255, 255, 255, 0.1);
}

.top-row {
    height: 3.5rem;
    background-color: rgba(0,0,0,0.4);
}

.navbar-brand {
    font-size: 1.1rem;
}

.oi {
    width: 2rem;
    font-size: 1.1rem;
    vertical-align: text-top;
    top: -2px;
}

.nav-item {
    font-size: 0.9rem;
    padding-bottom: 0.5rem;
}

    .nav-item:first-of-type {
        padding-top: 1rem;
    }

    .nav-item:last-of-type {
        padding-bottom: 1rem;
    }

    .nav-item ::deep a {
        color: #d7d7d7;
        border-radius: 4px;
        height: 3rem;
        display: flex;
        align-items: center;
        line-height: 3rem;
    }

.nav-item ::deep a.active {
    background-color: rgba(255,255,255,0.25);
    color: white;
}

.nav-item ::deep a:hover {
    background-color: rgba(255,255,255,0.1);
    color: white;
}

@media (min-width: 768px) {
    .navbar-toggler {
        display: none;
    }

    .collapse {
        /* Never collapse the sidebar for wide screens */
        display: block;
    }
}

Die neueste Basisdatei wwwroot/css/app.css einer Blazor WebAssembly-App oder Datei wwwroot/css/site.css einer Blazor Server-App enthält die folgenden Formatvorlagen. Entfernen Sie zusätzliche Formatvorlagen, und behalten Sie die folgenden Formatvorlagen sowie alle anderen Formatvorlagen bei, die Sie der App hinzugefügt haben.

Das folgende Stylesheet enthält nur Basisformatvorlagen und keine von Entwickler*innen hinzugefügten benutzerdefinierten Formatvorlagen:

html, body {
    font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
}

a, .btn-link {
    color: #0366d6;
}

.btn-primary {
    color: #fff;
    background-color: #1b6ec2;
    border-color: #1861ac;
}

.content {
    padding-top: 1.1rem;
}

.valid.modified:not([type=checkbox]) {
    outline: 1px solid #26b050;
}

.invalid {
    outline: 1px solid red;
}

.validation-message {
    color: red;
}

#blazor-error-ui {
    background: lightyellow;
    bottom: 0;
    box-shadow: 0 -1px 2px rgba(0, 0, 0, 0.2);
    display: none;
    left: 0;
    padding: 0.6rem 1.25rem 0.7rem 1.25rem;
    position: fixed;
    width: 100%;
    z-index: 1000;
}

#blazor-error-ui .dismiss {
    cursor: pointer;
    position: absolute;
    right: 0.75rem;
    top: 0.5rem;
}

Hinweis

Im obigen Beispiel wird die @import-Anweisung für Open Iconic-Symbole (open-iconic-bootstrap.css), die von der Blazor-Projektvorlage bereitgestellt werden, nicht gezeigt. Open Iconic wurde von den Verantwortlichen eingestellt.

Aktualisieren von Blazor WebAssembly Projekten

Befolgen Sie die Anleitungen im vorherigen Abschnitt Aktualisieren von Blazor WebAssembly- und Blazor Server-Projekten.

Wenden Sie für ein Blazor WebAssembly-Projekt, einschließlich des Client-Projekts einer gehosteten Blazor-Projektmappe, die folgenden Änderungen auf die Projektdatei an:

Aktualisieren Sie das SDK von Microsoft.NET.Sdk.Web auf Microsoft.NET.Sdk.BlazorWebAssembly:
```
- <Project Sdk="Microsoft.NET.Sdk.Web">
+ <Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">
```
Hinweis

Dieses Update gilt nur für eigenständige Blazor WebAssembly-Projekte und die Client-Projekte von gehosteten Blazor-Projektmappen.

Aktualisieren Sie die folgenden Eigenschaften:

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

  <PropertyGroup>
-     <TargetFramework>netstandard2.1</TargetFramework>
-     <RazorLangVersion>3.0</RazorLangVersion>
+     <TargetFramework>net5.0</TargetFramework>
  </PropertyGroup>

Entfernen Sie den Paketverweis auf Microsoft.AspNetCore.Components.WebAssembly.Build:

<ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.Build" Version="3.2.1" PrivateAssets="all" />

Aktualisieren Sie andere Pakete auf die aktuellen Versionen. Die aktuellen Versionen finden Sie auf NuGet.org.
Ändern Sie in wwwroot/index.html das Element, das die App-Komponente lädt, in ein <div>-Element, dessen id auf app festgelegt ist:
```
-<app>Loading...</app>
+<div id="app">Loading...</div>
```
Ändern Sie in Program.Main (Program.cs) den Verweis auf das <app>-Element in einen CSS-Selektor (Cascading Stylesheets), indem Sie diesem einen #-Hash hinzufügen:
```
-builder.RootComponents.Add<App>("app");
+builder.RootComponents.Add<App>("#app");
```

Ändern Sie, falls vorhanden, in Program.Main (Program.cs) eine vorübergehende HttpClient-Standardregistrierung in eine bereichsbezogene Registrierung:

-builder.Services.AddTransient(sp => new HttpClient 
-    { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });
+builder.Services.AddScoped(sp => new HttpClient 
+    { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });

Führen Sie in der Datei Program.Main (Program.cs) der Client-App von gehosteten Blazor-Projektmappen die folgenden Schritte aus:

Ersetzen Sie optional Clientbasisadressen im Zeichenfolgenformat durch builder.HostEnvironment.BaseAddress.
Ändern Sie alle benannten vorübergehenden Clientfactoryregistrierungen in bereichsbezogene Registrierungen.

-builder.Services.AddHttpClient("{APP NAMESPACE}.ServerAPI", 
-    client => client.BaseAddress = new Uri("https://localhost:5001"))
-    .AddHttpMessageHandler<BaseAddressAuthorizationMessageHandler>();
-builder.Services.AddTransient(sp => sp.GetRequiredService<IHttpClientFactory>()
-    .CreateClient("{APP NAMESPACE}.ServerAPI"));
+builder.Services.AddHttpClient("{APP NAMESPACE}.ServerAPI", 
+    client => client.BaseAddress = new Uri(builder.HostEnvironment.BaseAddress))
+    .AddHttpMessageHandler<BaseAddressAuthorizationMessageHandler>();
+builder.Services.AddScoped(sp => sp.GetRequiredService<IHttpClientFactory>()
+    .CreateClient("{APP NAMESPACE}.ServerAPI"));

Im obigen Code steht der Platzhalter {APP NAMESPACE} für den Namespace der App.

Eigenständige Blazor WebAssembly-App mit Microsoft-Konten

Befolgen Sie die Anweisungen in den vorherigen Abschnitten Aktualisieren von Blazor WebAssembly- und Blazor Server-Projekten und Aktualisieren von Blazor WebAssembly-Projekten.

Für eine eigenständige Blazor WebAssembly-App, die im Azure-Portal zur Verwendung von Microsoft Entra ID (ME-ID) für Microsoft-Konten registriert ist:

Für die App sind die Bereiche openid und offline_access erforderlich:

options.ProviderOptions.DefaultAccessTokenScopes.Add("openid");
options.ProviderOptions.DefaultAccessTokenScopes.Add("offline_access");

Gehen Sie auf dem Blatt Authentifizierung der App-Registrierung im Azure-Portal wie folgt vor:
1. Entfernen Sie die Web-Plattformkonfiguration.
2. Fügen Sie eine Konfiguration vom Typ Single-Page-Webanwendung mit dem Umleitungs-URI der App hinzu.
3. Deaktivieren Sie Implizite Genehmigung für Zugriffstoken und ID-Token.

Weitere Informationen finden Sie unter Sichern einer eigenständigen ASP.NET Core-Blazor WebAssembly-App mit Microsoft-Konten.

Eigenständige Blazor WebAssembly-App mit Microsoft Entra ID (ME-ID)

Befolgen Sie die Anweisungen in den vorherigen Abschnitten Aktualisieren von Blazor WebAssembly- und Blazor Server-Projekten und Aktualisieren von Blazor WebAssembly-Projekten.

Für eine eigenständige Blazor WebAssembly-App, die im Azure-Portal zur Verwendung von Microsoft Entra ID (ME-ID) registriert ist:

Die App erfordert den Bereich https://graph.microsoft.com/User.Read:

options.ProviderOptions.DefaultAccessTokenScopes
    .Add("https://graph.microsoft.com/User.Read");

Gehen Sie auf dem Blatt Authentifizierung der App-Registrierung im Azure-Portal wie folgt vor:
1. Entfernen Sie die Web-Plattformkonfiguration.
2. Fügen Sie eine Konfiguration vom Typ Single-Page-Webanwendung mit dem Umleitungs-URI der App hinzu.
3. Deaktivieren Sie Implizite Genehmigung für Zugriffstoken und ID-Token.

Weitere Informationen finden Sie unter Sichern einer eigenständigen ASP.NET Core-Blazor WebAssembly-App mit Microsoft Entra ID.

Eigenständige Blazor WebAssembly-App mit Azure Active Directory (AAD) B2C

Befolgen Sie die Anweisungen in den vorherigen Abschnitten Aktualisieren von Blazor WebAssembly- und Blazor Server-Projekten und Aktualisieren von Blazor WebAssembly-Projekten.

Für eine eigenständige Blazor WebAssembly-App, die im Azure-Portal zur Verwendung von Azure Active Directory (AAD) B2C registriert ist:

Für die App sind die Bereiche openid und offline_access erforderlich:

options.ProviderOptions.DefaultAccessTokenScopes.Add("openid");
options.ProviderOptions.DefaultAccessTokenScopes.Add("offline_access");

Gehen Sie auf dem Blatt Authentifizierung der App-Registrierung im Azure-Portal wie folgt vor:
1. Entfernen Sie die Web-Plattformkonfiguration.
2. Fügen Sie eine Konfiguration vom Typ Single-Page-Webanwendung mit dem Umleitungs-URI der App hinzu.
3. Deaktivieren Sie Implizite Genehmigung für Zugriffstoken und ID-Token.

Weitere Informationen finden Sie unter Sichern einer eigenständigen ASP.NET Core-Blazor WebAssembly-App mit Azure Active Directory B2C.

Gehostete Blazor WebAssembly-App mit Microsoft Entra ID (ME-ID) oder AAD B2C

Befolgen Sie die Anweisungen in den vorherigen Abschnitten Aktualisieren von Blazor WebAssembly- und Blazor Server-Projekten und Aktualisieren von Blazor WebAssembly-Projekten.

Für die Client-App-Registrierung einer gehosteten Blazor-Projektmappe, die AAD oder AAD B2C für die Benutzerauthentifizierung verwendet, sollte die Azure-Apps-Plattformkonfiguration Single-Page-Webanwendung verwendet werden.

Gehen Sie auf dem Blatt Authentifizierung für die Client-App-Registrierung im Azure-Portal wie folgt vor:

Entfernen Sie die Web-Plattformkonfiguration.
Fügen Sie eine Konfiguration vom Typ Single-Page-Webanwendung mit dem Umleitungs-URI der App hinzu.
Deaktivieren Sie Implizite Genehmigung für Zugriffstoken und ID-Token.

Weitere Informationen finden Sie unter:

Aktualisieren des Server-Projekts einer gehosteten Blazor-Projektmappe

Befolgen Sie die Anweisungen in den vorherigen Abschnitten:

Aktualisieren von Blazor WebAssembly- und Blazor Server-Projekten
Aktualisieren von Blazor WebAssembly-Projekten
Abschnitt, der für den Anbieter der App mit Azure Active Directory gilt:

Aktualisieren Sie das Server-Projekt einer gehosteten Blazor-Projektmappe als ASP.NET Core-App gemäß dem allgemeinen Leitfaden in diesem Artikel.

Darüber hinaus sollten Server-Projekte, die Benutzer*innen bei Blazor WebAssembly-Client-Apps mit Microsoft Entra ID (ME-ID) oder B2C authentifizieren, neue Microsoft Identity v2.0-Pakete verwenden:

Für AAD:

-<PackageReference Include="Microsoft.AspNetCore.Authentication.AzureAD.UI" Version="..." />
+<PackageReference Include="Microsoft.Identity.Web" Version="{VERSION}" />
+<PackageReference Include="Microsoft.Identity.Web.UI" Version="{VERSION}" />

Für AAD B2C:

-<PackageReference Include="Microsoft.AspNetCore.Authentication.AzureADB2C.UI" Version="..." />
+<PackageReference Include="Microsoft.Identity.Web" Version="{VERSION}" />
+<PackageReference Include="Microsoft.Identity.Web.UI" Version="{VERSION}" />

Bestimmen Sie für die vorherigen Paketverweise die Paketversionen für die {VERSION}-Platzhalter auf NuGet.org:

Hinweis

Das SDK des Server-Projekts in einer gehosteten Blazor WebAssembly-Projektmappe bleibt Microsoft.NET.Sdk.Web:

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

Weitere Informationen finden Sie unter:

Bereinigen und Neuerstellen des Projekts

Nach der Migration der App oder Projektmappe zu .NET 5 bereinigen Sie die App oder Projektmappe, und erstellen Sie sie neu. Wenn Paketinkompatibilitäten zwischen neuen Paketverweisen und zwischengespeicherten Paketen bestehen:

Löschen Sie NuGet-Paketcaches, indem Sie den folgenden Befehl dotnet nuget locals in einer Befehlsshell ausführen:
```
dotnet nuget locals --clear all
```
Bereinigen Sie die App oder Projektmappe, und erstellen Sie sie neu.

Problembehandlung

Befolgen Sie den Leitfaden zur Problembehandlung am Ende des Themas zur Sicherheit von Blazor WebAssembly, der für Ihre App gilt:

Eigenständige Blazor WebAssembly-Apps:

Gehostete Blazor WebAssembly-Apps:

Nicht autorisierter Client für Microsoft Entra ID (ME-ID)

Nach dem Aktualisieren einer Blazor WebAssembly-App, die AAD für die Authentifizierung verwendet, erhalten Sie möglicherweise die folgende Fehlermeldung beim Anmelderückruf an die App, nachdem sich die Benutzer*innen mit AAD angemeldet haben:

Info: Die Autorisierung von Microsoft.AspNetCore.Authorization.DefaultAuthorizationService[2] Authorization ist fehlgeschlagen. Diese Anforderungen wurden nicht erfüllt: DenyAnonymousAuthorizationRequirement: Erfordert einen authentifizierten Benutzer.

Anmelderückruffehler von AAD:

Fehler: unauthorized_client
Description (Beschreibung): AADB2C90058: The provided application is not configured to allow public clients.

So beheben Sie den Fehler

Greifen Sie im Azure-Portal auf das Manifest der App zu.
Legen Sie das Attribut allowPublicClient auf null oder true fest.

Aktualisieren einer progressiven Blazor-Web-App (PWA)

Fügen Sie der Projektdatei der PWA-App das folgende Element hinzu:

<ItemGroup>
  <ServiceWorker Include="wwwroot\service-worker.js" 
    PublishedContent="wwwroot\service-worker.published.js" />
</ItemGroup>

Entfernen des Stylesheetlinks der Preview-CSS-Isolation

Wenn die Datei wwwroot/index.html (Blazor WebAssembly) oder Pages/_Host.cshtml (Blazor Server) des Projekts ein Stylesheet-<link>-Element für scoped.styles.css aus einer früheren 5.0-Vorschauversion enthält, entfernen Sie das <link>-Tag:

-<link href="_framework/scoped.styles.css/" rel="stylesheet" />

Aktualisieren von Razor-Klassenbibliotheken (RCLs)

Migrieren Sie Razor-Klassenbibliotheken (Razor Class Library, RCL), um neue APIs oder Features zu nutzen, die im Rahmen von ASP.NET Core 5.0 eingeführt werden.

So aktualisieren Sie eine RCL, die sich auf Komponenten bezieht:

Aktualisieren Sie die folgenden Eigenschaften in der Projektdatei:

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

  <PropertyGroup>
-     <TargetFramework>netstandard2.0</TargetFramework>
-     <RazorLangVersion>3.0</RazorLangVersion>
+     <TargetFramework>net5.0</TargetFramework>
  </PropertyGroup>

Aktualisieren Sie andere Pakete auf die aktuellen Versionen. Die aktuellen Versionen finden Sie auf NuGet.org.

Um eine RCL für Model View Controller (MVC) zu aktualisieren, aktualisieren Sie die folgenden Eigenschaften in der Projektdatei:

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

  <PropertyGroup>
-    <TargetFramework>netcoreapp3.1</TargetFramework>
+    <TargetFramework>net5.0</TargetFramework>
    <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
  </PropertyGroup>

Aktualisieren von Paketverweisen

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

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

Aktualisieren von Docker-Images

Aktualisieren Sie für Apps, die Docker verwenden, Ihre DockerfileFROM-Anweisungen und -Skripts. Verwenden Sie ein Basisimage, das die ASP.NET Core 5.0-Runtime enthält. Beachten Sie den folgenden Unterschied beim Befehl docker pull zwischen ASP.NET Core 3.1 und 5.0:

- docker pull mcr.microsoft.com/dotnet/core/aspnet:3.1
+ docker pull mcr.microsoft.com/dotnet/aspnet:5.0

Im Rahmen des Wechsels zu „.NET“ als Produktname wurden die Docker-Images aus den mcr.microsoft.com/dotnet/core-Repositorys in mcr.microsoft.com/dotnet verschoben. Weitere Informationen finden Sie unter dotnet/dotnet-docker#1939.

Änderungen der Modellbindung in ASP.NET Core MVC und Razor Pages

DateTime-Werte sind als UTC-Zeiten modellgebunden.

In ASP.NET Core 3.1 und früher waren DateTime-Werte als Ortszeit modellgebunden, wobei die Zeitzone vom Server bestimmt wurde. Durch die Eingabeformatierung (JSON) gebundene DateTime-Werte und DateTimeOffset-Werte wurden als UTC-Zeitzonen gebunden.

In ASP.NET Core 5.0 und höher werden DateTime-Werte von der Modellbindung konsistent an die UTC-Zeitzone gebunden.

Um das vorherige Verhalten beizubehalten, entfernen Sie DateTimeModelBinderProvider in Startup.ConfigureServices:

services.AddControllersWithViews(options => 
    options.ModelBinderProviders.RemoveType<DateTimeModelBinderProvider>());

ComplexObjectModelBinderProvider \ ComplexObjectModelBinder ersetzen ComplexTypeModelBinderProvider \ ComplexTypeModelBinder

Zum Hinzufügen von Unterstützung für die Modellbindung von C# 9-Datensatztypen ist der ComplexTypeModelBinderProvider:

Als veraltet gekennzeichnet.
Nicht mehr standardmäßig registriert.

Apps, die vom Vorhandensein von ComplexTypeModelBinderProvider in der ModelBinderProviders-Sammlung abhängig sind, müssen auf den neuen Binderanbieter verweisen:

- var complexModelBinderProvider = options.ModelBinderProviders.OfType<ComplexTypeModelBinderProvider>();
+ var complexModelBinderProvider = options.ModelBinderProviders.OfType<ComplexObjectModelBinderProvider>();

UseDatabaseErrorPage veraltet

Die ASP.NET Core 3.1-Vorlagen, die eine Option für einzelne Benutzerkonten enthalten, generieren einen Aufruf von UseDatabaseErrorPage. UseDatabaseErrorPage ist jetzt veraltet und sollte wie im folgenden Code gezeigt durch eine Kombination von AddDatabaseDeveloperPageExceptionFilter und UseMigrationsEndPoint ersetzt werden:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlServer(
            Configuration.GetConnectionString("DefaultConnection")));
+   services.AddDatabaseDeveloperPageExceptionFilter();
    services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
        .AddEntityFrameworkStores<ApplicationDbContext>();
    services.AddRazorPages();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
+       app.UseMigrationsEndPoint();
-       app.UseDatabaseErrorPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

Weitere Informationen finden Sie in diesem GitHub-Issue.

ASP.NET Core-Modul (ANCM)

Wenn das ASP.NET Core-Modul (ANCM) bei der Installation von Visual Studio keine ausgewählte Komponente war oder wenn eine frühere Version des ANCM auf dem System installiert wurde, laden Sie den neuesten Installer für das .NET Core Hosting-Paket (direkter Download) herunter, und führen Sie das Installationsprogramm aus. Weitere Informationen finden Sie unter Das .NET Core-Hostingbundle.

Paketverweisänderungen beeinträchtigen einige NuGet-Pakete

Bei der Migration einiger Microsoft.Extensions.*-NuGet-Pakete vom Repository dotnet/extensions zu dotnet/runtime, wie im Beitrag zum Migrieren von „dotnet/extensions“-Inhalten zu „dotnet/runtime“ und „dotnet/aspnetcore“ (aspnet/Ankündigung Nr. 411)) beschrieben, werden Paketänderungen auf einige der migrierten Pakete angewendet. Diese Änderungen führen häufig zu Namespaceänderungen für die .NET-API.

Verwenden Sie den .NET API-Browser, um App-Namespaceänderungen für APIs bei einer Migration zu Version 5.0 zu untersuchen.

Migrieren von Microsoft.Identity.Web

Auf den folgenden Wikiseiten wird erläutert, wie Sie Microsoft.Identity.Web von ASP.NET Core 3.1 zu Version 5.0 migrieren:

In den folgenden Tutorials wird die Migration ebenfalls erläutert:

ASP.NET Core-Web-App, die Benutzer*innen mit Microsoft Identity Platform in Ihrer Organisation anmeldet. Weitere Informationen finden Sie unter Option 2: Erstellen des Beispiels über die Befehlszeile.
Anmelden von Benutzer*innen mit Microsoft Identity Platform in einer WPF-Desktopanwendung und Aufrufen einer ASP.NET Core-Web-API. Weitere Informationen finden Sie im Artikel zum Erstellen des Codes.

Überprüfen von Breaking Changes

Informationen zu Breaking Changes zwischen .NET Core 3.1 und .NET 5.0 finden Sie unter Breaking Changes bei der Migration von Version 3.1 zu 5.0. ASP.NET Core und Entity Framework Core sind auch in der Liste enthalten.

Migrieren von ASP.NET Core 3.1 zu 5.0

Voraussetzungen

Aktualisieren der .NET Core SDK-Version in „global.json“

Aktualisieren des Zielframeworks

Löschen der Ordner `bin` und `obj`

Änderungen der Blazor-App-Routinglogik in Version 5.0.1 und weiteren 5.x-Versionen bis 6.0

Altes Verhalten

Neues Verhalten

Grund für die Änderung

Empfohlene Maßnahme

Aktualisieren von Blazor WebAssembly- und Blazor Server-Projekten

Aktualisieren von Blazor WebAssembly Projekten

Eigenständige Blazor WebAssembly-App mit Microsoft-Konten

Eigenständige Blazor WebAssembly-App mit Microsoft Entra ID (ME-ID)

Eigenständige Blazor WebAssembly-App mit Azure Active Directory (AAD) B2C

Gehostete Blazor WebAssembly-App mit Microsoft Entra ID (ME-ID) oder AAD B2C

Aktualisieren des Server-Projekts einer gehosteten Blazor-Projektmappe

Bereinigen und Neuerstellen des Projekts

Problembehandlung

Nicht autorisierter Client für Microsoft Entra ID (ME-ID)

Aktualisieren einer progressiven Blazor-Web-App (PWA)

Entfernen des Stylesheetlinks der Preview-CSS-Isolation

Aktualisieren von Razor-Klassenbibliotheken (RCLs)

Aktualisieren von Paketverweisen

Aktualisieren von Docker-Images

Änderungen der Modellbindung in ASP.NET Core MVC und Razor Pages

DateTime-Werte sind als UTC-Zeiten modellgebunden.

ComplexObjectModelBinderProvider \ ComplexObjectModelBinder ersetzen ComplexTypeModelBinderProvider \ ComplexTypeModelBinder

UseDatabaseErrorPage veraltet

ASP.NET Core-Modul (ANCM)

Paketverweisänderungen beeinträchtigen einige NuGet-Pakete

Migrieren von Microsoft.Identity.Web

Überprüfen von Breaking Changes

Feedback

Zusätzliche Ressourcen

Migrieren von ASP.NET Core 3.1 zu 5.0

Voraussetzungen

Aktualisieren der .NET Core SDK-Version in „global.json“

Aktualisieren des Zielframeworks

Löschen der Ordner bin und obj

Änderungen der Blazor-App-Routinglogik in Version 5.0.1 und weiteren 5.x-Versionen bis 6.0

Altes Verhalten

Neues Verhalten

Grund für die Änderung

Empfohlene Maßnahme

Aktualisieren von Blazor WebAssembly- und Blazor Server-Projekten

Aktualisieren von Blazor WebAssembly Projekten

Eigenständige Blazor WebAssembly-App mit Microsoft-Konten

Eigenständige Blazor WebAssembly-App mit Microsoft Entra ID (ME-ID)

Eigenständige Blazor WebAssembly-App mit Azure Active Directory (AAD) B2C

Gehostete Blazor WebAssembly-App mit Microsoft Entra ID (ME-ID) oder AAD B2C

Aktualisieren des Server-Projekts einer gehosteten Blazor-Projektmappe

Bereinigen und Neuerstellen des Projekts

Problembehandlung

Nicht autorisierter Client für Microsoft Entra ID (ME-ID)

Aktualisieren einer progressiven Blazor-Web-App (PWA)

Entfernen des Stylesheetlinks der Preview-CSS-Isolation

Aktualisieren von Razor-Klassenbibliotheken (RCLs)

Aktualisieren von Paketverweisen

Aktualisieren von Docker-Images

Änderungen der Modellbindung in ASP.NET Core MVC und Razor Pages

DateTime-Werte sind als UTC-Zeiten modellgebunden.

ComplexObjectModelBinderProvider \ ComplexObjectModelBinder ersetzen ComplexTypeModelBinderProvider \ ComplexTypeModelBinder

UseDatabaseErrorPage veraltet

ASP.NET Core-Modul (ANCM)

Paketverweisänderungen beeinträchtigen einige NuGet-Pakete

Migrieren von Microsoft.Identity.Web

Überprüfen von Breaking Changes

Feedback

Zusätzliche Ressourcen

Löschen der Ordner `bin` und `obj`