Novità dell'API Web ASP.NET 2.1

da Microsoft

Questo argomento descrive le novità per API Web ASP.NET 2.1.

• Scaricare

• Documentazione

• Nuove funzionalità in API Web ASP.NET 2.1

  • Gestione degli errori globali
  • Miglioramenti del routing degli attributi
  • Miglioramenti alla pagina della Guida
  • Supporto di IgnoreRoute
  • Formatore BSON Media-Type
  • Supporto migliore per i filtri asincroni
  • Analisi delle query per la libreria di formattazione client

• Problemi noti e modifiche di rilievo

• Correzioni di bug

Scarica

Le funzionalità di runtime vengono rilasciate come pacchetti NuGet nella raccolta NuGet. Tutti i pacchetti di runtime seguono la specifica Semantic Versioning . Il pacchetto RTM più recente API Web ASP.NET 2.1 ha la versione seguente: "5.1.2". È possibile installare o aggiornare questi pacchetti tramite NuGet. La versione include anche i pacchetti localizzati corrispondenti in NuGet.

È possibile installare o aggiornare i pacchetti NuGet rilasciati usando la console di Gestione pacchetti NuGet:

Install-Package Microsoft.AspNet.WebApi -Version 5.1.2

Documentazione

Le esercitazioni e altre informazioni su API Web ASP.NET 2.1 RTM sono disponibili dal sito Web ASP.NET (https://www.asp.net/web-api).

Nuove funzionalità in API Web ASP.NET 2.1

Gestione degli errori globali

Tutte le eccezioni non gestite possono ora essere registrate tramite un meccanismo centrale e il comportamento per le eccezioni non gestite può essere personalizzato.

Il framework supporta più loggger di eccezioni, che visualizzano tutte le eccezioni non gestite e le informazioni sul contesto in cui si è verificato, ad esempio la richiesta elaborata al momento.

Ad esempio, il codice seguente usa System.Diagnostics.TraceSource per registrare tutte le eccezioni non gestite:

public class TraceSourceExceptionLogger : ExceptionLogger
{
    private readonly TraceSource _traceSource;

    public TraceSourceExceptionLogger(TraceSource traceSource)
    {
        _traceSource = traceSource;
    }

    public override void Log(ExceptionLoggerContext context)
    {
        _traceSource.TraceEvent(TraceEventType.Error, 1,
            "Unhandled exception processing {0} for {1}: {2}",
            context.Request.Method,
            context.Request.RequestUri,
            context.Exception);
    }
}

config.Services.Add(typeof(IExceptionLogger), 
    new TraceSourceExceptionLogger(new 
    TraceSource("MyTraceSource", SourceLevels.All)));

È anche possibile sostituire il gestore di eccezioni predefinito, in modo che sia possibile personalizzare completamente il messaggio di risposta HTTP inviato quando si verifica un'eccezione non gestita.

È stato fornito un esempio che registra tutte le eccezioni non gestite tramite il framework ELMAH popolare.

Miglioramenti del routing degli attributi

Il routing degli attributi supporta ora i vincoli, abilitando la selezione della route basata su versioni e intestazione. Inoltre, molti aspetti delle route degli attributi sono ora personalizzabili tramite l'interfaccia IDirectRouteFactory e la classe RouteFactoryAttribute . Il prefisso di route è ora estendibile tramite l'interfaccia IRoutePrefix e la classe RoutePrefixAttribute .

È stato fornito un esempio che usa vincoli per filtrare dinamicamente i controller da un'intestazione HTTP "api-version".

Miglioramenti alla pagina della Guida

L'API Web 2.1 include i miglioramenti seguenti alle pagine della Guida api:

• Documentazione delle singole proprietà dei parametri o dei tipi restituiti di azioni.
• Documentazione delle annotazioni del modello di dati.

La progettazione dell'interfaccia utente delle pagine della Guida è stata aggiornata anche per gestire queste modifiche.

Supporto di IgnoreRoute

L'API Web 2.1 supporta l'ignorare i modelli DI URL nel routing api Web, tramite un set di metodi di estensione IgnoreRoute in HttpRouteCollection. Questi metodi consentono all'API Web di ignorare gli URL corrispondenti a un modello specificato e consentire all'host di applicare un'elaborazione aggiuntiva, se appropriato.

Nell'esempio seguente vengono ignorati gli URI che iniziano con un segmento "contenuto":

routes.IgnoreRoute("IgnoreContent", "content/{*paths}");
routes.MapHttpRoute("Default", "{controller}/{id}");

Formatore BSON Media-Type

L'API Web supporta ora il formato di fili BSON , sia sul client che sul server.

Per abilitare BSON sul lato server, aggiungere bsonMediaTypeFormatter all'insieme di formattatori:

config.Formatters.Add(new BsonMediaTypeFormatter());

Ecco come un client .NET può usare il formato BSON:

// Add Accept header.
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/bson"));

// POST data in BSON format.
HttpResponseMessage response = await client.PostAsync<MyData>("api/MyData", data, new 
BsonMediaTypeFormatter());

// GET data in BSON format.
data = await response.Content.ReadAsAsync<MyData>(new MediaTypeFormatter[] { 
  new BsonMediaTypeFormatter() });

È stato fornito un esempio che mostra sia il lato client che il lato server.

Per altre informazioni, vedere Supporto BSON nell'API Web 2.1

Supporto migliore per i filtri asincroni

L'API Web supporta ora un modo semplice per creare filtri che eseguono in modo asincrono. Questa funzionalità è utile è che il filtro deve eseguire un'azione asincrona, ad esempio l'accesso a un database. In precedenza, per creare un filtro asincrono, è necessario implementare l'interfaccia del filtro autonomamente, perché le classi di base del filtro espongono solo metodi sincroni. È ora possibile eseguire l'override dei metodi virtuali On*Async della classe base del filtro.

Ad esempio:

public class AsyncLoggingFilter : ActionFilterAttribute
{
    public override async Task OnActionExecutingAsync(HttpActionContext actionContext, CancellationToken cancellationToken)
    {
        await Trace.WriteAsync("Executing action named {0} for request {1}.", 
            actionContext.ActionDescriptor.ActionName, 
            actionContext.Request.GetCorrelationId());
    }
}

Le classi AuthorizationFilterAttribute, ActionFilterAttribute e ExceptionFilterAttribute supportano tutte le classi asincrone nell'API Web 2.1.

Analisi delle query per la libreria di formattazione client

In precedenza , System.Net.Http.Formatting supportava l'analisi e l'aggiornamento delle query URI per il codice lato server, ma la libreria portabile equivalente mancava di questa funzionalità. Nell'API Web 2.1 un'applicazione client può ora analizzare e aggiornare facilmente una stringa di query.

Negli esempi seguenti viene illustrato come analizzare, modificare e generare query URI. Gli esempi mostrano un'applicazione console per semplicità.

// Query parsing
HttpValueCollection collection = new Uri("http://api/something?catId=3&catId=4&dogId=1,2").ParseQueryString();

Console.WriteLine(collection["catId"]); // output: 3,4
Console.WriteLine(collection["dogId"]); // output: 1,2

// Modify the query
collection.Add("dogId", "7");

// Index into the values
Console.WriteLine(collection["catId"]); // output: 3,4
Console.WriteLine(collection["dogId"]); // output: 1,2,7

// Recreate the query string
Console.WriteLine(collection.ToString()); // output: catId=3&catId=4&dogId=1%2C2&dogId=7

// Query generation
HttpValueCollection newCollection = new HttpValueCollection();

newCollection.Add("catId", "1");
newCollection.Add("dogId", "7");

// Index into the values
Console.WriteLine(newCollection["catId"]); // output: 1
Console.WriteLine(newCollection["dogId"]); // output: 7

// Create the query string
Console.WriteLine(newCollection.ToString()); // catId=1&dogId=7

Problemi noti e modifiche di rilievo

Questa sezione descrive i problemi noti e le modifiche di rilievo nel API Web ASP.NET 2.1 RTM.

Routing degli attributi

Le ambiguità nel routing degli attributi segnalano ora un errore anziché scegliere la prima corrispondenza.

Le route degli attributi non possono usare il parametro {controller} e usare il parametro {action} sulle route inserite nelle azioni. Questi parametri causano molto probabilmente ambiguità.

Scaffolding MVC/Web API in un progetto con pacchetti 5.1 genera pacchetti 5.0 per quelli che non esistono già nel progetto

L'aggiornamento dei pacchetti NuGet per API Web ASP.NET 2.1 RTM non aggiorna gli strumenti di Visual Studio, ad esempio ASP.NET scaffolding o il modello di progetto applicazione Web ASP.NET. Usano la versione precedente dei pacchetti di runtime ASP.NET (5.0.0.0.0). Di conseguenza, il ASP.NET scaffolding installerà la versione precedente (5.0.0.0) dei pacchetti necessari, se non sono già disponibili nei progetti. Tuttavia, il ASP.NET scaffolding in Visual Studio 2013 RTM o Update 1 non sovrascrive i pacchetti più recenti nei progetti.

Se si usa ASP.NET scaffolding dopo aver aggiornato i pacchetti all'API Web 2.1 o ASP.NET MVC 5.1, assicurarsi che le versioni dell'API Web e MVC siano coerenti.

Rinomina il tipo

Alcuni dei tipi usati per l'estendibilità del routing degli attributi sono stati rinominati da RC a 2.1 RTM.

Nome del tipo precedente (2.1 RC)	Nuovo nome del tipo (2.1 RTM)
IDirectRouteProvider	IDirectRouteFactory
RouteProviderAttribute	RouteFactoryAttribute
DirectRouteProviderContext	DirectRouteFactoryContext

I filtri di eccezione non annullano le eccezioni di aggregazione generate nelle azioni asincrone

In precedenza, se un'azione asincrona genera un'eccezione AggregateException, un filtro di eccezione annulla l'eccezione e OnException otterrà l'eccezione di base. In 2.1 il filtro eccezione non lo annulla e OnException ottiene l'oggetto AggregateException originale.

Correzioni di bug

Questa versione include anche diverse correzioni di bug.

Il pacchetto 5.1.2 contiene aggiornamenti di IntelliSense, ma nessuna correzione di bug.