ASP.NET Core MVC 的兼容性版本

2025-05-28

此方法 SetCompatibilityVersion 是适用于 ASP.NET Core 3.0 应用的 no-op。也就是说，无论CompatibilityVersion的值是多少，调用SetCompatibilityVersion都不会影响应用程序。

ASP.NET Core 的下一个次要版本可能提供新 CompatibilityVersion 值。
CompatibilityVersion 值从 Version_2_0 到 Version_2_2 标记为 [Obsolete(...)]。
请参阅 Antiforgery、CORS、诊断、Mvc 和路由中的 API 重大变更。此列表包括兼容换机的重大更改。

若要查看 ASP.NET Core 2.x 应用的工作原理 SetCompatibilityVersion ，请选择本文的 ASP.NET Core 2.2 版本。

该SetCompatibilityVersion 方法允许 ASP.NET Core 2.x 应用程序选择启用或禁用在 ASP.NET Core MVC 2.1 或 2.2 中引入的可能导致中断的行为更改。这些潜在的中断行为更改通常在于 MVC 子系统的行为方式以及运行时调用代码的方式。通过选择加入，您可以获得 ASP.NET Core 的最新功能和长期功能。

以下代码将兼容性模式设置为 ASP.NET Core 2.2：

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

建议使用最新版本CompatibilityVersion.Latest（）测试应用。我们预计大多数应用在使用最新版本时不会发生破坏性的行为改变。

调用 SetCompatibilityVersion(CompatibilityVersion.Version_2_0) 的应用受到了 ASP.NET Core 2.1/2.2 MVC 版本中引入的潜在破坏性行为更改的保护。这种保护：

不适用于所有 2.1 或更高版本的更改，而是专注于可能破坏 MVC 子系统中 ASP.NET Core 运行时行为的变更。
不会扩展到 ASP.NET Core 3.0。

默认情况下，ASP.NET Core 2.1 和 2.2 应用如果没有调用SetCompatibilityVersion，其兼容性为 2.0。也就是说，不调用 SetCompatibilityVersion 与调用 SetCompatibilityVersion(CompatibilityVersion.Version_2_0)相同。

以下代码将兼容性模式设置为 ASP.NET Core 2.2，但以下行为除外：

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;
        });
}

对于遇到导致不兼容行为更改的应用，请使用相应的兼容性设置：

允许使用最新版本并选择不参与某些可能破坏现有功能的行为更改。
提供时间来更新应用，使其适用于最新更改。

文档 MvcOptions 对于发生的变化及其对大多数用户的好处进行了很好的说明。

使用 ASP.NET Core 3.0 时，兼容性开关支持的旧行为已被删除。我们认为，这些是积极的变化，使几乎所有用户受益。通过在 2.1 和 2.2 中引入这些更改，大多数应用都可以受益，而其他人则有时间更新。

通过

ASP.NET Core MVC 的兼容性版本

其他资源