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.

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