Outil Service Model Metadata Tool (Svcutil.exe)

Article
09/12/2008

L'outil Service Model Metadata Tool est utilisé pour générer un code de modèle de service à partir de documents de métadonnées, ainsi que des documents de métadonnées à partir d'un code de modèle de service.

Notes

L'outil Service Model Metadata Tool se trouve à l'emplacement d'installation du Kit de développement logiciel Windows, généralement C:\Program Files\Microsoft SDKs\Windows\v6.0\Bin

Le tableau suivant résume les différentes fonctionnalités fournies par cet outil et la rubrique correspondante qui décrit leur utilisation.

Tâche	Rubrique
Génère le code à partir des services en cours d'exécution ou de documents de métadonnées statiques.	Generating a WCF Client from Service Metadata
Exporte des documents de métadonnées à partir de code compilé.	How to: Use Svcutil.exe to Export Metadata from Compiled Service Code
Valide le code de service compilé.	How to: Use Svcutil.exe to Validate Compiled Service Code
Télécharge des documents de métadonnées à partir de services en cours d'exécution.	How to: Download Metadata Documents from a Running Service
Génère du code de sérialisation.	How to: Use Svcutil.exe to Generate Serialization Code

Attention :
Svcutil remplace les fichiers existants d'un disque si les noms qui ont été fournis en tant que paramètres sont identiques. Cela peut inclure des fichiers de code, des fichiers de configuration ou de métadonnées. Pour éviter cela, lorsque vous générez du code et des fichiers de configuration, utilisez le commutateur /mergeConfig. De plus, les commutateurs /r et /ct utilisés pour référencer des types sont destinés à la génération de contrats de données. Ces commutateurs ne fonctionnent pas lors de l'utilisation de XmlSerializer.

Svcutil remplace les fichiers existants d'un disque si les noms qui ont été fournis en tant que paramètres sont identiques. Cela peut inclure des fichiers de code, des fichiers de configuration ou de métadonnées. Pour éviter cela, lorsque vous générez du code et des fichiers de configuration, utilisez le commutateur /mergeConfig.

De plus, les commutateurs /r et /ct utilisés pour référencer des types sont destinés à la génération de contrats de données. Ces commutateurs ne fonctionnent pas lors de l'utilisation de XmlSerializer.

Cet outil est soumis à un délai d'attente de 5 minutes lors de la récupération de métadonnées. Ce délai d'attente s'applique uniquement à la récupération des métadonnées sur le réseau. Il ne s'applique pas au traitement de ces métadonnées.

Lorsque vous utilisez Svcutil pour accéder à un document WSDL qui contient une référence à un service d'émission de jeton de sécurité (STS), Svcutil effectue un appel WS-MetadataExchange call au STS. Cependant, le service peut exposer ses documents WSDL à l'aide de WS-MetadataExchange ou de HTTP GET. Par conséquent, si le STS n'a exposé que le document WSDL à l'aide de HTTP GET, un client écrit dans .NET Framework 3.0 échoue. Pour les clients écrits dans .NET Framework 3.5, Svcutil tente d'utiliser WS-MetadataExchange et HTTP GET pour obtenir le STS WSDL.

Utilisations courantes

Le tableau suivant illustre certaines des options fréquemment utilisées pour cet outil.

Option	Description
/directory:<répertoire>	Répertoire à utiliser pour la création des fichiers. Valeur par défaut : le répertoire actif. Forme abrégée : /d
/help	Affiche la syntaxe de commande et les options de l'outil. Forme abrégée : /?
/noLogo	Supprime le message de copyright et de bannière.
/svcutilConfig:<fichier_config>	Spécifie un fichier de configuration personnalisé à utiliser en remplacement du fichier App.config. Peut être utilisé pour enregistrer des extensions system.serviceModel sans modifier le fichier de configuration de l'outil.
/target:<type_sortie>	Spécifie la sortie à générer par l'outil. Les valeurs valides sont code, métadonnées ou xmlSerializer. Forme abrégée : /t

Génération de code

Svcutil.exe peut générer du code pour les contrats de service, les clients et les types de données à partir de documents de métadonnées. Ces documents de métadonnées peuvent se trouver sur un stockage durable, ou encore être récupérés en ligne. La récupération en ligne suit le protocole WS-Metadata Exchange ou le protocole DISCO (pour plus d'informations, consultez la section consacrée au téléchargement de métadonnées).

Pour un service avec un point de terminaison BasicHttpContextbinding, Svcutil.exe génère un BasicHttpBinding avec l'attribut allowCookies affecté à la place de la valeur true. Les cookies sont utilisés pour le contexte sur le serveur. Pour gérer le contexte sur le client lorsque le service utiliser des cookies, vous pouvez modifier manuellement la configuration pour utiliser une liaison de contexte.

Attention :
Svcutil.exe génère le client sur la base du WSDL ou du fichier de stratégie reçu du service. Le nom d'utilisateur principal (UPN) est généré en concaténant le nom d'utilisateur, « @ » et un nom de domaine complet. Toutefois, ce format n'est pas valide pour les utilisateurs Active Directory, et l'UPN généré par l'outil provoque une défaillance dans l'authentification Kerberos et l'affichage du message d'erreur suivant : La tentative d'ouverture de session a échoué. Pour remédier à cela, vous devez corriger manuellement le fichier client généré par cet outil.

Svcutil.exe génère le client sur la base du WSDL ou du fichier de stratégie reçu du service. Le nom d'utilisateur principal (UPN) est généré en concaténant le nom d'utilisateur, « @ » et un nom de domaine complet. Toutefois, ce format n'est pas valide pour les utilisateurs Active Directory, et l'UPN généré par l'outil provoque une défaillance dans l'authentification Kerberos et l'affichage du message d'erreur suivant : La tentative d'ouverture de session a échoué. Pour remédier à cela, vous devez corriger manuellement le fichier client généré par cet outil.

svcutil.exe [/t:code] <metadataDocumentPath>* | <url>* | <epr>

Argument	Description
epr	Chemin d'accès à un fichier XML qui contient une référence de point de terminaison WS-Addressing pour un service qui prend en charge WS-Metadata Exchange. Pour plus d'informations, consultez la section consacrée au téléchargement de métadonnées.
metadataDocumentPath	Chemin d'accès à un document de métadonnées (wsdl ou xsd) qui contient le contrat à importer dans le code (.wsdl, .xsd, .wspolicy ou .wsmex). Svcutil effectue des imports et des opérations d'inclusion lorsque vous spécifiez une URL distante pour les métadonnées. Toutefois, si vous souhaitez traiter des fichiers de métadonnées sur le système de fichiers local, vous devez spécifier tous les fichiers dans cet argument. De cette façon, vous pouvez utiliser Svcutil dans un environnement de génération dans lequel vous ne pouvez pas avoir de dépendances de réseau. Vous pouvez utiliser des caractères génériques (par exemple, * .xsd, * .wsdl) pour cet argument.
url	URL à un point de terminaison de service qui fournit les métadonnées ou à un document de métadonnées hébergé en ligne. Pour plus d'informations sur la façon dont ces documents sont récupérés, consultez la section consacrée au téléchargement de métadonnées.

epr

Chemin d'accès à un fichier XML qui contient une référence de point de terminaison WS-Addressing pour un service qui prend en charge WS-Metadata Exchange. Pour plus d'informations, consultez la section consacrée au téléchargement de métadonnées.

metadataDocumentPath

Chemin d'accès à un document de métadonnées (wsdl ou xsd) qui contient le contrat à importer dans le code (.wsdl, .xsd, .wspolicy ou .wsmex).

Svcutil effectue des imports et des opérations d'inclusion lorsque vous spécifiez une URL distante pour les métadonnées. Toutefois, si vous souhaitez traiter des fichiers de métadonnées sur le système de fichiers local, vous devez spécifier tous les fichiers dans cet argument. De cette façon, vous pouvez utiliser Svcutil dans un environnement de génération dans lequel vous ne pouvez pas avoir de dépendances de réseau. Vous pouvez utiliser des caractères génériques (par exemple, * .xsd, * .wsdl) pour cet argument.

url

URL à un point de terminaison de service qui fournit les métadonnées ou à un document de métadonnées hébergé en ligne. Pour plus d'informations sur la façon dont ces documents sont récupérés, consultez la section consacrée au téléchargement de métadonnées.

Option	Description
/async	Génère à la fois des signatures de méthode synchrones et asynchrones. Valeur par défaut : génération de signatures de méthode synchrones uniquement. Forme abrégée : /a
/collectionType:<type>	Spécifie un nom qualifié complet ou qualifié d'assembly de type à utiliser comme type de données de collection, lorsque du code est généré à partir de schémas. Forme abrégée : /ct
/config:<fichier_config>	Spécifie le nom de fichier du fichier de configuration généré. Valeur par défaut : output.config.
/dataContractOnly	Génère du code pour les types de contrat de données uniquement. Aucun type de contrat de service n'est généré. Pour cette option, vous devez spécifier uniquement des fichiers de métadonnées locaux. Forme abrégée : /dconly
/enableDataBinding	Implémente l'interface INotifyPropertyChanged sur tous les types de contrat de données pour activer la liaison de données. Forme abrégée : /edb
/excludeType:<type>	Spécifie un nom de type qualifié complet ou qualifié d'assembly à exclure des types de contrat référencés. Lors de l'utilisation de ce commutateur avec /r à partir de DLL séparées, le nom complet de la classe XSD est référencé. Forme abrégée : /et
/importXmlTypes	Configure le sérialiseur de contrat de données de façon à importer des types autres que le type de contrat de données en tant que types IXmlSerializable.
/internal	Génère des classes marquées comme internes. Valeur par défaut : génération de classes publiques uniquement. Forme abrégée : /i
/language:<langage>	Spécifie le langage de programmation à utiliser pour la génération de code. Vous devez spécifier un nom de langage enregistré dans le fichier Machine.config, ou le nom qualifié complet d'une classe qui hérite de CodeDomProvider. Valeurs: c#, cs, csharp, vb, visualbasic, c++, cpp Valeur par défaut : csharp Forme abrégée : /l Remarque : Le commutateur prend en charge C++ uniquement pour le fournisseur de code fourni avec Visual Studio 2005 SP1.
/mergeConfig	Fusionne la configuration générée dans un fichier existant au lieu de remplacer le fichier existant.
/messageContract	Génère des types de contrat de message. Forme abrégée : /mc
/namespace:<chaîne, chaîne>	Spécifie un mappage d'un espace de noms WSDL ou XML Schema targetNamespace vers un espace de noms CLR. L'utilisation de '*' pour l'espace de noms targetNamespace mappe tous les espaces de noms targetNamespaces sans mappage explicite à cet espace de noms CLR. Pour vérifier que le nom de contrat du message n'entre pas en collision avec le nom d'opération, vous devez soit qualifier la référence de type avec ::, soit vous assurer que les noms sont uniques. Valeur par défaut : dérivée de l'espace de noms cible du document de schéma pour les contrats de données. L'espace de noms par défaut est utilisé pour tous les autres types générés. Forme abrégée : /n
/noConfig	Ne génère pas de fichiers de configuration.
/noStdLib	Ne référence pas les bibliothèques standard. Valeur par défaut: Mscorlib.dll et System.servicemodel.dll sont référencés.
/out:<fichier>	Spécifie le nom de fichier du code généré. Valeur par défaut: dérivée du nom de définition WSDL, du nom de service WSDL ou de l'espace de noms cible de l'un des schémas. Forme abrégée : /o
/serializable	Génère des classes marquées avec l'attribut Serializable. Forme abrégée : /s
/targetClientVersion	Spécifie la version de .NET Framework ciblée par l'application. Les valeurs valides sont Version30 et Version35. La valeur par défaut est Version30, ce qui signifie que l'outil SvcUtil.exe vise .NET Framework 3.0 par défaut. Forme abrégée : /tcv Version30 : Utilisez `/tcv:Version30` si vous générez du code pour les clients qui utilisent .NET Framework 3.0. Si vous utilisez cette valeur, l'outil SvcUtil.exe génère du code qui référence les fonctionnalités présentes dans .NET Framework 3.0 et dans les versions antérieures. Version35 : Utilisez `/tcv:Version35` si vous générez du code pour les clients qui utilisent .NET Framework 3.5. Si vous utilisez cette valeur, l'outil SvcUtil.exe génère du code qui référence les fonctionnalités présentes dans .NET Framework 3.5 et dans les versions antérieures. Si vous utilisez `/tcv:Version35` avec le commutateur /async, des méthodes asynchrones basées sur des délégués de rappel et sur des événements sont générées. De plus, la prise en charge des DataSets activés par LINQ et DateTimeOffset est activée.
/reference:<chemin_accès>	Référence les types contenus dans l'assembly spécifié. Lorsque vous générez des clients, utilisez cette option pour spécifier des assemblys qui peuvent contenir des types représentant les métadonnées importées. Vous ne pouvez pas spécifier de contrats de message et de types XmlSerializer à l'aide de ce commutateur. Si DateTimeOffset est référencé, ce type est utilisé au lieu de générer un nouveau type. Si l'application est écrite à l'aide de .NET Framework 3.5, SvcUtil.exe référence automatiquement DateTimeOffset. Forme abrégée : /r
/serializer:Auto	Sélectionne automatiquement le sérialiseur. Utilise le sérialiseur de contrat de données. Si cela échoue, le XmlSerializer est utilisé. Forme abrégée : /ser:Auto
/serializer:DataContractSerializer	Génère des types de données qui utilisent le sérialiseur de contrat de données pour la sérialisation et la désérialisation. Forme abrégée : /ser:DataContractSerializer
/serializer:XmlSerializer	Génère des types de données qui utilisent le XmlSerializer pour la sérialisation et la désérialisation. Forme abrégée : /ser:XmlSerializer

Remarque :
Lorsque la liaison de service est l'une des liaisons fournies par le système (consultez System-Provided Bindings), et la propriété ProtectionLevel a la valeur None ou Sign, Svcutil génère un fichier de configuration à l'aide de l'élément <customBinding> au lieu de l'élément fourni par le système attendu. Par exemple, si le service utilise l'élément <wsHttpBinding> avec le ProtectionLevel définissez à Sign, la configuration générée a <customBinding> dans la section de liaisons au lieu de <wsHttpBinding>. Pour plus d'informations sur le niveau de protection, consultez Understanding Protection Level.

Lorsque la liaison de service est l'une des liaisons fournies par le système (consultez System-Provided Bindings), et la propriété ProtectionLevel a la valeur None ou Sign, Svcutil génère un fichier de configuration à l'aide de l'élément <customBinding> au lieu de l'élément fourni par le système attendu. Par exemple, si le service utilise l'élément <wsHttpBinding> avec le ProtectionLevel définissez à Sign, la configuration générée a <customBinding> dans la section de liaisons au lieu de <wsHttpBinding>. Pour plus d'informations sur le niveau de protection, consultez Understanding Protection Level.

Exportation de métadonnées

Svcutil.exe peut exporter des métadonnées pour des services, des contrats et des types de données contenus dans des assemblys compilés. Pour exporter des métadonnées pour un service, vous devez utiliser l'option /serviceName afin de spécifier le service à exporter. Pour exporter tous les types de contrat de données dans un assembly, vous devez utiliser l'option /dataContractOnly. Par défaut, les métadonnées sont exportées pour tous les contrats de service dans les assemblys d'entrée.

svcutil.exe [/t:metadata] [/serviceName:<serviceConfigName>] [/dataContractOnly] <assemblyPath>*

Argument	Description
assemblyPath	Spécifie le chemin d'accès à un assembly qui contient des services, des contrats ou des types de contrat de données à exporter. Des caractères génériques de ligne de la commande standard peuvent être utilisés pour fournir plusieurs fichiers en tant qu'entrée.

Option	Description
/serviceName:<nom_config_service>	Spécifie le nom de configuration d'un service à exporter. Si cette option est utilisée, un assembly exécutable avec un fichier de configuration associé doit être passé en tant qu'entrée. Svcutil.exe recherche tous les fichiers de configuration associés la configuration du service. Si les fichiers de configuration contiennent des types d'extension, les assemblys qui contiennent ces types doivent être dans le GAC ou être explicitement fournis à l'aide de l'option /reference.
/reference:<chemin_accès>	Ajoute l'assembly spécifié au jeu d'assemblys utilisé pour résoudre des références de type. Si vous exportez ou validez un service qui utilise des extensions tierces (Comportements, Liaisons et BindingElements) enregistrées dans la configuration, utilisez cette option pour localiser des assemblys d'extension qui ne figurent pas dans le GAC. Forme abrégée : /r
/dataContractOnly	Fonctionne uniquement sur les types de contrat de données. Les contrats de service ne sont pas traités. Pour cette option, vous devez spécifier uniquement des fichiers de métadonnées locaux. Forme abrégée : /dconly
/excludeType:<type>	Spécifie le nom qualifié complet ou qualifié d'assembly d'un type à exclure de l'exportation. Cette option peut être utilisée lors de l'exportation des métadonnées d'un service (ou d'un ensemble de contrats de services) afin d'exclure certains types de l'opération d'exportation. Cette option ne peut pas être utilisée avec l'option /dconly. Lorsqu'un assembly contient plusieurs services et que chacun d'entre eux utilise des classes séparées tout en portant le même nom XSD, vous devez spécifier le nom du service au lieu du nom de classe XSD pour ce commutateur. Les types XSD ou les types de contrat de données ne sont pas pris en charge. Forme abrégée : /et

Validation de service

La validation peut être utilisée pour détecter des erreurs dans les implémentations de service sans héberger le service. Vous devez utiliser l'option /serviceName pour indiquer le service à valider.

svcutil.exe /validate /serviceName:<serviceConfigName> <assemblyPath>*

Argument	Description
assemblyPath	Spécifie le chemin d'accès à un assembly qui contient des types de service à valider. L'assembly doit posséder un fichier de configuration associé pour pouvoir fournir la configuration du service. Vous pouvez utiliser des caractères génériques de ligne de commande standard pour fournir plusieurs assemblys.

Option	Description
/validate	Valide une implémentation de service spécifiée par l'option /serviceName. Si cette option est utilisée, un assembly exécutable avec un fichier de configuration associé doit être passé en tant qu'entrée. Forme abrégée : /v
/serviceName:<nom_config_service>	Spécifie le nom de configuration d'un service à valider. Svcutil.exe recherche tous les fichiers de configuration associés de tous les assemblys d'entrée pour la configuration du service. Si les fichiers de configuration contiennent des types d'extension, les assemblys qui contiennent ces types doivent être dans le GAC ou être explicitement fournis à l'aide de l'option /reference.
/reference:<chemin_accès>	Ajoute l'assembly spécifié au jeu d'assemblys utilisé pour résoudre des références de type. Si vous exportez ou validez un service qui utilise des extensions tierces (Comportements, Liaisons et BindingElements) enregistrées dans la configuration, utilisez cette option pour localiser des assemblys d'extension qui ne figurent pas dans le GAC. Forme abrégée : /r
/dataContractOnly	Fonctionne uniquement sur les types de contrat de données. Les contrats de service ne sont pas traités. Pour cette option, vous devez spécifier uniquement des fichiers de métadonnées locaux. Forme abrégée : /dconly
/excludeType:<type>	Spécifie le nom qualifié complet ou qualifié d'assembly d'un type à exclure de la validation. Forme abrégée : /et

Téléchargement de métadonnées

Svcutil.exe permet de télécharger des métadonnées à partir de services en cours d'exécution et de les enregistrer dans des fichiers locaux. Pour pouvoir télécharger des métadonnées, vous devez spécifier l'option /t:metadata. Sinon, un code client est généré. Pour les schémas d'URL HTTP et HTTPS, Svcutil.exe essaie de récupérer les métadonnées à l'aide de WS-Metadata Exchange et DISCO. Pour tous les autres schémas d'URL, Svcutil.exe utilise uniquement WS-MetadataExchange.

Svcutil publie les requêtes de métadonnées suivantes tout en effectuant simultanément une récupération de métadonnées.

Requête MEX (WS-Transfer) à l'adresse fournie
Requête MEX à l'adresse fournie avec /mex ajouté
Requête DISCO (à l'aide du DiscoveryClientProtocol d'ASMX) à l'adresse fournie.

Par défaut, Svcutil.exe utilise les liaisons définies dans la classe MetadataExchangeBindings pour effectuer des requêtes MEX. Pour configurer la liaison utilisée pour WS-Metadata Exchange, vous devez définir un point de terminaison client dans la configuration qui utilise le contrat IMetadataExchange. Cela peut être défini soit dans le fichier de configuration de Svcutil.exe, soit dans un autre fichier de configuration spécifié à l'aide de l'option /svcutilConfig.

svcutil.exe /t:metadata <url>* | <epr>

Argument	Description
url	URL d'accès à un point de terminaison de service qui fournit les métadonnées ou à un document de métadonnées hébergé en ligne.
epr	Chemin d'accès à un fichier XML qui contient une référence de point de terminaison WS-Addressing pour un service qui prend en charge WS-Metadata Exchange.

Génération de type XmlSerializer

Les applications clientes et de services qui utilisent des types de données sérialisables à l'aide de XmlSerializer génèrent et compilent le code de sérialisation de ces types de données lors de l'exécution, ce qui peut provoquer des performances de démarrage lentes.

Remarque :
Le code de sérialisation prégénéré est réservé aux applications clientes, pas aux services.

Svcutil.exe peut améliorer les performances de démarrage de ces applications en générant le code de sérialisation C# nécessaire à partir des assemblys compilés pour l'application. Pour plus d'informations, consultez How to: Improve the Startup Time of WCF Client Applications using the XmlSerializer.

Remarque :
Svcutil.exe génère uniquement le code des types utilisés par les contrats de service figurant dans les assemblys d'entrée.

svcutil.exe /t:xmlSerializer <assemblyPath>*

Argument	Description
assemblyPath	Spécifie le chemin d'accès à un assembly qui contient des types de contrat de service. Des types de sérialisation sont générés pour tous les types Xml sérialisables de chaque contrat.

Option	Description
/reference:<chemin_accès>	Ajoute l'assembly spécifié au jeu d'assemblys utilisé pour résoudre des références de type. Forme abrégée : /r
/excludeType:<type>	Spécifie le nom qualifié complet ou qualifié d'assembly d'un type à exclure de l'exportation ou de la validation. Forme abrégée : /et
/out:<fichier>	Spécifie le nom de fichier du code généré. Cette option est ignorée lorsque plusieurs assemblys sont passés à l'outil en tant qu'entrée. Valeur par défaut : dérivée du nom de l'assembly. Forme abrégée : /o
/UseSerializerForFaults	Spécifie que XmlSerializer doit être utilisé pour lire et écrire les erreurs, au lieu du DataContractSerializer par défaut.

Exemples

La commande suivante génère un code client à partir d'un service en cours d'exécution ou de documents de métadonnées en ligne.

svcutil http://service/metadataEndpoint

La commande suivante génère un code client à partir de documents de métadonnées locaux.

svcutil *.wsdl *.xsd /language:C#

La commande suivante génère des types de contrat de données en Visual Basic à partir de documents de schémas locaux.

svcutil /dconly *.xsd /language:VB

La commande suivante télécharge des documents de métadonnées à partir de services en cours d'exécution.

svcutil /t:metadata http://service/metadataEndpoint

La commande suivante génère des documents de métadonnées pour les contrats de service et les types associés d'un assembly.

svcutil myAssembly.dll

La commande suivante génère des documents de métadonnées pour un service, ainsi que tous les contrats de service et types de données associés au sein d'un assembly.

svcutil myServiceHost.exe /serviceName:myServiceName

La commande suivante génère des documents de métadonnées pour les types de données présents dans un assembly.

svcutil myServiceHost.exe /dconly

La commande suivante vérifie l'hébergement de services.

svcutil /validate /serviceName:myServiceName myServiceHost.exe

La commande suivante génère des types de sérialisation pour les types XmlSerializer utilisés par les contrats de service de l'assembly.

svcutil /t:xmlserializer myContractLibrary.exe

Problèmes de sécurité

Vous devez utiliser la liste de contrôle d'accès appropriée pour protéger le dossier d'installation de Svcutil.exe, Svcutil.config, ainsi que les fichiers vers lesquels pointe /svcutilConfig. Cela peut éviter l'enregistrement et l'exécution d'extensions malveillantes.

De plus, minimiser le risque que la sécurité soit compromise, vous ne devez pas ajouter d'extensions non fiables au système, ni avoir recours à des fournisseurs de code non fiables avec Svcutil.exe.

Enfin, vous ne devez pas utiliser l'outil dans la couche intermédiaire de votre application, car cela pourrait provoquer un déni de service pour le processus en cours.

Partager via