Version de compatibilité pour ASP.NET Core MVC

  • Article

Par Rick Anderson

La méthode SetCompatibilityVersion est une non-op pour les applications ASP.NET Core 3.0. Autrement dit, l'appel SetCompatibilityVersion avec n'importe quelle valeur de CompatibilityVersion n'a aucun impact sur l'application.

  • La prochaine version mineure d'ASP.NET Core peut fournir une nouvelle valeur CompatibilityVersion.
  • CompatibilityVersion les valeurs Version_2_0 via Version_2_2 sont marquées [Obsolete(...)].
  • Voir Breaking API changes in Antiforgery, CORS, Diagnostics, Mvc, and Routing. Cette liste inclut les modifications avec rupture pour les commutateurs de compatibilité.

Pour voir comment SetCompatibilityVersion fonctionne avec les applications ASP.NET Core 2.x, sélectionnez la version ASP.NET Core 2.2 de cet article.

La méthode SetCompatibilityVersion permet à une application ASP.NET Core 2.x d'activer ou de désactiver les changements de comportement potentiellement dangereux introduits dans ASP.NET Core MVC 2.1 ou 2.2. Ces changements de comportement potentiellement cassants concernent en général la façon dont le sous-système MVC se comporte et la façon dont votre code est appelé par le runtime. En acceptant, vous obtenez le comportement le plus récent et le comportement à long terme d’ASP.NET Core.

Le code suivant définit le mode de compatibilité sur ASP.NET Core 2.2 :

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

Nous vous recommandons de tester votre application avec la version la plus récente (CompatibilityVersion.Latest). Nous pensons que la plupart des applications ne connaîtront pas de changements de comportement cassants avec la version la plus récente.

Les applications SetCompatibilityVersion(CompatibilityVersion.Version_2_0) qui appellent sont protégées contre les changements de comportement potentiellement dangereux introduits dans les versions ASP.NET Core 2.1/2.2 MVC. Cette protection :

  • Ne s’applique pas à tous les changements de 2.1 et ultérieur. Elle est destinée aux changements de comportement potentiellement cassants du runtime ASP.NET Core dans le sous-système MVC.
  • Ne s'étend pas à ASP.NET Core 3.0.

La compatibilité par défaut pour les applications ASP.NET Core 2.1 et 2.2 qui n'appellent SetCompatibilityVersionpas est la compatibilité 2.0. Autrement dit, ne pas appeler SetCompatibilityVersion revient à appeler SetCompatibilityVersion(CompatibilityVersion.Version_2_0).

Le code suivant définit le mode de compatibilité sur ASP.NET Core 2.2, sauf pour les comportements suivants :

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

Pour les applications qui rencontrent des changements de comportement cassants, l’utilisation des commutateurs de compatibilité appropriés :

  • Vous permet d’utiliser la dernière version et de refuser des changements de comportement cassants spécifiques.
  • Vous laisse le temps de mettre à jour votre application pour qu’elle fonctionne avec les derniers changements.

La documentation MvcOptions explique clairement ce qui a changé et pourquoi ces changements représentent une amélioration pour la plupart des utilisateurs.

Avec ASP.NET Core 3.0, les anciens comportements pris en charge par les commutateurs de compatibilité ont été supprimés. Nous pensons que ce sont des changements positifs, qui vont bénéficier à presque tous les utilisateurs. En introduisant ces modifications dans les versions 2.1 et 2.2, la plupart des applications peuvent en bénéficier, tandis que d'autres ont le temps de se mettre à jour.