Breaking Changes in .NET Core 3.1

  • Artikel

Wenn Sie eine Migration von Version 3.1 von .NET Core oder ASP.NET Core durchführen, können sich die in diesem Artikel aufgeführten Breaking Changes auf Ihre App auswirken.

ASP.NET Core

HTTP: Browser-SameSite-Änderungen mit Auswirkung auf die Authentifizierung

Bei einigen Browsern, z. B. Chrome und Firefox, gab es Breaking Changes bei deren Implementierungen von SameSite für Cookies. Die Änderungen wirken sich auf Remoteauthentifizierungsszenarien aus, z. B. OpenID Connect und WS-Verbund, die durch das Senden von SameSite=None deaktiviert werden müssen. SameSite=None funktioniert jedoch unter iOS 12 und einigen älteren Versionen anderer Browser nicht. Die App muss ermitteln, ob diese Versionen vorliegen, und SameSite weglassen.

Dieses Problem wird unter dotnet/aspnetcore#14996 behandelt.

Eingeführt in Version

3.1 Vorschauversion 1

Altes Verhalten

SameSite ist eine Erweiterung des Normentwurfs von 2016 für HTTP-Cookies. Damit soll das Risiko einer websiteübergreifenden Anforderungsfälschung (Cross-Site Request Forgery, CSRF) minimiert werden. Es wurde ursprünglich als eine Funktion entwickelt, die die Server durch Hinzufügen der neuen Parameter aktivieren können. In ASP.NET Core 2.0 wurde die erstmalige Unterstützung für SameSite eingeführt.

Neues Verhalten

Google hat einen neuen Normentwurf vorgeschlagen, der nicht abwärtskompatibel ist. In der Norm wird der Standardmodus in Lax geändert und der neue Eintrag None zur Deaktivierung eingeführt. Lax ist für die meisten App-Cookies ausreichend, allerdings funktionieren standardübergreifende Szenarien wie die Anmeldung mit OpenID Connect und WS-Verbund dann nicht mehr. Die meisten OAuth-Anmeldungen sind aufgrund von Unterschieden beim Ablauf der Anforderung nicht betroffen. Der neue Parameter None führt zu Kompatibilitätsproblemen mit Clients, die den früheren Normentwurf implementiert haben (z. B. iOS 12). Chrome 80 enthält die Änderungen. Weitere Informationen finden Sie unter SameSite-Updates für den Chrome-Produkteinführungszeitplan.

ASP.NET Core 3.1 wurde aktualisiert, um das neue SameSite-Verhalten zu implementieren. Das Update definiert das Verhalten von SameSiteMode.None neu, um SameSite=None auszugeben, und ergänzt den neuen Wert SameSiteMode.Unspecified, um das SameSite-Attribut auszulassen. Der Standard für alle Cookie-APIs ist jetzt Unspecified, obwohl einige Komponenten, die Cookies verwenden, Werte festlegen, die sich eher auf die entsprechenden Szenarien beziehen, z. B. die OpenID Connect-Korrelation und Nonce-Cookies.

Weitere aktuelle Änderungen in diesem Bereich finden Sie unter HTTP: Einige Cookie-SameSite-Standardwerte wurden in None geändert. In ASP.NET Core 3.0 wurden die meisten Standardwerte von SameSiteMode.Lax in SameSiteMode.None geändert (der vorherige Standard wird jedoch weiterhin verwendet).

Grund für die Änderung

Änderungen bei Browsern und Spezifikationen, wie im vorangehenden Text erläutert.

Apps, die mit Remotestandorten interagieren, z. B. über die Anmeldung über Drittanbieter, müssen folgende Aktionen ausführen:

  • Testen Sie diese Szenarien in mehreren Browsern.
  • Wenden Sie die Maßnahmen zur Ermittlung der Cookierichtlinien im Browser an, die in Unterstützung älterer Browser erläutert werden.

Informationen zu Tests und Browserermittlung finden Sie im folgenden Abschnitt.

Ermitteln, ob Sie betroffen sind

Testen Sie Ihre Web-App mit einer Clientversion, die das neue Verhalten aktivieren kann. Chrome, Firefox und Microsoft Edge Chromium verfügen über neue Featureflags, die für Tests verwendet werden können. Vergewissern Sie sich, dass Ihre App nach dem Anwenden der Patches mit älteren Clientversionen kompatibel ist, insbesondere mit Safari. Weitere Informationen finden Sie unter Unterstützung älterer Browser.

Chrome

Chrome 78 und höher liefert irreführende Testergebnisse. Diese Versionen verfügen über eine vorübergehende Entschärfung und akzeptieren Cookies, die weniger als zwei Minuten alt sind. Wenn die entsprechenden Testflags aktiviert sind, liefern Chrome 76 und 77 genauere Ergebnisse. Um das neue Verhalten zu testen, legen Sie chrome://flags/#same-site-by-default-cookies auf aktiviert fest. Bei Chrome 75 und früheren Versionen wurde ein Fehlschlagen mit der neuen None-Einstellung gemeldet. Weitere Informationen finden Sie unter Unterstützung älterer Browser.

Google stellt keine älteren Chrome-Versionen zur Verfügung. Sie können jedoch ältere Versionen von Chromium herunterladen, die für Tests ausreichen. Befolgen Sie die Anweisungen unter Herunterladen von Chromium.

Safari

In Safari 12 wurde der vorherige Entwurf streng implementiert, und der neue None-Wert in Cookies führt zu einem Fehler. Um dies zu vermeiden, muss der unter Unterstützung älterer Browser aufgeführte Code zur Browserermittlung verwendet werden. Sie müssen Tests mit Safari 12 und 13 sowie auf WebKit-Basis, Betriebssystemanmeldungen mit Microsoft Authentication Library (MSAL), Active Directory Authentication Library (ADAL) oder einer sonstigen von Ihnen verwendeten Bibliothek durchführen. Das Problem hängt von der zugrunde liegenden Betriebssystemversion ab. Bei OSX Mojave 10.14 und iOS 12 sind Kompatibilitätsprobleme mit dem neuen Verhalten bekannt. Das Problem lässt sich mit einem Upgrade auf OSX Catalina 10.15 bzw. iOS 13 beheben. Safari verfügt derzeit über kein Aktivierungsflag zum Testen des neuen Spezifikationsverhaltens.

Firefox

Die Firefox-Unterstützung für den neuen Standard kann in Version 68 und höher getestet werden, indem Sie sich auf der Seite about:config mit dem Featureflag network.cookie.sameSite.laxByDefaultanmelden. Bei älteren Versionen von Firefox sind keine Kompatibilitätsprobleme bekannt.

Microsoft Edge

Microsoft Edge unterstützt zwar den alten SameSite-Standard, ab Version 44 sind jedoch keine Kompatibilitätsprobleme mit dem neuen Standard aufgetreten.

Microsoft Edge Chromium

Das Featureflag ist edge://flags/#same-site-by-default-cookies. Bei Tests mit Microsoft Edge Chromium 78 wurden keine Kompatibilitätsprobleme festgestellt.

Electron

Zu den Electron-Versionen zählen ältere Versionen von Chromium. Beispielsweise ist die von Microsoft Teams verwendete Electron-Version Chromium 66, das das ältere Verhalten aufweist. Führen Sie Ihre eigenen Kompatibilitätstests mit der Version von Electron aus, die in Ihrem Produkt verwendet wird. Weitere Informationen finden Sie unter Unterstützung älterer Browser.

Unterstützung älterer Browser

Im SameSite-Standard von 2016 ist vorgeschrieben, dass unbekannte Werte als SameSite=Strict-Werte behandelt werden. Folglich kann es sein, dass bei älteren Browsern, die den ursprünglichen Standard unterstützen, Fehler auftreten, wenn eine SameSite-Eigenschaft mit dem Wert None erkannt wird. Web-Apps müssen eine Browserermittlung implementieren, wenn diese alten Browser unterstützt werden sollen. ASP.NET Core implementiert keine Browserermittlung für Sie, da die Werte des User-Agent-Anforderungsheaders sehr instabil sind und sich wöchentlich ändern. Stattdessen können Sie mithilfe eines Erweiterungspunkts in der Cookierichtlinie für User-Agentspezifische Logik hinzufügen.

Fügen Sie in Startup.cs folgenden Code hinzu:

private void CheckSameSite(HttpContext httpContext, CookieOptions options)
{
    if (options.SameSite == SameSiteMode.None)
    {
        var userAgent = httpContext.Request.Headers["User-Agent"].ToString();
        // TODO: Use your User Agent library of choice here.
        if (/* UserAgent doesn't support new behavior */)
        {
            options.SameSite = SameSiteMode.Unspecified;
        }
    }
}

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<CookiePolicyOptions>(options =>
    {
        options.MinimumSameSitePolicy = SameSiteMode.Unspecified;
        options.OnAppendCookie = cookieContext =>
            CheckSameSite(cookieContext.Context, cookieContext.CookieOptions);
        options.OnDeleteCookie = cookieContext =>
            CheckSameSite(cookieContext.Context, cookieContext.CookieOptions);
    });
}

public void Configure(IApplicationBuilder app)
{
    // Before UseAuthentication or anything else that writes cookies.
    app.UseCookiePolicy();

    app.UseAuthentication();
    // code omitted for brevity
}
Deaktivierungsschalter

Mit dem Kompatibilitätsschalter Microsoft.AspNetCore.SuppressSameSiteNone können Sie das neue ASP.NET Core-Cookieverhalten vorübergehend deaktivieren. Fügen Sie folgenden JSON-Code einer runtimeconfig.template.json-Datei in Ihrem Projekt hinzu:

{
  "configProperties": {
    "Microsoft.AspNetCore.SuppressSameSiteNone": "true"
  }
}
Andere Versionen

Entsprechende SameSite-Patches für folgende Versionen sind in Entwicklung:

  • ASP.NET Core 2.1, 2.2 und 3.0
  • Microsoft.Owin 4.1
  • System.Web (für .NET Framework 4.7.2 und höher)

Category

ASP.NET

Betroffene APIs

Bereitstellung

x86-Hostpfad unter 64-Bit-Windows

MSBuild

Entwurfszeitbuilds geben nur allgemeine Paketverweise zurück

Ab .NET Core SDK 3.1.400 werden vom RunResolvePackageDependencies-Ziel nur Verweise auf Pakete der obersten Ebene zurückgegeben.

Eingeführt in Version

.NET Core SDK 3.1.400

Änderungsbeschreibung

In früheren Versionen des .NET Core SDK erstellte das RunResolvePackageDependencies-Ziel die folgenden MSBuild-Elemente, die Informationen aus der NuGet-Ressourcendatei enthielten:

  • PackageDefinitions
  • PackageDependencies
  • TargetDefinitions
  • FileDefinitions
  • FileDependencies

Mit diesen Daten füllt Visual Studio den Knoten „Abhängigkeiten“ im Projektmappen-Explorer auf. Es kann sich dabei jedoch um eine große Menge von Daten handeln, die nur benötigt werden, wenn der Knoten „Abhängigkeiten“ aufgeklappt wird.

Ab Version 3.1.400 des .NET Core SDK werden die meisten dieser Elemente nicht standardmäßig generiert. Nur Elemente vom Typ Package werden zurückgegeben. Wenn Visual Studio die Elemente zum Auffüllen des Knotens „Abhängigkeiten“ benötigt, liest Visual Studio die betreffenden Informationen direkt aus der Ressourcendatei.

Grund für die Änderung

Diese Änderung wurde eingeführt, um die Leistung beim Laden von Projektmappen in Visual Studio zu verbessern. Zuvor wurden alle Paketverweise geladen, darunter viele, die von den meisten Benutzern nie angezeigt wurden.

Wenn Sie über eine MSBuild-Logik verfügen, die von der Erstellung dieser Elemente abhängt, legen Sie die Eigenschaft EmitLegacyAssetsFileItems in Ihrer Projektdatei auf true fest. Mit dieser Einstellung aktivieren Sie das vorherige Verhalten, bei dem alle Elemente erstellt werden.

Kategorie

MSBuild

Betroffene APIs

Nicht zutreffend

SDK

Toolmanifeste im Stammordner

Windows Forms

Entfernte Steuerelemente

Ab .NET Core 3.1 sind einige Windows Forms-Steuerelemente nicht mehr verfügbar.

Änderungsbeschreibung

Ab .NET Core 3.1 sind verschiedene Windows Forms-Steuerelemente nicht mehr verfügbar. Ersatzsteuerelemente, die ein besseres Design und eine umfassendere Unterstützung bieten, wurden in .NET Framework 2.0 eingeführt. Die veralteten Steuerelemente wurden zwar bereits aus den Designer-Toolboxen entfernt, konnten aber weiterhin verwendet werden.

Die folgenden Typen stehen nicht mehr länger zur Verfügung:

Eingeführt in Version

3.1

Für jedes entfernte Steuerelement gibt es ein empfohlenes Ersatzsteuerelement. Beachten Sie hierzu die folgende Tabelle:

Entferntes Steuerelement (API) Empfohlener Ersatz Zugehörige entfernte APIs
ContextMenu ContextMenuStrip
DataGrid DataGridView DataGridCell, DataGridRow, DataGridTableCollection, DataGridColumnCollection, DataGridTableStyle, DataGridColumnStyle, DataGridLineStyle, DataGridParentRowsLabel, DataGridParentRowsLabelStyle, DataGridBoolColumn, DataGridTextBox, GridColumnStylesCollection, GridTableStylesCollection, HitTestType
MainMenu MenuStrip
Menü ToolStripDropDown, ToolStripDropDownMenu MenuItemCollection
MenuItem ToolStripMenuItem
ToolBar ToolStrip ToolBarAppearance
ToolBarButton ToolStripButton ToolBarButtonClickEventArgs, ToolBarButtonClickEventHandler, ToolBarButtonStyle, ToolBarTextAlign

Kategorie

Windows Forms

Betroffene APIs

CellFormatting-Ereignis wird nicht ausgelöst, wenn QuickInfo angezeigt wird

Eine DataGridView zeigt nun Text- und die Fehler-QuickInfos einer Zelle an, wenn mit der Maus darauf gezeigt wird oder wenn sie mit der Tastatur ausgewählt wird. Wenn eine QuickInfo angezeigt wird, wird das DataGridView.CellFormatting-Ereignis nicht ausgelöst.

Änderungsbeschreibung

Vor .NET Core 3.1 wurde bei einer DataGridView, für die die ShowCellToolTips-Eigenschaft auf true festgelegt wurde, eine QuickInfo für den Text und Fehler einer Zelle angezeigt, wenn mit der Maus auf die Zelle gezeigt wurde. Es wurden keine QuickInfos angezeigt, wenn die Maus mit der Tastatur ausgewählt wurde (z. B. mit der TAB-TASTE, einer Tastenkombination oder den Pfeiltasten). Wenn der Benutzer eine Zelle bearbeitet hat und die DataGridView sich noch im Bearbeitungsmodus befunden hat und mit der Maus auf eine Zelle gezeigt wurde, für die die ToolTipText-Eigenschaft nicht festgelegt war, wurde ein CellFormatting-Ereignis ausgelöst, um den Text der Zelle für die Anzeige in der Zelle zu formatieren.

Um die Barrierefreiheitsstandards zu erfüllen, werden ab .NET Core 3.1 bei einer DataGridView, für die die ShowCellToolTips-Eigenschaft auf true festgelegt ist, QuickInfos für den Text und Fehler der Zelle nicht nur dann angezeigt, wenn mit der Maus darauf gezeigt wird, sondern auch, wenn sie mit der Tastatur ausgewählt wird. Infolge dieser Änderung wird das CellFormatting-Ereignis nicht ausgelöst, wenn mit der Maus auf Zellen gezeigt wird, für die ToolTipText-Eigenschaft nicht festgelegt ist, und die DataGridView sich im Bearbeitungsmodus befindet. Das Ereignis wird nicht ausgelöst, da der Inhalt der Zelle, auf die gezeigt wird, als QuickInfo und nicht in der Zelle dargestellt wird.

Eingeführt in Version

3.1

Schreiben Sie Code um, der das CellFormatting-Ereignis benötigt, während sich die DataGridView im Bearbeitungsmodus befindet.

Kategorie

Windows Forms

Betroffene APIs

Keine

Siehe auch