Nouveautés d’ASP.NET Web API 2.1

par Microsoft

Cette rubrique décrit les nouveautés de API Web ASP.NET 2.1.

• Télécharger

• Documentation

• Nouvelles fonctionnalités de API Web ASP.NET 2.1

  • Gestion globale des erreurs
  • Améliorations du routage des attributs
  • Améliorations de la page d’aide
  • Prise en charge d’IgnoreRoute
  • Formateur Media-Type BSON
  • Meilleure prise en charge des filtres asynchrones
  • Analyse des requêtes pour la bibliothèque de mise en forme du client

• Problèmes connus et modifications cassants

• Résolution des bogues

Télécharger

Les fonctionnalités d’exécution sont publiées sous forme de packages NuGet dans la galerie NuGet. Tous les packages d’exécution suivent la spécification du contrôle de version sémantique . Le dernier package RTM API Web ASP.NET 2.1 a la version suivante : « 5.1.2 ». Vous pouvez installer ou mettre à jour ces packages via NuGet. La version inclut également des packages localisés correspondants sur NuGet.

Vous pouvez installer ou mettre à jour les packages NuGet publiés à l’aide de la console du Gestionnaire de package NuGet :

Install-Package Microsoft.AspNet.WebApi -Version 5.1.2

Documentation

Des tutoriels et d’autres informations sur API Web ASP.NET RTM 2.1 sont disponibles sur le site web ASP.NET (https://www.asp.net/web-api).

Nouvelles fonctionnalités de API Web ASP.NET 2.1

Gestion globale des erreurs

Toutes les exceptions non gérées peuvent désormais être journalisées via un mécanisme central et le comportement des exceptions non gérées peut être personnalisé.

L’infrastructure prend en charge plusieurs enregistreurs d’événements d’exception, qui voient tous l’exception non prise en charge et des informations sur le contexte dans lequel elle s’est produite, comme la demande en cours de traitement à ce moment-là.

Par exemple, le code suivant utilise System.Diagnostics.TraceSource pour consigner toutes les exceptions non gérées :

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

Vous pouvez également remplacer le gestionnaire d’exceptions par défaut, afin de personnaliser entièrement le message de réponse HTTP envoyé lorsqu’une exception non prise en charge se produit.

Nous avons fourni un exemple qui consigne toutes les exceptions non prises en charge via l’infrastructure ELMAH populaire.

Améliorations du routage des attributs

Le routage d’attributs prend désormais en charge les contraintes, ce qui permet le contrôle de version et la sélection d’itinéraires en fonction de l’en-tête. En outre, de nombreux aspects des itinéraires d’attributs sont désormais personnalisables via l’interface IDirectRouteFactory et la classe RouteFactoryAttribute . Le préfixe d’itinéraire est désormais extensible via l’interface IRoutePrefix et la classe RoutePrefixAttribute .

Nous avons fourni un exemple qui utilise des contraintes pour filtrer dynamiquement les contrôleurs par un en-tête HTTP « api-version ».

Améliorations de la page d’aide

L’API web 2.1 inclut les améliorations suivantes apportées aux pages d’aide de l’API :

• Documentation des propriétés individuelles des paramètres ou des types d’actions de retour.
• Documentation des annotations de modèle de données.

La conception de l’interface utilisateur des pages d’aide a également été mise à jour pour prendre en charge ces modifications.

Prise en charge d’IgnoreRoute

L’API web 2.1 prend en charge l’ignorance des modèles d’URL dans le routage de l’API web, via un ensemble de méthodes d’extension IgnoreRoute sur HttpRouteCollection. Ces méthodes obligent l’API web à ignorer toutes les URL qui correspondent à un modèle spécifié et à autoriser l’hôte à appliquer un traitement supplémentaire, le cas échéant.

L’exemple suivant ignore les URI qui commencent par un segment « content » :

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

Formateur Media-Type BSON

L’API web prend désormais en charge le format filaire BSON , à la fois sur le client et sur le serveur.

Pour activer BSON côté serveur, ajoutez le BsonMediaTypeFormatter à la collection des formateurs :

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

Voici comment un client .NET peut utiliser le format 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() });

Nous avons fourni un exemple qui montre à la fois le côté client et côté serveur.

Pour plus d’informations, consultez Prise en charge de BSON dans l’API web 2.1

Meilleure prise en charge des filtres asynchrones

L’API web prend désormais en charge un moyen simple de créer des filtres qui s’exécutent de manière asynchrone. Cette fonctionnalité est utile si votre filtre a besoin d’effectuer une action asynchrone, telle que l’accès à une base de données. Auparavant, pour créer un filtre asynchrone, vous deviez implémenter l’interface de filtre vous-même, car les classes de base de filtre exposaient uniquement les méthodes synchrones. Vous pouvez maintenant remplacer les méthodes virtuelles On*Async de la classe de base de filtre.

Par exemple :

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

Les classes AuthorizationFilterAttribute, ActionFilterAttribute et ExceptionFilterAttribute prennent toutes en charge async dans l’API Web 2.1.

Analyse des requêtes pour la bibliothèque de mise en forme du client

Auparavant, System.Net.Http.Formatting prenait en charge l’analyse et la mise à jour des requêtes URI pour le code côté serveur, mais cette fonctionnalité manquait à la bibliothèque portable équivalente. Dans l’API Web 2.1, une application cliente peut désormais analyser et mettre à jour facilement une chaîne de requête.

Les exemples suivants montrent comment analyser, modifier et générer des requêtes URI. (Les exemples montrent une application console par souci de simplicité.)

// 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

Problèmes connus et modifications cassants

Cette section décrit les problèmes connus et les changements cassants dans le API Web ASP.NET RTM 2.1.

Routage des attributs

Les ambiguïtés dans les correspondances de routage d’attribut signalent désormais une erreur plutôt que de choisir la première correspondance.

Il est interdit aux itinéraires d’attribut d’utiliser le paramètre {controller} et d’utiliser le paramètre {action} sur les itinéraires placés sur des actions. Ces paramètres provoqueraient très probablement des ambiguïtés.

La génération de modèles MVC/API web dans un projet avec des packages 5.1 aboutit à des packages 5.0 pour ceux qui n’existent pas déjà dans le projet

La mise à jour des packages NuGet pour API Web ASP.NET 2.1 RTM ne met pas à jour les outils Visual Studio, tels que ASP.NET structure ou le modèle de projet d’application web ASP.NET. Ils utilisent la version précédente des packages d’exécution ASP.NET (5.0.0.0). Par conséquent, la ASP.NET la structure installera la version précédente (5.0.0.0) des packages requis, s’ils ne sont pas déjà disponibles dans vos projets. Toutefois, le ASP.NET la génération de modèles dans Visual Studio 2013 RTM ou Update 1 ne remplace pas les derniers packages de vos projets.

Si vous utilisez ASP.NET structure après la mise à jour des packages vers l’API Web 2.1 ou ASP.NET MVC 5.1, assurez-vous que les versions de l’API web et de MVC sont cohérentes.

Renommages de type

Certains des types utilisés pour l’extensibilité du routage des attributs ont été renommés de la RC en RTM 2.1.

Ancien nom de type (2.1 RC)	Nouveau nom de type (2.1 RTM)
IDirectRouteProvider	IDirectRouteFactory
RouteProviderAttribute	RouteFactoryAttribute
DirectRouteProviderContext	DirectRouteFactoryContext

Les filtres d’exceptions ne désencapsulent pas les exceptions agrégées levées dans les actions asynchrones

Auparavant, si une action asynchrone lançait une exception AggregateException, un filtre d’exception désencapsulait l’exception et OnException obtenait l’exception de base. Dans la version 2.1, le filtre d’exception ne l’annule pas, et OnException obtient l’objet AggregateException d’origine.

Correctifs de bogues

Cette version inclut également plusieurs correctifs de bogues.

Le package 5.1.2 contient des mises à jour IntelliSense, mais aucun correctif de bogue.