Versione di compatibilità per ASP.NET Core MVC

Il SetCompatibilityVersion metodo è un metodo no-op per le app ASP.NET Core 3.0. Ovvero, la chiamata SetCompatibilityVersion con qualsiasi valore di CompatibilityVersion non ha alcun impatto sull'applicazione.

• La versione secondaria successiva di ASP.NET Core può fornire un nuovo CompatibilityVersion valore.
• CompatibilityVersion i valori Version_2_0 tramite Version_2_2 sono contrassegnati come [Obsolete(...)].
• Vedere Modifiche dell'API di rilievo in Antiforgery, CORS, Diagnostica, Mvc e Routing. Questo elenco include modifiche di rilievo per le opzioni di compatibilità.

Per informazioni SetCompatibilityVersion sul funzionamento delle app ASP.NET Core 2.x, selezionare la versione ASP.NET Core 2.2 di questo articolo.

Il SetCompatibilityVersion metodo consente a un'app ASP.NET Core 2.x di acconsentire esplicitamente o rifiutare esplicitamente le modifiche di comportamento potenzialmente di rilievo introdotte in ASP.NET Core MVC 2.1 o 2.2. Queste modifiche potenzialmente importanti del comportamento riguardano in genere il funzionamento del sottosistema MVC e la modalità con cui il codice dell'utente viene chiamato dal runtime. Se si acconsente esplicitamente, si ottiene il comportamento più recente e il comportamento a lungo termine di ASP.NET Core.

Il codice seguente imposta la modalità di compatibilità su ASP.NET Core 2.2:

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

È consigliabile testare l'app usando la versione più recente (CompatibilityVersion.Latest). Microsoft prevede che la maggior parte delle app non riscontrerà modifiche importanti del comportamento quando viene usata la versione più recente.

Le app che chiamano SetCompatibilityVersion(CompatibilityVersion.Version_2_0) sono protette da modifiche di comportamento potenzialmente di rilievo introdotte nelle versioni MVC di ASP.NET Core 2.1/2.2. La protezione:

• Non è valida per tutte le modifiche 2.1 e successive, ma è destinata alle modifiche potenzialmente importanti del comportamento del runtime ASP.NET Core nel sottosistema MVC.
• Non si estende a ASP.NET Core 3.0.

La compatibilità predefinita per ASP.NET app Core 2.1 e 2.2 che non chiamano SetCompatibilityVersion è compatibilità 2.0. In altri termini il fatto di non chiamare SetCompatibilityVersion equivale a chiamare SetCompatibilityVersion(CompatibilityVersion.Version_2_0).

Il codice seguente imposta la modalità di compatibilità su ASP.NET Core 2.2, con l'eccezione dei comportamenti seguenti:

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

Per le app che riscontrano modifiche potenzialmente importanti del comportamento, l'uso delle opzioni di compatibilità appropriate:

• Consente di usare la versione più recente e di rifiutare esplicitamente modifiche importanti del comportamento specifiche.
• Garantisce il tempo necessario per l'aggiornamento dell'app, che in tal modo potrà funzionare con le modifiche più recenti.

La documentazione di MvcOptions offre una spiegazione chiara delle modifiche e dei motivi per cui queste rappresentano un miglioramento per la maggior parte degli utenti.

Con ASP.NET Core 3.0, i comportamenti precedenti supportati dalle opzioni di compatibilità sono stati rimossi. Queste modifiche positive andranno a vantaggio della maggior parte degli utenti. Introducendo queste modifiche nella versione 2.1 e 2.2, la maggior parte delle app può trarre vantaggio, mentre altre hanno tempo per l'aggiornamento.