Kompatibilitätsversion für ASP.NET Core MVCCompatibility version for ASP.NET Core MVC

Von Rick AndersonBy Rick Anderson

Die SetCompatibilityVersion-Methode ist für ASP.NET Core 3.0-Apps keine Option.The SetCompatibilityVersion method is a no-op for ASP.NET Core 3.0 apps. Das bedeutet, dass der Aufruf von SetCompatibilityVersion mit einem beliebigen Wert von CompatibilityVersion keine Auswirkungen auf die Anwendung hat.That is, calling SetCompatibilityVersion with any value of CompatibilityVersion has no impact on the application.

  • Die nächste Nebenversion von ASP.NET Core stellt möglicherweise einen neuen CompatibilityVersion-Wert bereit.The next minor version of ASP.NET Core may provide a new CompatibilityVersion value.
  • CompatibilityVersion-Werte von Version_2_0 bis Version_2_2 (jeweils einschließlich) sind als [Obsolete(...)] gekennzeichnet.CompatibilityVersion values Version_2_0 through Version_2_2 are marked [Obsolete(...)].
  • Weitere Informationen finden Sie unter Breaking API changes in Antiforgery, CORS, Diagnostics, Mvc, and Routing (Breaking Changes bei APIs für Fälschungsschutz, CORS, Diagnosen, MVC und Routing).See Breaking API changes in Antiforgery, CORS, Diagnostics, Mvc, and Routing. Diese Liste enthält Breaking Changes für Kompatibilitätsoptionen.This list includes breaking changes for compatibility switches.

Um zu erfahren, wie SetCompatibilityVersion mit ASP.NET Core 2.x-Apps funktioniert, wählen Sie die ASP.NET Core 2.2-Version dieses Artikels aus.To see how SetCompatibilityVersion works with ASP.NET Core 2.x apps, select the ASP.NET Core 2.2 version of this article.

Mit der Methode SetCompatibilityVersion kann eine ASP.NET Core 2.x-App Änderungen im Verhalten aktivieren oder deaktivieren, die in ASP.NET Core MVC 2.1 oder 2.2 eingeführt wurden und Fehler verursachen können.The SetCompatibilityVersion method allows an ASP.NET Core 2.x app to opt-in or opt-out of potentially breaking behavior changes introduced in ASP.NET Core MVC 2.1 or 2.2. Diese potentiell Fehler verursachenden Änderungen im Verhalten betreffen generell das Verhalten des MVC-Subsystems und die Art, wie Ihr Code von der Runtime aufgerufen wird.These potentially breaking behavior changes are generally in how the MVC subsystem behaves and how your code is called by the runtime. Wenn Sie sich für die Änderungen entscheiden, erhalten Sie das aktuelle Verhalten und das langfristige Verhalten von ASP.NET Core.By opting in, you get the latest behavior, and the long-term behavior of ASP.NET Core.

Der folgende Code legt den Kompatibilitätsmodus auf ASP.NET Core 2.2 fest:The following code sets the compatibility mode to ASP.NET Core 2.2:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

Es wird empfohlen, Ihre App mit der aktuellen Version zu testen (CompatibilityVersion.Latest).We recommend you test your app using the latest version (CompatibilityVersion.Latest). Wir erwarten, dass bei den meisten Apps mit der aktuellen Version keine Fehler verursachenden Verhaltensänderungen auftreten werden.We anticipate that most apps won't have breaking behavior changes using the latest version.

Apps, die SetCompatibilityVersion(CompatibilityVersion.Version_2_0) aufrufen, sind vor potenziell Fehler verursachenden Änderungen im Verhalten geschützt, die in den ASP.NET Core MVC-Versionen 2.1 bzw. 2.2 eingeführt wurden.Apps that call SetCompatibilityVersion(CompatibilityVersion.Version_2_0) are protected from potentially breaking behavior changes introduced in the ASP.NET Core 2.1/2.2 MVC versions. Dieser Schutz:This protection:

  • Gilt nicht für alle Änderungen in 2.1 und höher. Das Ziel sind potentiell Fehler verursachende Änderungen im Verhalten der ASP.NET Core-Runtime im MVC-Subsystem.Does not apply to all 2.1 and later changes, it's targeted to potentially breaking ASP.NET Core runtime behavior changes in the MVC subsystem.
  • Der Schutz gilt nicht für ASP.NET Core 3.0.Does not extend to ASP.NET Core 3.0.

Standardmäßig gilt für ASP.NET Core 2.1- und 2.2-Apps, die nichtSetCompatibilityVersion aufrufen, die Kompatibilität mit Version 2.0.The default compatibility for ASP.NET Core 2.1 and 2.2 apps that do not call SetCompatibilityVersion is 2.0 compatibility. Das bedeutet, SetCompatibilityVersion nicht aufzurufen entspricht dem Aufrufen von SetCompatibilityVersion(CompatibilityVersion.Version_2_0).That is, not calling SetCompatibilityVersion is the same as calling SetCompatibilityVersion(CompatibilityVersion.Version_2_0).

Der folgende Code legt den Kompatibilitätsmodus auf ASP.NET Core 2.2 fest, außer für die folgenden Verhaltensweisen:The following code sets the compatibility mode to ASP.NET Core 2.2, except for the following behaviors:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        // Include the 2.2 behaviors
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
        // Except for the following.
        .AddMvcOptions(options =>
        {
            // Don't combine authorize filters (keep 2.0 behavior).
            options.AllowCombiningAuthorizeFilters = false;
            // All exceptions thrown by an IInputFormatter are treated
            // as model state errors (keep 2.0 behavior).
            options.InputFormatterExceptionPolicy =
                InputFormatterExceptionPolicy.AllExceptions;
        });
}

Bei Apps, bei denen Fehler verursachende Änderungen auftreten, können Sie die geeigneten Kompatibilitätsoptionen verwenden, um Folgendes zu erreichen:For apps that encounter breaking behavior changes, using the appropriate compatibility switches:

  • Sie können das aktuelle Release verwenden und spezifische Fehler verursachende Änderungen im Verhalten vermeiden.Allows you to use the latest release and opt out of specific breaking behavior changes.
  • Sie bekommen die Gelegenheit, Ihre App zu aktualisieren, damit Sie mit den neuesten Änderungen funktioniert.Gives you time to update your app so it works with the latest changes.

In der MvcOptions-Dokumentation finden Sie eine gute Erklärung, was sich geändert hat und warum die Änderungen eine Verbesserung für die meisten Benutzer darstellen.The MvcOptions documentation has a good explanation of what changed and why the changes are an improvement for most users.

Alte Verhaltensweisen, die von Kompatibilitätsoptionen unterstützt werden, wurden aus ASP.NET Core 3.0 entfernt.With ASP.NET Core 3.0, old behaviors supported by compatibility switches have been removed. Beinahe alle Benutzer werden von diesen positiven Änderungen profitieren.We feel these are positive changes benefitting nearly all users. Diese Änderungen in 2.1 und 2.2 bieten Vorteile für die meisten Apps, bei anderen bleibt genügend Zeit für ein Update.By introducing these changes in 2.1 and 2.2, most apps can benefit, while others have time to update.