Versão de compatibilidade do ASP.NET Core MVC

O SetCompatibilityVersion método não é operacional para aplicativos ASP.NET Core 3.0. Ou seja, chamar SetCompatibilityVersion com qualquer valor de CompatibilityVersion não tem impacto sobre o aplicativo.

• A próxima versão secundária do ASP.NET Core pode fornecer um novo CompatibilityVersion valor.
• Os CompatibilityVersion valores Version_2_0 pelo Version_2_2 são marcados [Obsolete(...)].
• Consulte Alterações interruptivas da API em Antiforgeria, CORS, Diagnóstico, Mvc e Roteamento. Essa lista inclui alterações interruptivas dos comutadores de compatibilidade.

Para ver como SetCompatibilityVersion funciona com aplicativos ASP.NET Core 2.x, selecione a versão ASP.NET Core 2.2 deste artigo.

O SetCompatibilityVersion método permite que um aplicativo ASP.NET Core 2.x aceite ou recuse alterações de comportamento potencialmente prejudiciais introduzidas no ASP.NET Core MVC 2.1 ou 2.2. Essas possíveis alterações da falha de comportamento geralmente afetam como o subsistema MVC se comporta e como o código do usuário é chamado pelo runtime. Ao aceitar, você obtém o comportamento mais recente e o comportamento de longo prazo do ASP.NET Core.

O código a seguir define o modo de compatibilidade para o ASP.NET Core 2.2:

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

É recomendável que você teste seu aplicativo usando a versão mais recente (CompatibilityVersion.Latest). Estimamos que a maioria dos aplicativos não terão alterações da falha de comportamento usando a versão mais recente.

Os aplicativos que chamam SetCompatibilityVersion(CompatibilityVersion.Version_2_0) são protegidos contra alterações de comportamento potencialmente prejudiciais introduzidas nas versões ASP.NET Core 2.1/2.2 MVC. Essa proteção:

• Não se aplica a todas as alterações da 2.1 e posteriores, ela é direcionada às possíveis alterações da falha de comportamento do runtime do ASP.NET Core no subsistema de MVC.
• Não se estende ao ASP.NET Core 3.0.

A compatibilidade padrão dos aplicativos ASP.NET Core 2.1 e 2.2.x que não é chamada é a SetCompatibilityVersion compatibilidade 2.0. Ou seja, não chamar SetCompatibilityVersion é o mesmo que chamar SetCompatibilityVersion(CompatibilityVersion.Version_2_0).

O código a seguir define o modo de compatibilidade para o ASP.NET Core 2.2, exceto para os seguintes comportamentos:

• AllowCombiningAuthorizeFilters
• InputFormatterExceptionPolicy

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

Para aplicativos que encontram alterações da falha de comportamento, o uso das opções de compatibilidade apropriadas:

• Permite que você use a versão mais recente e recuse alterações da falha de comportamento específicas.
• Tenha tempo para atualizar seu aplicativo para que ele funcione com as alterações mais recentes.

A documentação MvcOptions tem uma boa explicação sobre o que mudou e por que as alterações são uma melhoria para a maioria dos usuários.

Com o ASP.NET Core 3.0, os comportamentos antigos suportados pelas opções de compatibilidade foram removidos. Consideramos que essas são alterações positivas que beneficiam quase todos os usuários. Ao introduzir essas alterações em 2.1 e 2.2, a maioria dos aplicativos pode se beneficiar, enquanto outros têm tempo para atualizar.