Vue d'ensemble de l'architecture de métadonnées
Windows Communication Foundation (WCF) fournit une infrastructure riche pour exporter, publier, récupérer et importer les métadonnées de service. Les services WCF utilisent les métadonnées pour décrire l'interaction avec les points de terminaison d'un service afin que les outils tels que Svcutil.exe puissent générer automatiquement le code client pour accéder au service.
La plupart des types qui composent l'infrastructure des métadonnées WCF réside dans l'espace de noms System.ServiceModel.Description.
WCF utilise la classe ServiceEndpoint pour décrire des points de terminaison dans un service. Vous pouvez utiliser WCF pour générer les métadonnées pour les points de terminaison de service ou importer les métadonnées de service pour générer des instances ServiceEndpoint.
représente les métadonnées pour un service sous la forme d'une instance du type MetadataSet dont la structure est fortement liée au format de la sérialisation des métadonnées définies dans WS-MetadataExchange. Le type MetadataSet regroupe les métadonnées de service réelles, telles que les documents WSDL (Web Services Description Language), les documents de schéma XML ou les expressions WS-Policy, sous la forme d'une collection d'instances MetadataSection. Chaque instance System.ServiceModel.Description.MetadataSection contient un dialecte de métadonnées spécifique et un identificateur. Un System.ServiceModel.Description.MetadataSection peut contenir les éléments suivants dans sa propriété MetadataSection.Metadata :
Métadonnées brutes.
Instance de MetadataReference.
Instance de MetadataLocation.
Les instances System.ServiceModel.Description.MetadataReference pointent vers un autre point de terminaison d'échanges de métadonnées (MEX) et les instances System.ServiceModel.Description.MetadataLocation pointent vers un document de métadonnées à l'aide d'une URL HTTP. WCF prend en charge l'utilisation de documents WSDL pour décrire des points de terminaison de service, des contrats de service, des liaisons, des modèles d'échange de messages, des messages et des messages d'erreur implémentés par un service. Les types de données utilisés par le service sont décrits dans les documents WSDL à l'aide du schéma XML. Pour plus d’informations, consultez Importation et exportation du schéma. Vous pouvez utiliser WCF pour exporter et importer des extensions WSDL pour le comportement de service, les comportements de contrat et les éléments de liaison qui étendent les fonctionnalités d’un service. Pour plus d’informations, consultez Exportation de métadonnées personnalisées pour une extension WCF.
Exportation des métadonnées de service
Dans WCF, le processus d'exportation de métadonnées consiste à décrire des points de terminaison de service et à les projeter dans une représentation parallèle standardisée qui permet aux clients de comprendre comment utiliser le service. Pour exporter des métadonnées à partir des instances ServiceEndpoint, utilisez une implémentation de la classe abstraite MetadataExporter. Une implémentation System.ServiceModel.Description.MetadataExporter génère des métadonnées encapsulée dans une instance MetadataSet.
La classe System.ServiceModel.Description.MetadataExporter fournit une infrastructure pour générer des expressions de stratégie qui décrivent les fonctions et les spécifications d'une liaison de point de terminaison et ses opérations, messages et erreurs associés. Ces expressions de stratégie sont capturées dans une instance PolicyConversionContext. Une implémentation System.ServiceModel.Description.MetadataExporter peut ensuite attacher ces expressions de stratégie aux métadonnées qu'elle génère.
System.ServiceModel.Description.MetadataExporter appelle chaque System.ServiceModel.Channels.BindingElement qui implémente l'interface IPolicyExportExtension dans la liaison d'un ServiceEndpoint lors de la génération d'un objet PolicyConversionContext devant être utilisé par l'implémentation System.ServiceModel.Description.MetadataExporter. Vous pouvez exporter de nouvelles assertions de stratégie en implémentant l'interface IPolicyExportExtension sur vos implémentations personnalisées du type BindingElement.
Le type WsdlExporter est l’implémentation de la classe abstraite System.ServiceModel.Description.MetadataExporter incluse dans WCF. Le type WsdlExporter génère les métadonnées WSDL avec les expressions de stratégie jointes.
Pour exporter des métadonnées WSDL ou des extensions WSDL personnalisées pour les comportements de point de terminaison, les comportements de contrat ou les éléments de liaison dans un point de terminaison de service, vous pouvez implémenter l’interface IWsdlExportExtension. Le WsdlExporter recherche dans une instance ServiceEndpoint des éléments de liaison, des comportements d'opération, des comportements de contrat et des comportements de point de terminaison qui implémentent l'interface IWsdlExportExtension lors de la génération du document WSDL.
Publication des métadonnées de service
Les services WCF publient les métadonnées en exposant un ou plusieurs points de terminaison de métadonnées. La publication des métadonnées de service rend les métadonnées de service disponibles à l'aide de protocoles standardisés, tels que les demandes MEX et HTTP/GET. Les points de terminaison de métadonnées sont semblables à d’autres points de terminaison de service en ce sens qu’ils ont une adresse, une liaison et un contrat. Vous pouvez ajouter des points de terminaison de métadonnées à un hôte de service dans la configuration ou dans le code.
Pour publier des points de terminaison de métadonnées pour un service WCF, vous devez d'abord ajouter une instance du comportement de service ServiceMetadataBehavior au service. L'ajout d'une instance System.ServiceModel.Description.ServiceMetadataBehavior à votre service augmente votre service en rendant possible la publication des métadonnées en exposant un ou plusieurs points de terminaison de métadonnées. Après avoir ajouté le comportement de service System.ServiceModel.Description.ServiceMetadataBehavior, vous pouvez ensuite exposer les points de terminaison de métadonnées qui prennent en charge le protocole MEX ou les points de terminaison de métadonnées qui répondent aux demandes HTTP/GET.
Pour ajouter des points de terminaison de métadonnées qui utilisent le protocole MEX, ajoutez des points de terminaison de service à votre hôte de service qui utilisent le contrat de service nommé IMetadataExchange.WCF définit l'interface IMetadataExchange qui porte ce nom de contrat de service. Les points de terminaison WS-MetadataExchange (ou points de terminaison MEX) peuvent utiliser l’une des quatre liaisons par défaut que les méthodes de fabrique statiques exposent sur la classe MetadataExchangeBindings afin d’établir une correspondance avec les liaisons par défaut utilisées par les outils WCF tels que Svcutil.exe. Vous pouvez également configurer des points de terminaison de métadonnées MEX à l’aide d’une liaison personnalisée.
ServiceMetadataBehavior utilise System.ServiceModel.Description.WsdlExporter pour exporter les métadonnées de tous les points de terminaison de service de votre service. Pour plus d’informations sur l’exportation de métadonnées à partir d’un service, consultez Exportation et importation de métadonnées.
Le ServiceMetadataBehavior augmente votre hôte de service en ajoutant une instance ServiceMetadataExtension sous la forme d'une extension à votre hôte de service. System.ServiceModel.Description.ServiceMetadataExtension fournit l'implémentation pour les protocoles de publication de métadonnées. Vous pouvez également utiliser System.ServiceModel.Description.ServiceMetadataExtension pour obtenir les métadonnées de service au moment de l'exécution en accédant à la propriété Metadata.
Attention
Si vous ajoutez un point de terminaison MEX dans votre fichier de configuration de l'application, puis tentez d'ajouter ServiceMetadataBehavior à votre hôte de service dans le code, vous obtenez l'exception suivante :
System.InvalidOperationException : Nom de contrat « IMetadataExchange » introuvable dans la liste des contrats implémentés par le service Service1. Ajoutez un ServiceMetadataBehavior au fichier de configuration ou directement à ServiceHost pour activer la prise en charge de ce contrat.
Vous pouvez remédier à ce problème en ajoutant ServiceMetadataBehavior dans le fichier de configuration, ou en ajoutant à la fois le point de terminaison et ServiceMetadataBehavior dans le code.
Pour obtenir un exemple d’ajout de ServiceMetadataBehavior dans un fichier de configuration d’application, consultez la Prise en main. Pour obtenir un exemple d’ajout de ServiceMetadataBehavior dans le code, consultez l’exemple Self-Host.
Attention
Lors de la publication de métadonnées pour un service qui expose deux contrats de service différents où chacun contient une opération du même nom, une exception est levée. Par exemple, si vous disposez d'un service qui expose un contrat de service appelé ICarService comportant une opération Get(Voiture c) et que le même service expose un contrat de service appelé IBookService comportant une opération Get(Livre b), une exception est levée ou un message d'erreur est affiché lors de la génération des métadonnées du service. Pour remédier à ce problème, effectuez l'une des opérations suivantes :
Récupération des métadonnées de service
WCF récupère des métadonnées de service à l'aide des protocoles standardisés tels que WS-MetadataExchange et les requêtes HTTP. Ces deux protocoles sont pris en charge par le type MetadataExchangeClient. Vous récupérez les métadonnées de service à l’aide du type System.ServiceModel.Description.MetadataExchangeClient en fournissant une adresse et une liaison facultative. La liaison utilisée par une instance System.ServiceModel.Description.MetadataExchangeClient peut être l'une des liaisons par défaut de la classe statique MetadataExchangeBindings, une liaison fournie par l'utilisateur ou une liaison chargée à partir d'une configuration de point de terminaison pour le contrat IMetadataExchange. System.ServiceModel.Description.MetadataExchangeClient peut également résoudre des références d'URL HTTP aux métadonnées à l'aide du type HttpWebRequest.
Par défaut, une instance System.ServiceModel.Description.MetadataExchangeClient est attachée à une instance ChannelFactoryBase unique. Vous pouvez modifier ou remplacer l'instance ChannelFactoryBase utilisée par System.ServiceModel.Description.MetadataExchangeClient en substituant la méthode virtuelle GetChannelFactory. De la même façon, vous pouvez modifier ou remplacer l'instance System.Net.HttpWebRequest utilisée par System.ServiceModel.Description.MetadataExchangeClient pour effectuer des requêtes HTTP/GET en substituant la méthode virtuelle MetadataExchangeClient.GetWebRequest.
Vous pouvez récupérer des métadonnées de service à l'aide d'un échange WS-MetadataExchange ou de requêtes HTTP/GET en utilisant l'outil Svcutil.exe et en passant le commutateur /target:metadata et une adresse. Svcutil.exe télécharge les métadonnées à l'adresse spécifiée et enregistre les fichiers sur disque. Svcutil.exe utilise une instance System.ServiceModel.Description.MetadataExchangeClient en interne et charge, à partir du fichier de configuration de l'application, une configuration de point de terminaison MEX dont le nom correspond au schéma de l'adresse passée à Svcutil.exe, s'il en existe une. Sinon, Svcutil.exe utilise par défaut une des liaisons définies par le type de fabrique statique MetadataExchangeBindings.
Importation des métadonnées de service
Dans WCF, l'importation de métadonnées est le processus de génération d'une représentation abstraite d'un service ou de ses composants à partir de ses métadonnées. Par exemple, WCF peut importer des instances ServiceEndpoint, des instances Binding ou des instances ContractDescription à partir d'un document WSDL pour un service. Pour importer des métadonnées de service dans WCF, utilisez une implémentation de la classe abstraite MetadataImporter. Les types qui dérivent de la classe System.ServiceModel.Description.MetadataImporter implémentent la prise en charge de l'importation des formats de métadonnées qui tirent parti de la logique d'importation WS-Policy dans WCF.
Une implémentation System.ServiceModel.Description.MetadataImporter recueille les expressions de stratégie attachées aux métadonnées de service dans un objet PolicyConversionContext. Le System.ServiceModel.Description.MetadataImporter traite ensuite les stratégies dans le cadre de l'importation des métadonnées en appelant les implémentations de l'interface IPolicyImportExtension dans la propriété PolicyImportExtensions.
Vous pouvez ajouter la prise en charge pour importer de nouvelles assertions de stratégie vers un System.ServiceModel.Description.MetadataImporter en ajoutant votre propre implémentation de l'interface IPolicyImportExtension à la collection PolicyImportExtensions sur une instance System.ServiceModel.Description.MetadataImporter. Vous pouvez également enregistrer votre extension de l’importation de la stratégie dans votre fichier de configuration de l’application cliente.
Le type System.ServiceModel.Description.WsdlImporter est l’implémentation de la classe abstraite System.ServiceModel.Description.MetadataImporter incluse dans WCF. Le type System.ServiceModel.Description.WsdlImporter importe des métadonnées WSDL avec les stratégies attachées fournies dans un objet MetadataSet.
Vous pouvez ajouter la prise en charge pour importer des extensions WSDL en implémentant l’interface IWsdlImportExtension et en ajoutant ensuite votre implémentation à la propriété WsdlImportExtensions sur votre instance System.ServiceModel.Description.WsdlImporter. Le System.ServiceModel.Description.WsdlImporter peut également charger des implémentations de l'interface System.ServiceModel.Description.IWsdlImportExtension inscrite dans votre fichier de configuration de l'application cliente.
Liaisons dynamiques
Vous pouvez mettre à jour dynamiquement la liaison que vous utilisez pour créer un canal vers un point de terminaison de service au cas où la liaison pour le point de terminaison change ou si vous souhaitez créer un canal vers un point de terminaison qui utilise le même contrat mais possède une liaison différente. Vous pouvez utiliser la classe statique MetadataResolver pour récupérer et importer les métadonnées au moment de l'exécution pour les points de terminaison de service qui implémentent un contrat spécifique. Vous pouvez utiliser ensuite les objets System.ServiceModel.Description.ServiceEndpoint importés pour créer une fabrique de client ou de canaux au point de terminaison souhaité.