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

作者:Rick AndersonBy Rick Anderson

SetCompatibilityVersion 方法可讓應用程式加入或退出 ASP.NET Core MVC 2.1 或更新版本所引入的可能重大行為變更。The SetCompatibilityVersion method allows an app to opt-in or opt-out of potentially breaking behavior changes introduced in ASP.NET Core MVC 2.1 or later. 這些可能的重大行為變更通常在於 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.Version_2_2) 測試應用程式。We recommend you test your app using the latest version (CompatibilityVersion.Version_2_2). 預計大部分的應用程式都不會使用最新版本進行重大行為變更。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 MVC 和更新版本的 2.x 版所引進的可能重大行為變更。Apps that call SetCompatibilityVersion(CompatibilityVersion.Version_2_0) are protected from potentially breaking behavior changes introduced in the ASP.NET Core 2.1 MVC and later 2.x 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.
  • 不會擴充到下一個主要版本。Does not extend to the next major version.

適用於 ASP.NET Core 2.1 和更新版本的 2.x 應用程式且不會呼叫 SetCompatibilityVersion 的預設相容性為 2.0 相容性。The default compatibility for ASP.NET Core 2.1 and later 2.x 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 版At some future date, there will be an ASP.NET Core 3.0 version. 3.0 版將移除相容性參數支援的舊行為。Old behaviors supported by compatibility switches will be removed in the 3.0 version. 我們覺得這些是有利於幾乎所有使用者的正向變更。We feel these are positive changes benefitting nearly all users. 現在引進這些變更,大部分的應用程式皆可獲益,而其他人則有時間來更新其應用程式。By introducing these changes now, most apps can benefit now, and the others will have time to update their apps.