ServiceModel Metadata Utility-Tool (Svcutil.exe)
Das ServiceModel Metadata Utility Tool wird zum Generieren von Service Model-Code aus Metadatendokumenten und zum Generieren von Metadatendokumenten aus Service Model-Code verwendet.
Hinweise
Das ServiceModel Metadata Utility Tool befindet sich unter dem Windows SDK-Installationspfad: C:\Programme\Microsoft SDKs\Windows\v6.0\Bin
In der folgenden Tabelle sind die verschiedenen Funktionen dieses Tools aufgeführt sowie die Themen, in denen die entsprechenden Vorgehensweisen beschrieben werden.
| Aufgabe | Thema |
|---|---|
Generiert Code von ausführenden Diensten oder statischen Metadatendokumenten. |
|
Exportiert Metadatendokumente aus kompiliertem Code. |
How to: Use Svcutil.exe to Export Metadata from Compiled Service Code |
Überprüft kompilierten Dienstcode. |
|
Lädt Metadatendokumente aus Diensten herunter, die zurzeit ausgeführt werden. |
|
Generiert Serialisierungscode. |
Warnung
Svcutil überschreibt vorhandene Dateien auf einem Datenträger, wenn die als Parameter angegebenen Namen identisch sind. Dazu zählen Codedateien, Konfigurationsdateien oder Metadatendateien. Um dies beim Generieren von Code- und Konfigurationsdateien zu vermeiden, verwenden Sie den /mergeConfig-Schalter.
Der /r-Schalter und der /ct -Schalter für Verweistypen dienen außerdem zum Generieren von Datenverträgen. Diese Schalter funktionieren nicht, wenn Sie XmlSerializer verwenden.Für das Tool gilt ein 5-Minuten-Timeout beim Abrufen von Metadaten. Dieses Timeout gilt nur beim Abrufen von Metadaten über das Netzwerk. Es gilt nicht für die Verarbeitung dieser Metadaten.
Wenn Sie mit Svcutil auf ein WSDL-Dokument zugreifen, das einen Verweis auf einen Sicherheitstokendienst (STS) enthält, führt Svcutil einen WS-MetadataExchange-Aufruf zu STS aus. Der Dienst kann jedoch seine WSDL-Dokumente entweder mithilfe von WS-MetadataExchange oder mithilfe von HTTP GET verfügbar machen. Hat der STS das WSDL-Dokument nur mithilfe von HTTP GET verfügbar gemacht, schlägt daher ein in .NET Framework 3.0 geschriebener Client fehl. Für in .NET Framework 3.5 geschriebene Clients versucht Svcutil, den STS WSDL sowohl mithilfe von WS-MetadataExchange als auch mit HTTP GET abzurufen.
Allgemeine Verwendungen
In der folgenden Tabelle werden einige der häufig verwendeten Optionen für dieses Tool aufgeführt.
| Option | Beschreibung |
|---|---|
/directory:<directory> |
Das Verzeichnis, in dem die Dateien erstellt werden sollen. Standard: Das aktuelle Verzeichnis. Kurzform: /d. |
/help |
Zeigt die Befehlssyntax und Optionen für das Tool an. Kurzform: /?. |
/noLogo |
Die Copyright- und die Bannermeldung werden unterdrückt. |
/svcutilConfig:<configFile> |
Gibt eine benutzerdefinierte Konfigurationsdatei an, die statt der Datei App.config verwendet werden soll. Dies kann verwendet werden, um system.serviceModel-Erweiterungen zu registrieren, ohne die Konfigurationsdatei des Tools zu ändern. |
/target:<output type> |
Gibt die Ausgabe an, die vom Tool generiert werden soll. Gültige Werte sind Code, Metadaten oder xmlSerializer. Kurzform: /t. |
Codeerzeugung
Svcutil.exe kann Code für Dienstverträge, Clients und Datentypen aus Metadatendokumenten generieren. Diese Metadatendokumente können sich in einem permanenten Speicher befinden oder online abgerufen werden. Der Onlineabruf erfolgt gemäß dem WS-Metadata Exchange-Protokoll oder DISCO-Protokoll (weitere Informationen finden Sie im Abschnitt Metadatendownload).
Für einen Dienst mit einem BasicHttpContextbinding-Endpunkt generiert Svcutil.exe stattdessen eine BasicHttpBinding, deren allowCookies-Attribut auf true festgelegt ist. Die Cookies werden auf dem Server für den Kontext verwendet. Möchten Sie den Kontext auf dem Client verwalten, wenn der Dienst Cookies verwendet, so können Sie die Konfiguration manuell für die Verwendung einer Kontextbindung ändern.
Warnung
Svcutil.exe generiert den Client auf der Basis der vom Dienst empfangenen WSDL- oder Richtliniendatei. Der Benutzerprinzipalname (UPN) wird generiert durch die Aneinanderreihung von Benutzername, "@" und vollqualifiziertem Domänennamen (FQDN). Für in Active Directory registrierte Benutzer ist dieses Format jedoch nicht gültig, und der vom Tool generierte UPN verursacht einen Fehler bei der Kerberos-Authentifizierung mit der Fehlermeldung "Der Anmeldeversuch ist fehlgeschlagen". Um dieses Problem zu beheben, sollten Sie die von diesem Tool generierte Clientdatei manuell reparieren.
svcutil.exe [/t:code] <metadataDocumentPath>* | <url>* | <epr>
| Argument | Beschreibung |
|---|---|
epr |
Der Pfad zu einer XML-Datei, die einen WS-Addressing-EndpointReference für einen Dienstendpunkt enthält, der WS-Metadata Exchange unterstützt. Weitere Informationen finden Sie im Abschnitt Metadatendownload. |
metadataDocumentPath |
Der Pfad zu einem Metadatendokument (wsdl oder xsd), der den in den Code zu importierenden Vertrag enthält (.wsdl, .xsd, .wspolicy oder .wsmex). Svcutil folgt Importen und bezieht eine Remote-URL für Metadaten ein, sofern diese angegeben wird. Wenn Metadatendateien im lokalen Dateisystem verarbeitet werden sollen, müssen Sie alle Dateien in diesem Argument angeben. Auf diese Art können Sie Svcutil in einer Buildumgebung verwenden, in der keine Netzwerkabhängigkeiten möglich sind. Sie können Platzhalter (z. B. *.xsd, *.wsdl) für dieses Argument verwenden. |
url |
Die URL zu einem Dienstendpunkt, der Metadaten bereitstellt, oder zu einem Metadatendokument, das online gehostet wird. Weitere Informationen dazu, wie diese Dokumente abgerufen werden, finden Sie im Abschnitt Metadatendownload. |
| Option | Beschreibung |
|---|---|
/async |
Generiert sowohl synchrone als auch asynchrone Methodensignaturen. Standard: Es werden nur synchrone Methodensignaturen generiert. Kurzform: /a. |
/collectionType:<type> |
Gibt beim Generieren von Code aus Schemas einen vollqualifizierten oder assemblyqualifizierten Namen des Typs an, der als Auflistungsdatentyp verwendet werden soll. Kurzform: /ct. |
/config:<configFile> |
Gibt den Dateinamen für die generierte Konfigurationsdatei an. Standard: output.config. |
/dataContractOnly |
Generiert nur Code für Datenvertragstypen. Dienstvertragstypen werden nicht generiert. Sie sollten nur lokale Metadatendateien für diese Option angeben. Kurzform: /dconly. |
/enableDataBinding |
Implementiert die INotifyPropertyChanged-Schnittstelle für alle Datenvertragstypen, um die Datenbindung zu ermöglichen. Kurzform: /edb. |
/excludeType:<type> |
Gibt einen vollqualifizierten oder assemblyqualifizierten Namen an, der aus den verwiesenen Vertragstypen ausgeschlossen werden soll. Beim Verwenden dieses Schalters mit /r aus separaten DLLs wird auf den vollständigen Namen der XSD-Klasse verwiesen. Kurzform: /et. |
/importXmlTypes |
Konfiguriert den Datenvertragsserialisierer, um Nicht-Datenvertragstypen als IXmlSerializable-Typen zu importieren. |
/internal |
Generiert Klassen, die als intern markiert sind. Standard: Generiert nur öffentliche Klassen. Kurzform: /i. |
/language:<language> |
Gibt die Programmiersprache an, die zur Codegenerierung verwendet werden soll. Sie können entweder einen in der Datei Machine.config registrierten Sprachnamen oder den vollqualifizierten Namen einer Klasse angeben, der von CodeDomProvider erbt. Werte: c#, cs, csharp, vb, visualbasic, c++, cpp Standard: csharp Kurzform: /l. Tipp Der Schalter unterstützt nur C++ für den Codeanbieter, der mit Visual Studio 2005 SP1 geliefert wird. |
/mergeConfig |
Fügt die generierte Konfiguration in eine vorhandene Datei ein, statt die vorhandene Datei zu überschreiben. |
/messageContract |
Generiert Nachrichtenvertragstypen. Kurzform: /mc. |
/namespace:<string,string> |
Gibt eine Zuordnung von einem WSDL- oder XML-Schema-targetNamespace zu einem CLR-Namespace an. Durch die Verwendung von '*' für den targetNamespace werden alle targetNamespaces ohne eine explizite Zuordnung diesem CLR-Namespace zugeordnet. Um zu gewährleisten, dass der Nachrichtenvertragsname nicht mit dem Vorgangsnamen in Konflikt steht, sollten Sie den Typverweis entweder mit :: angeben oder sicherstellen, dass die Namen einmalig sind. Standard: Wird vom Zielnamespace des Schemadokuments für Datenverträge abgeleitet. Der Standardnamespace wird für alle anderen generierten Typen verwendet. Kurzform: /n. |
/noConfig |
Es werden keine Konfigurationsdateien generiert. |
/noStdLib |
Verweist nicht auf Standardbibliotheken. Standard: Es wird auf Mscorlib.dll und System.servicemodel.dll verwiesen. |
/out:<file> |
Gibt den Dateinamen für den generierten Code an. Standard: Wird vom WSDL-Definitionsnamen, WSDL-Dienstnamen oder Zielnamespace eines der Schemas abgeleitet. Kurzform: /o. |
/serializable |
Generiert mit dem Serializable-Attribut markierte Klassen. Kurzform: /s. |
/targetClientVersion |
Geben Sie an, auf welche Version von .NET Framework die Anwendung abzielt. Gültige Werte sind Version30 und Version35. Der Standardwert ist Version30, was bedeutet, dass das Tool SvcUtil.exe standardmäßig auf .NET Framework 3.0 abzielt. Kurzform: /tcv. Version30: Verwenden Sie Version35: Verwenden Sie |
/reference:<file path> |
Verweist auf Typen in der angegebenen Assembly. Beim Generieren von Clients können Sie diese Option verwenden, um Assemblys anzugeben, die unter Umständen die Typen mit den zu importierenden Metadaten enthalten. Sie können mit diesem Schalter keine Nachrichtenverträge oder XmlSerializer-Typen angeben. Wenn auf DateTimeOffset verwiesen wird, wird dieser Typ verwendet, statt einen neuen Typ zu generieren. Wenn die Anwendung mit .NET Framework 3.5 geschrieben wird, verweist SvcUtil.exe automatisch auf DateTimeOffset. Kurzform: /r. |
/serializer:Auto |
Wählt das Serialisierungsprogramm automatisch aus. Dabei wird der Datenvertragsserialisierer verwendet. Wenn dieser Versuch fehlschlägt, wird XmlSerializer verwendet. Kurzform: /ser:Auto. |
/serializer:DataContractSerializer |
Generiert Datentypen, die den Datenvertragsserialisierer für die Serialisierung und die Deserialisierung verwenden. Kurzform: /ser:DataContractSerializer. |
/serializer:XmlSerializer |
Generiert Datentypen, die XmlSerializer für die Serialisierung und die Deserialisierung verwenden. Kurzform: /ser:XmlSerializer. |
Tipp
Wenn es sich bei der Dienstbindung um eine vom System bereitgestellte Bindung handelt (siehe System-Provided Bindings) und die ProtectionLevel-Eigenschaft entweder auf None oder auf Sign festgelegt ist, generiert Svcutil eine Konfigurationsdatei mithilfe des <customBinding>-Elements anstatt des erwarteten vom System bereitgestellten Elements. Wenn der Dienst beispielsweise das <wsHttpBinding>-Element verwendet, für das ProtectionLevel auf Sign festgelegt ist, wird im Bindungsabschnitt der generierten Konfiguration <customBinding> anstatt <wsHttpBinding> angezeigt. Weitere Informationen zum Schutzgrad finden Sie unter Understanding Protection Level.
Metadatenexport
Svcutil.exe kann Metadaten für Dienste, Verträge und Datentypen in kompilierten Assemblys exportieren. Um Metadaten für einen Dienst zu exportieren, müssen Sie den zu exportierenden Dienst mit der /serviceName-Option angeben. Um alle Datenvertragstypen innerhalb einer Assembly zu exportieren, verwenden Sie die /dataContractOnly-Option. Standardmäßig werden die Metadaten für alle Dienstverträge in den Eingabeassemblys exportiert.
svcutil.exe [/t:metadata] [/serviceName:<serviceConfigName>] [/dataContractOnly] <assemblyPath>*
| Argument | Beschreibung |
|---|---|
assemblyPath |
Gibt den Pfad zu einer Assembly an, die zu exportierende Dienste, Verträge oder Datenvertragstypen enthält. Sie können standardmäßige Befehlszeilenplatzhalter verwenden, um mehrere Dateien anzugeben. |
| Option | Beschreibung |
|---|---|
/serviceName:<serviceConfigName> |
Gibt den Konfigurationsnamen eines Diensts an, der exportiert werden soll. Bei Verwendung dieser Option muss eine ausführbare Assembly mit einer zugeordneten Konfigurationsdatei als Eingabe übergeben werden. Svcutil.exe durchsucht alle zugeordneten Konfigurationsdateien für die Dienstkonfiguration. Wenn die Konfigurationsdateien Erweiterungstypen enthalten, müssen die Assemblys, die diese Typen enthalten, sich entweder im GAC befinden oder ausdrücklich durch die /reference-Option angegeben werden. |
/reference:<file path> |
Fügt die angegebene Assembly dem Satz von Assemblys hinzu, der zum Auflösen von Typverweisen verwendet wird. Wenn Sie einen Dienst exportieren oder überprüfen, der in der Konfiguration registrierte Drittanbietererweiterungen verwendet (Verhalten, Bindungen und Bindungselemente), können Sie diese Option zum Suchen von Erweiterungsassemblys einsetzen, die sich nicht im GAC befinden. Kurzform: /r. |
/dataContractOnly |
Funktioniert nur bei Datenvertragstypen. Dienstverträge werden nicht verarbeitet. Sie sollten nur lokale Metadatendateien für diese Option angeben. Kurzform: /dconly. |
/excludeType:<type> |
Gibt einen vollqualifizierten oder assemblyqualifizierten Namen eines Typs an, der aus dem Export ausgeschlossen werden soll. Diese Option kann beim Exportieren von Metadaten für einen Dienst oder einen Satz von Dienstverträgen verwendet werden, um Typen aus dem Export auszuschließen. Diese Option kann nicht zusammen mit der /dconly-Option verwendet werden. Wenn Sie eine einzelne Assembly mit mehreren Diensten vorliegen haben und jede Assembly separate Klassen mit dem gleichen XSD-Namen verwendet, sollten Sie den Dienstnamen anstatt des XSD-Klassennamens für diesen Schalter angeben. XSD- oder Datenvertragstypen werden nicht unterstützt. Kurzform: /et. |
Dienstüberprüfung
Die Überprüfung kann nicht zum Erkennen von Fehlern in Dienstimplementierungen verwendet werden, ohne den Dienst zu hosten. Sie müssen die /serviceName-Option verwenden, um den zu überprüfenden Dienst anzugeben.
svcutil.exe /validate /serviceName:<serviceConfigName> <assemblyPath>*
| Argument | Beschreibung |
|---|---|
assemblyPath |
Gibt den Pfad zu einer Assembly an, die zu überprüfende Diensttypen enthält. Die Assembly muss über eine zugeordnete Konfigurationsdatei verfügen, um die Dienstkonfiguration bereitzustellen. Sie können standardmäßige Befehlszeilenplatzhalter verwenden, um mehrere Assemblys anzugeben. |
| Option | Beschreibung |
|---|---|
/validate |
Überprüft eine durch die /serviceName-Option angegebene Dienstimplementierung. Bei Verwendung dieser Option muss eine ausführbare Assembly mit einer zugeordneten Konfigurationsdatei als Eingabe übergeben werden. Kurzform: /v. |
/serviceName:<serviceConfigName> |
Gibt den Konfigurationsnamen eines zu überprüfenden Diensts an. Svcutil.exe durchsucht alle zugeordneten Konfigurationsdateien aller Eingabeassemblys für die Dienstkonfiguration. Wenn die Konfigurationsdateien Erweiterungstypen enthalten, müssen die Assemblys, die diese Typen enthalten, sich entweder im GAC befinden oder ausdrücklich durch die /reference-Option angegeben werden. |
/reference:<file path> |
Fügt die angegebene Assembly dem Satz von Assemblys hinzu, der zum Auflösen von Typverweisen verwendet wird. Wenn Sie einen Dienst exportieren oder überprüfen, der in der Konfiguration registrierte Drittanbietererweiterungen verwendet (Verhalten, Bindungen und Bindungselemente), können Sie diese Option zum Suchen von Erweiterungsassemblys einsetzen, die sich nicht im GAC befinden. Kurzform: /r. |
/dataContractOnly |
Funktioniert nur bei Datenvertragstypen. Dienstverträge werden nicht verarbeitet. Sie sollten nur lokale Metadatendateien für diese Option angeben. Kurzform: /dconly. |
/excludeType:<type> |
Gibt einen vollqualifizierten oder assemblyqualifizierten Namen eines Typs an, der aus der Überprüfung ausgeschlossen werden soll. Kurzform: /et. |
Metadatendownload
Svcutil.exe kann verwendet werden, um Metadaten aus ausführenden Diensten herunterzuladen und die Metadaten in lokalen Dateien zu speichern. Um Metadaten herunterzuladen, müssen Sie die /t:metadata-Option angeben. Andernfalls wird Clientcode generiert. Bei HTTP- und HTTPS-URL-Schemas versucht Svcutil.exe, Metadaten mit WS-Metadata Exchange und DISCO abzurufen. Bei allen anderen URL-Schemas verwendet Svcutil.exe nur WS-Metadata Exchange.
Svcutil gibt die folgenden Metadatenanforderungen gleichzeitig aus, um Metadaten abzurufen.
- MEX (WS-Transfer)-Anforderung an die angegebene Adresse
- MEX-Anforderung an die angegebene Adresse mit angefügtem /mex
- DISCO-Anforderung (mit DiscoveryClientProtocol von ASMX) an die angegebene Adresse
Standardmäßig verwendet Svcutil.exe die in der MetadataExchangeBindings-Klasse definierten Bindungen, um MEX-Anforderungen zu stellen. Um die für WS-Metadata Exchange verwendete Bindung zu konfigurieren, müssen Sie einen Clientendpunkt in der Konfiguration definieren, der den IMetadataExchange-Vertrag verwendet. Dies kann entweder in der Konfigurationsdatei von Svcutil.exe oder in einer anderen Konfigurationsdatei, die mit der /svcutilConfig-Option angegeben wird, definiert werden.
svcutil.exe /t:metadata <url>* | <epr>
| Argument | Beschreibung |
|---|---|
url |
Die URL zu einem Dienstendpunkt, der Metadaten bereitstellt, oder zu einem Metadatendokument, das online gehostet wird. |
epr |
Der Pfad zu einer XML-Datei, die einen WS-Addressing-EndpointReference für einen Dienstendpunkt enthält, der WS-Metadata Exchange unterstützt. |
XmlSerializer-Typgenerierung
Dienste und Clientanwendungen, die Datentypen verwenden, die mit dem XmlSerializer serialisiert werden können, generieren und kompilieren für diese Datentypen während der Laufzeit Code, was zu einem verlangsamten Start führen kann.
Tipp
Vorab generierter Serialisierungscode kann nur in Clientanwendungen verwendet werden und nicht in Diensten.
Svcutil.exe kann den erforderlichen C#-Serialisierungscode aus den kompilierten Assemblys für die Anwendung generieren, um damit die Startleistung für diese Anwendungen zu verbessern. Weitere Informationen finden Sie unter How to: Improve the Startup Time of WCF Client Applications using the XmlSerializer.
Tipp
Svcutil.exe generiert nur Code für Typen, die von Dienstverträgen, die in der Eingabeassemblys gefunden werden, verwendet werden.
svcutil.exe /t:xmlSerializer <assemblyPath>*
| Argument | Beschreibung |
|---|---|
assemblyPath |
Gibt den Pfad zu einer Assembly an, die Dienstvertragstypen enthält. Serialisierungstypen werden für alle serialisierbaren XML-Typen in jedem Vertrag generiert. |
| Option | Beschreibung |
|---|---|
/reference:<file path> |
Fügt die angegebene Assembly dem Satz von Assemblys hinzu, der zum Auflösen von Typverweisen verwendet wird. Kurzform: /r. |
/excludeType:<type> |
Gibt einen vollqualifizierten oder assemblyqualifizierten Namen eines Typs an, der aus dem Export oder der Überprüfung ausgeschlossen werden soll. Kurzform: /et. |
/out:<file> |
Gibt den Dateinamen für den generierten Code an. Diese Option wird ignoriert, wenn mehrere Assemblys als Eingabe an das Tool übergeben werden. Standard: Wird vom Assemblynamen abgeleitet. Kurzform: /o. |
/UseSerializerForFaults |
Gibt an, dass der XmlSerializer für Lektüre und das Schreiben von Fehlern, statt des Standard-DataContractSerializer, verwendet werden soll. |
Beispiele
Der folgende Befehl generiert Clientcode von einem ausgeführten Dienst oder Onlinemetadatendokumenten.
svcutil http://service/metadataEndpoint
Der folgende Befehl generiert Clientcode aus lokalen Metadatendokumenten.
svcutil *.wsdl *.xsd /language:C#
Der folgende Befehl generiert Datenvertragstypen in Visual Basic aus lokalen Schemadokumenten.
svcutil /dconly *.xsd /language:VB
Der folgende Befehl lädt Metadatendokumente aus Diensten herunter, die zurzeit ausgeführt werden.
svcutil /t:metadata http://service/metadataEndpoint
Der folgende Befehl generiert Metadatendokumente für Dienstverträge und zugeordnete Typen in einer Assembly.
svcutil myAssembly.dll
Der folgende Befehl generiert Metadatendokumente für einen Dienst und alle zugeordneten Dienstvertragstypen und Datentypen in einer Assembly.
svcutil myServiceHost.exe /serviceName:myServiceName
Der folgende Befehl generiert Metadatendokumente für Datentypen in einer Assembly.
svcutil myServiceHost.exe /dconly
Der folgende Befehl überprüft Diensthosting.
svcutil /validate /serviceName:myServiceName myServiceHost.exe
Der folgende Befehl generiert Serialisierungstypen für XmlSerializer-Typen, die von Dienstverträgen in der Assembly verwendet werden.
svcutil /t:xmlserializer myContractLibrary.exe
Sicherheitsaspekte
Sie sollten die entsprechende Zugriffssteuerungsliste verwenden, um den Installationsordner von Svcutil.exe, Svcutil.config und Dateien, auf die /svcutilConfig verweist, zu schützen. Dies kann verhindern, dass bösartige Erweiterungen registriert und ausgeführt werden.
Um außerdem weitere Sicherheitsgefahren auszuschließen, sollten Sie dem System nur vertrauenswürdige Erweiterungen hinzufügen und nur vertrauenswürdige Codeanbieter mit Svcutil.exe verwenden.
Und schließlich sollten Sie das Tool nicht in der mittleren Ebene Ihrer Anwendung einsetzen, da dies einen Denial-of-Service beim aktuellen Vorgang zur Folge haben kann.
Siehe auch
Referenz
DataContractAttribute
DataMemberAttribute
Weitere Ressourcen
How To: Create a Windows Communication Foundation Client Class