Vue d'ensemble du modèle de programmation Web HTTP WCF

Article
05/10/2023

Le modèle de programmation HTTP Web WCF (Windows Communication Foundation) fournit les éléments de base requis pour générer des services HTTP Web avec WCF. Les services HTTP Web WCF sont conçus pour être accessibles à l'éventail de clients le plus large possible (y compris les navigateurs Web). Ils ont les spécifications uniques suivantes :

URI et traitement des URI Les URI jouent un rôle central dans la conception de services HTTP Web. Le modèle de programmation HTTP Web WCF utilise les classes UriTemplate et UriTemplateTable pour fournir des fonctions de traitement des URI.
Prise en charge des opérations GET et POST Les services HTTP Web utilisent le verbe GET pour la récupération des données, en plus de divers verbes d’appel pour la modification de données et l'appel distant. Le modèle de programmation HTTP Web WCF utilise WebGetAttribute et WebInvokeAttribute pour associer des opérations de service à la fois à GET et à d'autres verbes HTTP comme PUT, POST et DELETE.
Formats de données variés Les services de style Web traitent de nombreux types de données en plus des messages SOAP. Le modèle de programmation HTTP Web WCF utilise WebHttpBinding et WebHttpBehavior pour prendre en charge de nombreux formats de données différents, y compris les documents XML, l'objet de données JSON et les flux de données de contenu binaire tels que les images, les fichiers vidéo ou le texte brut.

Le modèle de programmation HTTP Web WCF étend la portée de WCF pour prendre en charge des scénarios de style Web qui incluent les services HTTP Web, AJAX et JSON, et les flux de syndication (ATOM/RSS). Pour plus d’informations sur les services AJAX et JSON, consultez Intégration d’AJAX et prise en charge de JSON. Pour plus d’informations sur la syndication, consultez Vue d’ensemble de la syndication WCF.

Il n'existe aucune restriction supplémentaire sur les types de données qui peuvent être retournées à partir d'un service Web HTTP. Tout type sérialisable peut être retourné à partir d'une opération de service WEB HTTP. Parce que les opérations de service WEB HTTP peuvent être appelées par un navigateur Web, il existe une restriction sur les types de données pouvant être spécifiées dans une URL. Pour plus d’informations sur les types pris en charge par défaut, consultez la section URL et paramètres de chaîne de requête UriTemplate ci-dessous. Le comportement par défaut peut être modifié en fournissant votre propre implémentation T:System.ServiceModel.Dispatcher.QueryStringConverter, qui indique comment convertir les paramètres spécifiés dans une URL en type de paramètre réel. Pour plus d'informations, consultez QueryStringConverter

Attention

Les services écrits avec le modèle de programmation HTTP Web WCF n’utilisent pas les messages SOAP. SOAP n’étant pas utilisé, les fonctionnalités de sécurité fournies par WCF ne peuvent pas l’être non plus. Toutefois, vous pouvez utiliser la sécurité basée sur le transport en hébergeant votre service avec HTTPS. Pour plus d'informations sur la sécurité WCF, consultez Vue d’ensemble de la sécurité.

Avertissement

L’installation d’une extension WebDAV pour IIS peut entraîner les services HTTP Web à retourner une erreur HTTP 405 lorsque l’extension WebDav essaie de gérer toutes les demandes PUT. Pour contourner ce problème, vous pouvez désinstaller l’extension WebDav ou désactiver l’extension WebDav pour votre site web. Pour plus d’informations, consultez IIS et WebDav

Traitement des URI avec UriTemplate et UriTemplateTable

Les modèles URI fournissent une syntaxe efficace pour exprimer des larges jeux d'URI dont la structure est semblable. Par exemple, le modèle suivant exprime le jeu de tous les URI à trois segments qui commencent par "a" et se terminent par "c" sans tenir compte de la valeur du segment intermédiaire : a/{segment}/c

Ce modèle décrit des URI comme suit :

a/x/c
a/y/c
a/z/c
Et ainsi de suite.

Dans ce modèle, la notation avec accolade ("{segment}") indique un segment variable au lieu d'une valeur littérale.

Le .NET Framework fournit une API sur l'utilisation des modèles d'URI appelée UriTemplate. UriTemplates vous permet d'effectuer les opérations suivantes :

Vous pouvez appeler une des méthodes Bind avec un jeu de paramètres pour produire un URI complètement fermé qui correspond au modèle. Cela signifie que toutes les variables dans le modèle URI sont remplacées par des valeurs réelles.
Vous pouvez appeler Match() avec un URI candidat qui utilise un modèle pour décomposer les parties qui constituent un URI candidat et qui retourne un dictionnaire qui contient les différentes parties de l'URI libellé selon les variables du modèle.
Bind() et Match() sont des inverses qui vous permettent d'appeler Match( Bind(x)) et de revenir dans le même environnement de démarrage.

Il arrive souvent (surtout sur le serveur où la distribution d'une demande vers une opération de service basée sur l'URI est nécessaire) de vouloir effectuer le suivi d'un jeu d'objets UriTemplate dans une structure de données qui peut adresser indépendamment chacun des modèles contenus. UriTemplateTable représente un ensemble de modèles d'URI et sélectionne la meilleure correspondance en fonction d'un ensemble de modèles et d'un URI candidat. Cela n'est pas lié à une pile réseau particulière (WCF inclus) ; vous pouvez donc l'utiliser partout quand cela est nécessaire.

Le modèle de service WCF utilise UriTemplate et UriTemplateTable pour associer des opérations de service à un jeu d'URI décrit par un UriTemplate. Une opération de service est associée à un UriTemplate à l'aide de WebGetAttribute ou de WebInvokeAttribute. Pour plus d’informations sur UriTemplate et UriTemplateTable, consultez UriTemplate et UriTemplateTable

Attributs WebGet et WebInvoke

Les services HTTP Web WCF utilisent des verbes de récupération (par exemple, HTTP GET) en plus de différents verbes d’appel (par exemple, HTTP POST, PUT et DELETE). Le modèle de programmation HTTP Web WCF permet aux développeurs de service de contrôler le modèle d’URI et le verbe associés à leurs opérations de service avec WebGetAttribute et WebInvokeAttribute. WebGetAttribute et WebInvokeAttribute vous permettent de contrôler comment les opérations individuelles sont attachées aux URI et les méthodes HTTP associées à ces URI. Par exemple, ajouter WebGetAttribute et WebInvokeAttribute dans le code suivant.

[ServiceContract]
interface ICustomer
{
  //"View It"

  [WebGet]
  Customer GetCustomer():

  //"Do It"
    [WebInvoke]
  Customer UpdateCustomerName( string id,
                               string newName );
}

Le code précédent vous permet d'effectuer les demandes HTTP suivantes.

GET /GetCustomer

POST /UpdateCustomerName

WebInvokeAttribute prend la valeur POST par défaut mais vous pouvez l'utiliser aussi pour d'autres verbes.

[ServiceContract]
interface ICustomer
{
  //"View It" -> HTTP GET
    [WebGet( UriTemplate="customers/{id}" )]
  Customer GetCustomer( string id ):

  //"Do It" -> HTTP PUT
  [WebInvoke( UriTemplate="customers/{id}", Method="PUT" )]
  Customer UpdateCustomer( string id, Customer newCustomer );
}

Pour voir un exemple complet d’un service WCF qui utilise le modèle de programmation HTTP Web WCF, consultez Guide pratique pour créer un service HTTP web WCF de base

Paramètres de chaîne de requête UriTemplate et URL

Les services de style Web peuvent être appelés depuis un navigateur Web en tapant une URL associée à une opération de service. Ces opérations de service peuvent accepter des paramètres de chaîne de requête qui doivent être spécifiés sous forme de chaîne dans l'URL. Le tableau suivant affiche les types qui peuvent être passés dans une URL et le format utilisé.

Type	Format
Byte	0 - 255
SByte	-128 - 127
Int16	-32768 - 32767
Int32	-2,147,483,648 - 2,147,483,647
Int64	-9,223,372,036,854,775,808 - 9,223,372,036,854,775,807
UInt16	0 - 65535
UInt32	0 - 4,294,967,295
UInt64	0 - 18,446,744,073,709,551,615
Single	-3.402823e38 - 3.402823e38 (la notation d'exposant n'est pas requise)
Double	-1.79769313486232e308 - 1.79769313486232e308 (la notation d'exposant n'est pas requise)
Char	Tout caractère unique
Decimal	Tout décimal en notation standard (aucun exposant)
Boolean	True ou False (ne respecte pas la casse)
String	Toute chaîne (la chaîne Null n'est pas prise en charge et aucun échappement n'est fait)
DateTime	MM/DD/YYYY MM/DD/YYYY HH:MM:SS [AM\|PM] Mois Jour Année Mois Jour Année HH:MM:SS [AM\|PM]
TimeSpan	DD.HH:MM:SS Où DD = jours, HH = heures, MM = minutes, SS = secondes
Guid	Un GUID, par exemple : 936DA01F-9ABD-4d9d-80C7-02AF85C822A8
DateTimeOffset	MM/DD/YYYY HH:MM:SS MM:SS Où DD = jours, HH = heures, MM = minutes, SS = secondes
Énumérations	La valeur d'énumération, par exemple, qui définit l'énumération comme indiqué dans le code suivant. `public enum Days{ Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday };` Chacune des valeurs d'énumération individuelles (ou leurs valeurs entières correspondantes) peut être spécifiée dans la chaîne de requête.
Types qui ont un `TypeConverterAttribute` pouvant convertir le type vers et depuis une représentation sous forme de chaîne.	Dépend du convertisseur de type.

Formats et le modèle de programmation Web HTTP WCF

Le modèle de programmation HTTP Web WCF a de nouvelles fonctionnalités permettant d’utiliser un grand nombre de formats de données différents. Au niveau de la couche de liaison, WebHttpBinding peut lire et écrire les différents types suivants de données :

XML
JSON
Flux binaires opaques

Cela signifie que le modèle de programmation HTTP Web WCF peut traiter tout type de données, mais vous risquez de programmer à l'encontre de Stream.

.NET Framework 3.5 assure la prise en charge des données JSON (AJAX) ainsi que des flux de syndication (notamment ATOM et RSS). Pour plus d’informations sur ces fonctionnalités, consultez Mise en forme HTTP Web WCF, Vue d’ensemble de la syndication WCF et Intégration d'AJAX et prise en charge de JSON.

Modèle de programmation Web HTTP WCF et sécurité

Comme le modèle de programmation HTTP Web WCF ne prend pas en charge les protocoles WS-*, la seule manière de sécuriser un service HTTP Web WCF consiste à exposer le service via HTTPS avec SSL. Pour plus d’informations sur la configuration de SSL avec IIS 7.0, consultez Comment implémenter SSL dans IIS.

Dépannage du modèle de programmation HTTP Web WCF

Lors de l'appel de services Web HTTP WCF à l'aide d'un ChannelFactoryBase<TChannel> afin de créer un canal, le WebHttpBehavior utilise le EndpointAddress défini dans le fichier de configuration même si un EndpointAddress différent est passé au ChannelFactoryBase<TChannel>.