Delen via


Compatibiliteitsversie voor ASP.NET Core MVC

Door Rick Anderson

De SetCompatibilityVersion methode is een no-op voor ASP.NET Core 3.0-apps. Dat wil gezegd dat het aanroepen SetCompatibilityVersion met een willekeurige waarde CompatibilityVersion geen invloed heeft op de toepassing.

Als u wilt zien hoe SetCompatibilityVersion u werkt met ASP.NET Core 2.x-apps, selecteert u de ASP.NET Core 2.2-versie van dit artikel.

Met de SetCompatibilityVersion-methode kan een ASP.NET Core 2.x-app zich aanmelden of afmelden voor mogelijk belangrijke gedragswijzigingen die zijn geïntroduceerd in ASP.NET Core MVC 2.1 of 2.2. Deze potentieel belangrijke gedragswijzigingen zijn doorgaans in de manier waarop het MVC-subsysteem zich gedraagt en hoe uw code wordt aangeroepen door de runtime. Als u zich aanmeldt, krijgt u het nieuwste gedrag en het langetermijngedrag van ASP.NET Core.

Met de volgende code wordt de compatibiliteitsmodus ingesteld op ASP.NET Core 2.2:

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

U wordt aangeraden uw app te testen met behulp van de nieuwste versie (CompatibilityVersion.Latest). We verwachten dat de meeste apps geen grote gedragsveranderingen zullen ondervinden bij gebruik van de nieuwste versie.

Apps die SetCompatibilityVersion(CompatibilityVersion.Version_2_0) aanroepen, worden beschermd tegen mogelijk problematische gedragswijzigingen die zijn geïntroduceerd in de ASP.NET Core 2.1/2.2 MVC-versies. Deze beveiliging:

  • Dit geldt niet voor alle wijzigingen in 2.1 of hoger, maar richt zich op potentieel verstorende wijzigingen in het runtimegedrag van ASP.NET Core binnen het MVC-subsysteem.
  • Wordt niet uitgebreid naar ASP.NET Core 3.0.

De standaardcompatibiliteit voor ASP.NET Core 2.1- en 2.2-apps die niet aanroep SetCompatibilityVersion, is compatibiliteit 2.0. Dat wil zeggen, niet SetCompatibilityVersion bellen is hetzelfde als SetCompatibilityVersion(CompatibilityVersion.Version_2_0) bellen.

Met de volgende code wordt de compatibiliteitsmodus ingesteld op ASP.NET Core 2.2, met uitzondering van het volgende gedrag:

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

Voor apps die te maken krijgen met veranderingen in het gedrag die tot verstoringen kunnen leiden, gebruikt u de juiste compatibiliteitsschakelaars:

  • Met dit kunt u de nieuwste release gebruiken en specifieke doorbrekende gedragswijzigingen uitsluiten.
  • Geeft u tijd om uw app bij te werken, zodat deze werkt met de meest recente wijzigingen.

De MvcOptions documentatie bevat een goede uitleg van wat er is gewijzigd en waarom de wijzigingen een verbetering zijn voor de meeste gebruikers.

Met ASP.NET Core 3.0 zijn oude gedragingen die worden ondersteund door compatibiliteitsswitches verwijderd. We vinden dat dit positieve veranderingen zijn die vrijwel alle gebruikers ten goede komen. Door deze wijzigingen in 2.1 en 2.2 te introduceren, kunnen de meeste apps profiteren, terwijl anderen tijd hebben om bij te werken.