ASP.NET Core, kompatibilita verzí a vliv na vývoj Web API

S vývojem nových verzí frameworku ASP.NET Core se Microsoft zaručil, že bude dodržovat určitá pravidla související se sémantickým verzováním. Na základě toho má vývojář jistotu, že nové minor verze frameworku s sebou nepřinesou žádné breaking changes a vývojář tak může bezpečně updatovat ASP.NET Core shared framework na webovém serveru, aniž by tím rozbil nasazené aplikace.

Compatibility Version

Problém této myšlenky je, že Microsoft občas potřebuje udělat breaking changes, které si nezaslouží novou major verzi. Řešením tohoto problému je Compatibility Version. Nově přidané chování se zkrátka obalí do IFu a při updatu na novou verzi se nadále používá původní implementace. Vývojář může volitelně vzít změny na vědomí a přepnout se chování nové verze. Řečí kódu to vypadá takto:

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

Mohu tedy sice využívat ASP.NET Core 2.2., chování některých částí aplikace však odpovídá verzi 2.1. Aby to nebylo málo, je volitelně možné použít určitou Compatibility Version a k tomu vybrané funkce nastavit ručně.

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
        .AddMvcOptions(options =>
        {
            // nekombinovat auth filtry (verze 2.0)
            options.AllowCombiningAuthorizeFilters = false;
        });
}

S příchodem verze ASP.NET Core 3.0 toto nastavení zmizí a bude se používat jedno společné nastavení. Samozřejmě jen do té doby, než bude potřeba někde udělat podobnou vyhýbku.

API Behavior Options

Chování Compatibility Version se nejvíce projevuje při vývoji RESTových API v ASP.NET Core. Microsoft totiž vymyslel způsob, jak automatizovat chování API v případě vzniku chyb (400, 500) a toto chování ve verzi ASP.NET Core 2.1 naskládal do tzv. API Behavior Options.

services.Configure<ApiBehaviorOptions>(o =>
{
    o.InvalidModelStateResponseFactory = context =>
    {
        return new BadRequestObjectResult(new { Message = "Error message"});
    };
};

S příchodem verze ASP.NET Core 2.2 následně změnil výchozí chování API Behavior Options z předchozí verze a zpřístupnil nové API pro nastavení chování:

services.AddMvc().ConfigureApiBehaviorOptions(o =>
{
    o.InvalidModelStateResponseFactory = context =>
    {
        return new BadRequestObjectResult(new { Message = "Error message"});
    };
});

Protože se výchozí chování v každé verzi mění, je nutné vybrat si vyhovující Compatibility Version.

Atribut [ApiController]

Aby to nebylo málo, všechno to chování API (tedy API Behavior Options) funguje jen za předpokladu, že nad controllerem použijete atribut [ApiController]. Od verze 2.2 je navíc možné atribut zaregistrovat na úrovni assembly (což se mi osobně vůbec nelíbí):

[assembly: ApiController]
namespace MyWebsite.Api
{
    public class Startup
    {
    }
} 

Osobně toto chování zapínám na vlastním BaseApiControlleru.

Závěr a co s tím

Mé osobní doporučení je používat atribut [ApiController] na úrovni vlastního base controlleru. Dále už ve všech aplikacích využívám ASP.NET Core 2.2 shared framework (metabalíček Microsoft.AspNetCore.App) a jako Compatibility Version 2.2. Tato nejnovější verze má smysluplně nastavená pravidla pro generování chybových zpráv a mnoho vývojářů nebude potřebovat cokoliv ručně dopisovat.