ASP.NET Core MVC 的相容性版本Compatibility version for ASP.NET Core MVC

作者:Rick AndersonBy Rick Anderson

SetCompatibilityVersion針對 ASP.NET Core 3.0 應用程式,此方法不會有任何作用。The SetCompatibilityVersion method is a no-op for ASP.NET Core 3.0 apps. 亦即, SetCompatibilityVersion 使用的任何值呼叫 CompatibilityVersion 不會影響應用程式。That is, calling SetCompatibilityVersion with any value of CompatibilityVersion has no impact on the application.

若要查看 SetCompatibilityVersion ASP.NET Core 2.x 應用程式如何運作,請選取 此文章的 ASP.NET Core 2.2 版本To see how SetCompatibilityVersion works with ASP.NET Core 2.x apps, select the ASP.NET Core 2.2 version of this article.

SetCompatibilityVersion方法可讓 ASP.NET Core 2.x 應用程式加入宣告或退出 ASP.NET CORE MVC 2.1 或2.2 中引進的潛在中斷行為變更。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. 這些可能的重大行為變更通常在於 MVC 子系統的運作方式,以及執行階段呼叫 您的程式碼 的方式。These potentially breaking behavior changes are generally in how the MVC subsystem behaves and how your code is called by the runtime. 透過選擇加入,您可以取得最新的行為和 ASP.NET Core 的長期行為。By opting in, you get the latest behavior, and the long-term behavior of ASP.NET Core.

下列程式碼會將相容性模式設定為 ASP.NET Core 2.2:The following code sets the compatibility mode to ASP.NET Core 2.2:

public void ConfigureServices(IServiceCollection services)

建議您使用最新版本 (CompatibilityVersion.Latest) 測試應用程式。We recommend you test your app using the latest version (CompatibilityVersion.Latest). 預計大部分的應用程式都不會使用最新版本進行重大行為變更。We anticipate that most apps won't have breaking behavior changes using the latest version.

呼叫的應用程式 SetCompatibilityVersion(CompatibilityVersion.Version_2_0) 會受到保護,以防止 ASP.NET Core 2.1/2.2 MVC 版本中引入的可能重大行為變更。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. 這項保護:This protection:

  • 不適用於所有 2.1 和更新版本的變更,它的目標是 MVC 子系統中的可能重大 ASP.NET Core 執行階段行為變更。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.
  • 不會延伸至 ASP.NET Core 3.0。Does not extend to ASP.NET Core 3.0.

呼叫 ASP.NET Core 2.1 和2.2 應用程式的預設相容性 SetCompatibilityVersion 為2.0 相容性。The default compatibility for ASP.NET Core 2.1 and 2.2 apps that do not call SetCompatibilityVersion is 2.0 compatibility. 也就是說,不呼叫 SetCompatibilityVersion 等同於呼叫 SetCompatibilityVersion(CompatibilityVersion.Version_2_0)That is, not calling SetCompatibilityVersion is the same as calling SetCompatibilityVersion(CompatibilityVersion.Version_2_0).

下列程式碼會將相容性模式設定為 ASP.NET Core 2.2,但下列行為除外:The following code sets the compatibility mode to ASP.NET Core 2.2, except for the following behaviors:

public void ConfigureServices(IServiceCollection services)
        // Include the 2.2 behaviors
        // 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 =

對於出現重大行為變更的應用程式,使用適當的相容性參數:For apps that encounter breaking behavior changes, using the appropriate compatibility switches:

  • 可讓您使用最新版本,並選擇退出特定的重大行為變更。Allows you to use the latest release and opt out of specific breaking behavior changes.
  • 讓您有時間來更新您的應用程式,使其適用於最新的變更。Gives you time to update your app so it works with the latest changes.

MvcOptions 文件充分說明變更的項目,以及所做變更對於大部分使用者來說都得到改善的原因。The MvcOptions documentation has a good explanation of what changed and why the changes are an improvement for most users.

使用 ASP.NET Core 3.0,已移除相容性參數所支援的舊行為。With ASP.NET Core 3.0, old behaviors supported by compatibility switches have been removed. 我們覺得這些是有利於幾乎所有使用者的正向變更。We feel these are positive changes benefitting nearly all users. 藉由在2.1 和2.2 中引進這些變更,大部分的應用程式都可以獲益,有些則有時間更新。By introducing these changes in 2.1 and 2.2, most apps can benefit, while others have time to update.