Совместимая версия для ASP.NET Core MVC

  • Статья

Автор: Рик Андерсон (Rick Anderson)

Метод SetCompatibilityVersion не предназначен для приложений ASP.NET Core 3.0. То есть вызов SetCompatibilityVersion с любым значением CompatibilityVersion не влияет на приложение.

  • Следующая дополнительная версия ASP.NET Core может предоставить новое значение CompatibilityVersion.
  • Значения CompatibilityVersion от Version_2_0 до Version_2_2 помечаются как [Obsolete(...)].
  • См. статью Breaking API changes in Antiforgery, CORS, Diagnostics, Mvc, and Routing (Критические изменения API в областях борьбы с фальсификацией, CORS, диагностики, MVC и маршрутизации). Этот список содержит критические изменения для параметров совместимости.

Чтобы узнать, как SetCompatibilityVersion работает с приложениями ASP.NET Core 2.x, выберите версию этой статьи для 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), защищены от потенциальных критически важных изменений в поведении, появившихся в версиях MVC ASP.NET Core 2.1/2.2. Особенности защиты:

  • Не применяется ко всем изменениям в версии 2.1 и более поздних версиях. Она направлена только на потенциально критические изменения в поведении среды выполнения ASP.NET Core в подсистеме MVC.
  • Не распространяется на 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 большинство приложений могут сразу воспользоваться преимуществами, в то время как для обновления других требуется время.