Nouveautés d’ASP.NET Web API 2.2

  • Article

par Microsoft

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

Télécharger

Les fonctionnalités d’exécution sont publiées sous forme de packages NuGet sur la galerie NuGet. Tous les packages d’exécution suivent la spécification du contrôle de version sémantique . Le dernier package API Web ASP.NET 2.2 a la version suivante : « 5.2.0 ». Vous pouvez installer ou mettre à jour ces packages via NuGet. La version inclut également les 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.2.0

Documentation

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

Nouvelles fonctionnalités de API Web ASP.NET 2.2

OData v4

Cette version ajoute la prise en charge du protocole OData v4. Pour plus d’informations, consultez la documentation sur l’API web OData v4.

Voici quelques-unes des principales fonctionnalités et modifications apportées à OData v4 :

Améliorations du routage des attributs

Le routage d’attributs fournit désormais un point d’extensibilité appelé IDirectRouteProvider, qui permet un contrôle total sur la façon dont les routes d’attributs sont découvertes et configurées. Un IDirectRouteProvider est chargé de fournir une liste d’actions et de contrôleurs, ainsi que les informations d’itinéraire associées pour spécifier exactement la configuration de routage souhaitée pour ces actions. Une implémentation IDirectRouteProvider peut être spécifiée lors de l’appel de MapAttributes/MapHttpAttributeRoutes.

La personnalisation d’IDirectRouteProvider sera plus simple en étendant notre implémentation par défaut, DefaultDirectRouteProvider. Cette classe fournit des méthodes virtuelles substituables distinctes pour modifier la logique de découverte des attributs, de création d’entrées de route et de découverte du préfixe de route et du préfixe de zone.

Voici quelques exemples sur ce que vous pouvez faire avec ce nouveau point d’extensibilité :

  1. Prise en charge de l’héritage des attributs route

    Exemple :

    Ici, une requête telle que « /api/values/10 » retournerait correctement « Success:10 »

    public class BaseController : ApiController
{
    [Route("{id:int}")]
    public string Get(int id)
    {
        return "Success:" + id;
    }
}
[RoutePrefix("api/values")]
public class ValuesController : BaseController
{
}
       
config.MapHttpAttributeRoutes(new CustomDirectRouteProvider());
public class CustomDirectRouteProvider : DefaultDirectRouteProvider
{
    protected override IReadOnlyList<IDirectRouteFactory> 
    GetActionRouteFactories(HttpActionDescriptor actionDescriptor)
    {
        return actionDescriptor.GetCustomAttributes<IDirectRouteFactory>
        (inherit: true);
    }
}

  2. Fournissez un nom d’itinéraire par défaut pour vos itinéraires d’attribut en suivant une convention que vous aimez. Par défaut, le routage d’attributs ne crée pas automatiquement de noms pour les itinéraires d’attributs.

  3. Modifiez le modèle d’itinéraire des itinéraires d’attribut à un emplacement central avant qu’ils ne se retrouvent dans la table de routage.

Prise en charge du client d’API web pour Windows Phone 8.1

Vous pouvez maintenant utiliser le package NuGet client de l’API web pour implémenter votre logique cliente d’API web lors du ciblage Windows Phone 8.1 ou à partir d’une application universelle.

Problèmes connus et changements cassants

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

OData v4

Générateur de modèles

Problème : Les fonctions surchargées n’ont pas pu être exposées en tant que FunctionImport

S’il existe 2 fonctions surchargées et qu’elles sont également FunctionImport comme indiqué ci-dessous, la demande de ~/GetAllConventionCustomers(CustomerName={customerName}) aboutit à System.InvalidOperationException.

<Function Name="GetAllConventionCustomers" 
ReturnType="Collection(WebStack.QA.Test.OData.UnboundOperation.ConventionCustomer)" 
IsComposable="true" />
<Function Name="GetAllConventionCustomers" 
ReturnType="Collection(WebStack.QA.Test.OData.UnboundOperation.ConventionCustomer)" 
IsComposable="true">
<Parameter Name="CustomerName" Type="Edm.String" FixedLength="false" 
Unicode="false" />
</Function>
...
<FunctionImport Name="GetAllConventionCustomers" 
Function="WebStack.QA.Test.OData.UnboundOperation.GetAllConventionCustomers" 
EntitySet="ConventionCustomers" IncludeInServiceDocument="true" />

Solution de contournement : la solution de contournement de ce problème consiste à ajouter les deux surcharges de fonction en tant que FunctionImports.

Routage OData

Les littéraux de chaîne qui incluent la barre oblique encodée d’URL (%2F) et la barre oblique inverse(%5C) provoquent une erreur 404 lorsqu’ils sont utilisés dans les chemins de ressources OData.

Par exemple, les littéraux de chaîne peuvent être utilisés dans les chemins de ressources OData en tant que paramètres de fonctions ou de valeurs de clé de jeux d’entités.

/Employees/Total.GetCount(Name='Name%2F')

/Employees('Name%5C')

Lorsque les services reçoivent de telles demandes, les hôtes annulent la séquence d’échappement avant de les transmettre au runtime de l’API web. Cela protège contre les attaques comme celles-ci :

http://www.contoso.com/..%2F..%2F/Windows/System32/cmd.exe?/c+dir+c:

La pile OData de l’API web renvoie alors une erreur 404 (introuvable). Pour éviter cette erreur, votre client doit utiliser les séquences d’échappement doubles pour la barre oblique (%252F) et la barre oblique inverse (%255C). Cela ne se produit pas pour les chaînes de requête telles que /Employees?$filter=Name eq 'Name%2F'

Notez que les barres obliques sans échappement ('/') et les barres obliques inverses ('') ne sont pas légales dans les littéraux de chaîne de chemin de ressource OData. Les barres obliques ne doivent apparaître que comme séparateurs de chemin d’accès et les barres obliques inverses ne doivent pas apparaître du tout dans le chemin de la ressource OData. (Les deux sont utilisables dans certaines parties d’une chaîne de requête OData.)

Solution de contournement : vous pouvez remplacer la méthode Parse de DefaultODataPathHandler pour échapper la barre oblique et la barre oblique inverse dans les littéraux de chaîne avant de les analyser. Vous trouverez un exemple de cette approche ici.

OData v3

[Interrogeable]

L’attribut [Interrogeable] est déconseillé. Les nouvelles applications OData v3 doivent utiliser System.Web.Http.OData.EnableQueryAttribute.

La méthode d’extension ODataHttpConfigurationExtensions.EnableQuerySupport ajoute désormais un EnableQueryAttribute à la collection de filtres globale. Si des contrôleurs ont l’attribut [Interrogeable], l’appel config.EnableQuerySupport() entraîne l’échec de l’attribut [Interrogeable]

La méthode recommandée pour résoudre ce problème consiste à remplacer toutes les instances de QueryableAttribute par System.Web.Http.OData.EnableQueryAttribute.

Une autre solution de contournement consiste à utiliser le code suivant dans votre configuration d’API web :

config.EnableQuerySupport(new QueryableAttribute());

Routage des attributs

Problème : La liaison de modèle de type complexe qui est décorée avec l’attribut FromUri se comporte différemment lors de l’utilisation du routage d’attributs.

Problème : Générer une génération automatique de l’API MVC/Web dans un projet avec des packages 5.2.0 entraîne la création de packages 5.1.2 pour ceux qui n’existent pas déjà dans le projet

La mise à jour des packages NuGet pour ASP.NET MVC 5.2 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 (par exemple, 5.1.2 dans Update 2). Par conséquent, la ASP.NET la génération automatique installe la version précédente (par exemple, 5.1.2 dans Update 2) des packages requis, s’ils ne sont pas déjà disponibles dans vos projets. Toutefois, la ASP.NET la génération automatique 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 de vos projets vers l’API Web 2.2 ou ASP.NET MVC 5.2, assurez-vous que les versions de l’API web et de ASP.NET MVC sont cohérentes.

Microsoft.AspNet.OData 5.2.1

Le package Microsoft.AspNet.OData 5.2.1 contient des mises à jour des dépendances NuGet, mais aucun correctif de bogue. Avec cette mise à jour, il n’existe plus de dépendance stricte envers Microsoft.OData.Core 6.4.0, mais une mise à niveau vers n’importe quelle version comprise entre 6.4.0 et 7.0.0.

Microsoft.AspNet.WebAPI 5.2.2

Dans cette version, nous avons apporté une modification de dépendance pour Json.Net 6.0.4. Pour plus d’informations sur les nouveautés de cette version de Json.NET, consultez Json.NET 6.0 version 4 - Fusion JSON, injection de dépendances. Cette version n’a pas d’autres nouvelles fonctionnalités ou correctifs de bogues dans l’API web. Nous avons par la suite mis à jour tous les autres packages dépendants que nous possédons pour dépendre de cette nouvelle version de l’API web.

Microsoft.AspNet.WebAPI 5.2.3 Bêta

Vous pouvez en savoir plus sur la version ici. Cette version contient uniquement des correctifs de bogues.