Compartilhar via

Versão de compatibilidade para ASP.NET Core MVC

Por Rick Anderson

O SetCompatibilityVersion método é um no-op para aplicativos do ASP.NET Core 3.0. Ou seja, chamar SetCompatibilityVersion com qualquer valor CompatibilityVersion não tem nenhum impacto no aplicativo.

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

O método SetCompatibilityVersion permite que um aplicativo ASP.NET Core 2.x opte por incluir ou excluir alterações de comportamento que podem causar interrupções, introduzidas no ASP.NET Core MVC 2.1 ou 2.2. Essas alterações de comportamento potencialmente interruptivas geralmente estão em como o subsistema MVC se comporta e como seu código é 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 como ASP.NET Core 2.2:

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

Recomendamos que você teste seu aplicativo usando a versão mais recente (CompatibilityVersion.Latest). Prevemos que a maioria dos aplicativos não terá alterações no comportamento que causem interrupções usando a versão mais recente.

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

  • Não se aplica a todas as alterações da versão 2.1 ou posteriores; destina-se a alterações que possam afetar o comportamento de runtime do ASP.NET Core no subsistema MVC.
  • Não se estende para ASP.NET Core 3.0.

A compatibilidade padrão para aplicativos do ASP.NET Core 2.1 e 2.2 que não chamam 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 como ASP.NET Core 2.2, exceto pelos seguintes comportamentos:

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 enfrentam alterações significativas no comportamento, use as opções de compatibilidade apropriadas:

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

A MvcOptions documentação tem uma boa explicação do 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, comportamentos antigos suportados por opções de compatibilidade foram removidos. Achamos que essas são mudanças positivas que beneficiam quase todos os usuários. Ao introduzir essas alterações no 2.1 e 2.2, a maioria dos aplicativos pode se beneficiar, enquanto outros têm tempo para atualizar.