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. 也就是说,使用 CompatibilityVersion 的任何值调用 SetCompatibilityVersion 都不会影响应用程序。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.

未 调用 SetCompatibilityVersion 的 ASP.NET Core 2.1 和 2.2 版本的应用的默认兼容性是 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.