Verktyg för ServiceModel-metadataverktyg (Svcutil.exe)
Verktyget ServiceModel Metadata Utility används för att generera tjänstmodellkod från metadatadokument och metadatadokument från tjänstmodellkod.
SvcUtil.exe
Verktyget servicemodelmetadata finns på installationsplatsen för Windows SDK, särskilt %ProgramFiles%\Microsoft SDKs\Windows\v6.0\Bin.
Funktioner
I följande tabell sammanfattas de olika funktioner som tillhandahålls av det här verktyget och motsvarande avsnitt som beskriver hur det används:
| Uppgift | Område |
|---|---|
| Genererar kod från tjänster som körs eller statiska metadatadokument. | Generera en WCF-klient från tjänstmetadata |
| Exporterar metadatadokument från kompilerad kod. | Anvisningar: Använd Svcutil.exe för att exportera metadata från kompilerad tjänstkod |
| Validerar kompilerad tjänstkod. | Anvisningar: Använd Svcutil.exe för att verifiera kompilerad tjänstkod |
| Laddar ned metadatadokument från tjänster som körs. | Gör så här: Använd Svcutil.exe för att ladda ned metadatadokument |
| Genererar serialiseringskod. | Gör så här: Förbättra starttiden för WCF-klientprogram med hjälp av XmlSerializer |
Varning
Svcutil skriver över befintliga filer på en disk om namnen som anges som parametrar är identiska. Detta kan omfatta kodfiler, konfigurations- eller metadatafiler. Använd växeln för att undvika detta när du genererar kod- och konfigurationsfiler /mergeConfig .
Dessutom /r används switcharna och /ct för referenstyper för att generera datakontrakt. Dessa växlar fungerar inte när du använder XmlSerializer.
Timeout
Verktyget har en tidsgräns på fem minuter när metadata hämtas. Den här tidsgränsen gäller endast för att hämta metadata över nätverket. Den gäller inte för någon bearbetning av dessa metadata.
Flera mål
Verktyget stöder inte flera mål. Om du vill generera en .NET Framework 4-artefakt från svcutil.exe använder du svcutil.exe från .NET Framework 4 SDK. Om du vill generera en .NET Framework 3.5-artefakt använder du den körbara filen från .NET Framework 3.5 SDK.
Åtkomst till WSDL-dokument
När du använder Svcutil för att komma åt ett WSDL-dokument som har en referens till en säkerhetstokentjänst (STS), gör Svcutil ett WS-MetadataExchange-anrop till STS. Tjänsten kan dock exponera sina WSDL-dokument med WS-MetadataExchange eller HTTP GET. Om STS endast har exponerat WSDL-dokumentet med HTTP GET misslyckas därför en klient som skrivits i WinFX. För klienter som skrivits i .NET Framework 3.5 försöker Svcutil använda både WS-MetadataExchange och HTTP GET för att hämta STS WSDL.
Använda SvcUtil.exe
Vanliga användningar
I följande tabell visas några vanliga alternativ för det här verktyget:
| Alternativ | Description |
|---|---|
| /directory:<directory> | Katalog för att skapa filer i. Standard: Den aktuella katalogen. Kort formulär: /d |
| /help | Visar kommandosyntaxen och alternativen för verktyget. Kort formulär: /? |
| /noLogo | Undertryck upphovsrätten och banderollmeddelandet. |
| /svcutilConfig:<configFile> | Anger en anpassad konfigurationsfil som ska användas i stället för App.config-filen. Detta kan användas för att registrera system.serviceModel-tillägg utan att ändra verktygets konfigurationsfil. |
| /target:<output type> | Anger de utdata som ska genereras av verktyget. Giltiga värden är kod, metadata eller xmlSerializer. Kort formulär: /t |
Kodgenerering
Svcutil.exe kan generera kod för tjänstkontrakt, klienter och datatyper från metadatadokument. Dessa metadatadokument kan finnas på en varaktig lagringsplats eller hämtas online. Onlinehämtning följer antingen WS-Metadata Exchange-protokollet eller DISCO-protokollet (mer information finns i avsnittet Hämta metadata).
Du kan använda verktyget SvcUtil.exe för att generera tjänst- och datakontrakt baserat på ett fördefinierat WSDL-dokument. Använd växeln /serviceContract och ange en URL eller filplats där WSDL-dokumentet kan laddas ned eller hittas. Detta genererar de tjänst- och datakontrakt som definieras i WSDL-dokumentet som sedan kan användas för att implementera en klagomålstjänst. Mer information finns i Så här hämtar du metadata och implementerar en kompatibel tjänst.
För en tjänst med en BasicHttpContextBinding-slutpunkt genererar Svcutil.exe en BasicHttpBinding med allowCookies attributet inställt på true i stället. Cookies används för kontext på servern. Om du vill hantera kontexten på klienten när tjänsten använder cookies kan du manuellt ändra konfigurationen så att den använder en kontextbindning.
Varning
Svcutil.exe genererar klienten baserat på WSDL- eller principfilen som tas emot från tjänsten. Användarens huvudnamn (UPN) genereras genom sammanlänkning av användarnamn, "@" och ett fullständigt domännamn (FQDN). Men för användare som har registrerat sig i Active Directory är det här formatet inte giltigt och UPN som genereras av verktyget orsakar ett fel i Kerberos-autentiseringen med felmeddelandet "Inloggningsförsöket misslyckades". För att lösa det här problemet bör du manuellt åtgärda klientfilen som genereras av det här verktyget.
svcutil.exe [/t:code] <metadataDocumentPath>* | <url>* | <epr>
| Argument | beskrivning |
|---|---|
epr |
Sökvägen till en XML-fil som innehåller en WS-adresseringsslutpunktReferens för en tjänstslutpunkt som stöder WS-Metadata Exchange. Mer information finns i avsnittet Hämta metadata. |
metadataDocumentPath |
Sökvägen till ett metadatadokument (wsdl eller xsd) som innehåller kontraktet som ska importeras till kod (.wsdl, .xsd, .wspolicy eller .wsmex). Svcutil följer importen och inkluderar när du anger en fjärr-URL för metadata. Men om du vill bearbeta metadatafiler i det lokala filsystemet måste du ange alla filer i det här argumentet. På så sätt kan du använda Svcutil i en byggmiljö där du inte kan ha nätverksberoenden. Du kan använda jokertecken (*.xsd, *.wsdl) för det här argumentet. |
url |
URL:en till en tjänstslutpunkt som tillhandahåller metadata eller till ett metadatadokument som finns online. Mer information om hur dessa dokument hämtas finns i avsnittet Hämta metadata. |
| Alternativ | Description |
|---|---|
| /Asynkrona | Genererar både synkrona och asynkrona metodsignaturer. Standard: generera endast synkrona metodsignaturer. Kort formulär: /a |
| /collectionType:<type> | Anger listsamlingstypen för en WCF-klient. Standard: samlingstypen är System.Array. Kort formulär: /ct |
| /config:<configFile> | Anger filnamnet för den genererade konfigurationsfilen. Standard: output.config |
| /dataContractOnly | Genererar endast kod för datakontraktstyper. Tjänstkontraktstyper genereras inte. Du bör bara ange lokala metadatafiler för det här alternativet. Kort formulär: /dconly |
| /enableDataBinding | Implementerar gränssnittet på alla typer av INotifyPropertyChanged datakontrakt för att aktivera databindning. Kort formulär: /edb |
| /excludeType:<type> | Anger ett fullständigt kvalificerat eller sammansättningskvalificerat typnamn som ska undantas från refererade kontraktstyper. När du använder den här växeln tillsammans med /r från separata DLL:er refereras det fullständiga namnet på XSD-klassen.Kort formulär: /et |
| /importXmlTypes | Konfigurerar datakontraktsserialiseraren för att importera typer som inte är datakontrakt som IXmlSerializable-typer. |
| /inre | Genererar klasser som är markerade som interna. Standard: generera endast offentliga klasser. Kort formulär: /i |
| /language:<language> | Anger det programmeringsspråk som ska användas för kodgenerering. Du bör ange antingen ett språknamn som är registrerat i filen Machine.config eller det fullständigt kvalificerade namnet på en klass som ärver från CodeDomProvider. Värden: c#, cs, csharp, vb, visualbasic, c++, cpp Standard: csharp Kort formulär: /l |
| /mergeConfig | Sammanfogar den genererade konfigurationen till en befintlig fil i stället för att skriva över den befintliga filen. |
| /messageContract | Genererar typer av meddelandekontrakt. Kort formulär: /mc |
| /namespace:<string,string> | Anger en mappning från ett WSDL- eller XML-schemamålNamnområde till ett CLR-namnområde. Med "*" för targetNamespace mappas alla targetNamespaces utan en explicit mappning till det CLR-namnområdet. För att säkerställa att namnet på meddelandekontraktet inte kolliderar med åtgärdsnamnet bör du antingen kvalificera typreferensen med ::eller kontrollera att namnen är unika.Standard: Härledd från målnamnområdet för schemadokumentet för datakontrakt. Standardnamnområdet används för alla andra genererade typer. Kort formulär: /n Obs! När du genererar typer som ska användas med XmlSerializer stöds endast en enda namnområdesmappning. Alla genererade typer finns antingen i standardnamnområdet eller i det namnområde som anges av *. |
| /noConfig | Generera inte konfigurationsfiler. |
| /noStdLib | Referera inte till standardbibliotek. Standard: Mscorlib.dll och System.servicemodel.dll refereras. |
| /out:<file> | Anger filnamnet för den genererade koden. Standard: Härledd från WSDL-definitionsnamnet, WSDL-tjänstnamnet eller målnamnområdet för något av schemana. Kort formulär: /o |
| /reference:<file path> | Refererar till typer i den angivna sammansättningen. När du genererar klienter använder du det här alternativet för att ange sammansättningar som kan innehålla typer som representerar de metadata som importeras. Du kan inte ange meddelandekontrakt och XmlSerializer typer med den här växeln. Om DateTimeOffset det refereras används den här typen i stället för att generera en ny typ. Om programmet skrivs med .NET Framework 3.5 SvcUtil.exe referenser DateTimeOffset automatiskt. Kort formulär: /r |
| /Serialiseras | Genererar klasser som har markerats med serialiseringsbart attribut. Kort formulär: /s |
| /serviceContract | Generera endast kod för tjänstkontrakt. Klientklassen och konfigurationen genereras inte Kort formulär: /sc |
| /serializer:Auto | Välj serialiseraren automatiskt. Detta försöker använda serialiseraren datakontrakt och använder XmlSerializer om det misslyckas. Kort formulär: /ser |
| /serializer:DataContractSerializer | Genererar datatyper som använder Serialiseraren för datakontrakt för serialisering och deserialisering. Kort formulär: /ser:DataContractSerializer |
| /serializer:XmlSerializer | Genererar datatyper som använder XmlSerializer för serialisering och deserialisering. Kort formulär: /ser:XmlSerializer |
| /targetClientVersion | Ange vilken version av .NET Framework som programmet är inriktat på. Giltiga värden är Version30 och Version35. Standardvärdet är Version30.Kort formulär: /tcvVersion30: Använd /tcv:Version30 om du genererar kod för klienter som använder WinFX.Version35: Använd /tcv:Version35 om du genererar kod för klienter som använder .NET Framework 3.5. När du använder /tcv:Version35 med växeln /async genereras både händelsebaserade och motringningsbaserade/delegatbaserade asynkrona metoder. Dessutom har stöd för LINQ-aktiverade DataSets och DateTimeOffset aktiverats. |
| /inslagna | Styr om specialhölje används för dokumentliteralformaterade dokument med omslutna parametrar. Använd växeln /wrapped med verktyget Service Model Metadata Utility Tool (Svcutil.exe) för att ange normalt hölje. |
Kommentar
När tjänstbindningen är en av bindningarna som tillhandahålls av systemet (se System-Provided Bindings) och ProtectionLevel egenskapen är inställd på antingen None eller Sign, genererar Svcutil en konfigurationsfil med hjälp <av customBinding-elementet> i stället för det förväntade systembaserade elementet. Om tjänsten till exempel använder -elementet <wsHttpBinding> ProtectionLevel med värdet Signhar den genererade konfigurationen <customBinding> i avsnittet bindningar i stället för <wsHttpBinding>. Mer information om skyddsnivån finns i Förstå skyddsnivå.
Metadataexport
Svcutil.exe kan exportera metadata för tjänster, kontrakt och datatyper i kompilerade sammansättningar. Om du vill exportera metadata för en tjänst måste du använda /serviceName alternativet för att ange den tjänst som du vill exportera. Om du vill exportera alla typer av datakontrakt inom en sammansättning bör du använda alternativet /dataContractOnly . Som standard exporteras metadata för alla tjänstkontrakt i indatasammansättningarna.
svcutil.exe [/t:metadata] [/serviceName:<serviceConfigName>] [/dataContractOnly] <assemblyPath>*
| Argument | beskrivning |
|---|---|
assemblyPath |
Anger sökvägen till en sammansättning som innehåller tjänster, kontrakt eller datakontraktstyper som ska exporteras. Jokertecken för standardkommandoraden kan användas för att tillhandahålla flera filer som indata. |
| Alternativ | Description |
|---|---|
| /serviceName:<serviceConfigName> | Anger konfigurationsnamnet för en tjänst som ska exporteras. Om det här alternativet används måste en körbar sammansättning med en associerad konfigurationsfil skickas som indata. Svcutil.exe söker i alla associerade konfigurationsfiler efter tjänstkonfigurationen. Om konfigurationsfilerna innehåller några tilläggstyper måste de sammansättningar som innehåller dessa typer antingen finnas i GAC eller uttryckligen anges med hjälp av /reference alternativet . |
| /reference:<file path> | Lägger till den angivna sammansättningen i uppsättningen sammansättningar som används för att matcha typreferenser. Om du exporterar eller validerar en tjänst som använder tillägg från tredje part (beteenden, bindningar och BindingElements) som registrerats i konfigurationen använder du det här alternativet för att hitta tilläggssammansättningar som inte finns i GAC. Kort formulär: /r |
| /dataContractOnly | Fungerar endast på datakontraktstyper. Tjänstkontrakt bearbetas inte. Du bör bara ange lokala metadatafiler för det här alternativet. Kort formulär: /dconly |
| /excludeType:<type> | Anger det fullständigt kvalificerade eller sammansättningskvalificerade namnet på en typ som ska undantas från export. Det här alternativet kan användas när du exporterar metadata för en tjänst eller en uppsättning tjänstkontrakt för att undanta typer från att exporteras. Det här alternativet kan inte användas tillsammans med alternativet /dconly .När du har en enda sammansättning som innehåller flera tjänster och var och en använder separata klasser med samma XSD-namn, bör du ange tjänstnamnet i stället för XSD-klassnamnet för den här växeln. XSD- eller datakontraktstyper stöds inte. Kort formulär: /et |
Tjänstverifiering
Validering kan användas för att identifiera fel i tjänstimplementeringar utan att vara värd för tjänsten. Du måste använda alternativet /serviceName för att ange den tjänst som du vill verifiera.
svcutil.exe /validate /serviceName:<serviceConfigName> <assemblyPath>*
| Argument | beskrivning |
|---|---|
assemblyPath |
Anger sökvägen till en sammansättning som innehåller tjänsttyper som ska valideras. Sammansättningen måste ha en associerad konfigurationsfil för att tillhandahålla tjänstkonfiguration. Standardtecken för kommandorad kan användas för att tillhandahålla flera sammansättningar. |
| Alternativ | Description |
|---|---|
| /validera | Validerar en tjänstimplementering som anges av /serviceName alternativet. Om det här alternativet används måste en körbar sammansättning med en associerad konfigurationsfil skickas som indata.Kort formulär: /v |
| /serviceName:<serviceConfigName> | Anger konfigurationsnamnet för en tjänst som ska verifieras. Svcutil.exe söker igenom alla associerade konfigurationsfiler för alla indatasammansättningar för tjänstkonfigurationen. Om konfigurationsfilerna innehåller några tilläggstyper måste de sammansättningar som innehåller dessa typer antingen finnas i GAC eller uttryckligen anges med hjälp av /reference alternativet . |
| /reference:<file path> | Lägger till den angivna sammansättningen i uppsättningen sammansättningar som används för att matcha typreferenser. Om du exporterar eller validerar en tjänst som använder tillägg från tredje part (beteenden, bindningar och BindingElements) som registrerats i konfigurationen använder du det här alternativet för att hitta tilläggssammansättningar som inte finns i GAC. Kort formulär: /r |
| /dataContractOnly | Fungerar endast på datakontraktstyper. Tjänstkontrakt bearbetas inte. Du bör bara ange lokala metadatafiler för det här alternativet. Kort formulär: /dconly |
| /excludeType:<type> | Anger det fullständigt kvalificerade eller sammansättningskvalificerade namnet på en typ som ska undantas från valideringen. Kort formulär: /et |
Nedladdning av metadata
Svcutil.exe kan användas för att ladda ned metadata från tjänster som körs och spara metadata i lokala filer. Om du vill ladda ned metadata måste du ange alternativet /t:metadata . Annars genereras klientkoden. För HTTP- och HTTPS-URL-scheman försöker Svcutil.exe hämta metadata med WS-Metadata Exchange och DISCO. För alla andra URL-scheman använder Svcutil.exe endast WS-Metadata Exchange.
Svcutil utfärdar följande metadatabegäranden samtidigt för att hämta metadata.
MEX-begäran (WS-Transfer) till den angivna adressen
MEX-begäran till den angivna adressen med /mex bifogad
DISCO-begäran (med hjälp av DiscoveryClientProtocol från ASMX) till den angivna adressen.
Som standard använder Svcutil.exe bindningarna som definierats i MetadataExchangeBindings klassen för att göra MEX-begäranden. För att konfigurera bindningen som används för WS-Metadata Exchange måste du definiera en klientslutpunkt i konfigurationen som använder IMetadataExchange-kontraktet. Detta kan definieras antingen i konfigurationsfilen för Svcutil.exe eller i en annan konfigurationsfil som anges med hjälp av /svcutilConfig alternativet .
svcutil.exe /t:metadata <url>* | <epr>
| Argument | beskrivning |
|---|---|
url |
URL:en till en tjänstslutpunkt som tillhandahåller metadata eller till ett metadatadokument som finns online. |
epr |
Sökvägen till en XML-fil som innehåller en WS-adresseringsslutpunktReferens för en tjänstslutpunkt som stöder WS-Metadata Exchange. |
XmlSerializer-typgenerering
Tjänster och klientprogram som använder datatyper som är serialiserbara med hjälp av XmlSerializer generera och kompilera serialiseringskod för dessa datatyper vid körning, vilket kan leda till långsamma startprestanda.
Kommentar
Förgenererad serialiseringskod kan endast användas i klientprogram och inte i tjänster.
Svcutil.exe kan generera nödvändig C#-serialiseringskod från de kompilerade sammansättningarna för programmet, vilket förbättrar startprestandan för dessa program. Mer information finns i Så här: Förbättra starttiden för WCF-klientprogram med hjälp av XmlSerializer.
Kommentar
Svcutil.exe genererar endast kod för typer som används av servicekontrakt som finns i indatasammansättningarna.
svcutil.exe /t:xmlSerializer <assemblyPath>*
| Argument | beskrivning |
|---|---|
assemblyPath |
Anger sökvägen till en sammansättning som innehåller tjänstkontraktstyper. Serialiseringstyper genereras för alla Xml Serializable-typer i varje kontrakt. |
| Alternativ | Description |
|---|---|
| /reference:<file path> | Lägger till den angivna sammansättningen i uppsättningen sammansättningar som används för att matcha typreferenser. Kort formulär: /r |
| /excludeType:<type> | Anger det fullständigt kvalificerade eller sammansättningskvalificerade namnet på en typ som ska undantas från export eller validering. Kort formulär: /et |
| /out:<file> | Anger filnamnet för den genererade koden. Det här alternativet ignoreras när flera sammansättningar skickas som indata till verktyget. Standard: Härledd från sammansättningsnamnet. Kort formulär: /o |
| /UseSerializerForFaults | Anger att XmlSerializer ska användas för att läsa och skriva fel, i stället för standardvärdet DataContractSerializer. |
Exempel
Följande kommando genererar klientkod från en tjänst eller metadatadokument som körs online.
svcutil http://service/metadataEndpoint
Följande kommando genererar klientkod från lokala metadatadokument.
svcutil *.wsdl *.xsd /language:C#
Följande kommando genererar datakontraktstyper i Visual Basic från lokala schemadokument.
svcutil /dconly *.xsd /language:VB
Följande kommando hämtar metadatadokument från tjänster som körs.
svcutil /t:metadata http://service/metadataEndpoint
Följande kommando genererar metadatadokument för tjänstkontrakt och associerade typer i en sammansättning.
svcutil myAssembly.dll
Följande kommando genererar metadatadokument för en tjänst och alla associerade tjänstkontrakt och datatyper i en sammansättning.
svcutil myServiceHost.exe /serviceName:myServiceName
Följande kommando genererar metadatadokument för datatyper i en sammansättning.
svcutil myServiceHost.exe /dconly
Följande kommando verifierar tjänstvärd.
svcutil /validate /serviceName:myServiceName myServiceHost.exe
Följande kommando genererar serialiseringstyper för XmlSerializer typer som används av tjänstkontrakt i sammansättningen.
svcutil /t:xmlserializer myContractLibrary.exe
Maximal kvot för antal namntabelltecken
När du använder svcutil för att generera metadata för en tjänst kan du få följande meddelande:
Fel: Det går inte att hämta metadata från http://localhost:8000/somesservice/mex kvoten för maximalt antal namntabelltecken (16384) har överskridits vid läsning av XML-data. Namntabellen är en datastruktur som används för att lagra strängar som påträffas under XML-bearbetningen. Långa XML-dokument med icke-upprepande elementnamn, attributnamn och attributvärden kan utlösa den här kvoten. Den här kvoten kan ökas genom att ändra egenskapen MaxNameTableCharCount för xmldictionaryReaderQuotas-objektet som används när XML-läsaren skapas.
Det här felet kan orsakas av en tjänst som returnerar en stor WSDL-fil när du begär dess metadata. Problemet är att teckenkvoten för verktyget svcutil.exe överskrids. Det här värdet är inställt för att förhindra dos-attacker (Denial of Service). Du kan öka den här kvoten genom att ange följande konfigurationsfil för svcutil.
Följande konfigurationsfil visar hur du anger läsarkvoter för svcutil
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<system.serviceModel>
<bindings>
<customBinding>
<binding name="MyBinding">
<textMessageEncoding>
<readerQuotas maxDepth="2147483647" maxStringContentLength="2147483647"
maxArrayLength="2147483647" maxBytesPerRead="2147483647" maxNameTableCharCount="2147483647" />
</textMessageEncoding>
<httpTransport maxReceivedMessageSize="2147483647" maxBufferSize="2147483647" />
</binding>
</customBinding>
</bindings>
<client>
<endpoint binding="customBinding" bindingConfiguration="MyBinding"
contract="IMetadataExchange"
name="http" />
</client>
</system.serviceModel>
</configuration>
Skapa en ny fil med namnet svcutil.exe.config och kopiera XML-exempelkoden till den. Placera sedan filen i samma katalog som svcutil.exe. Nästa gång svcutil.exe körs hämtas de nya inställningarna.
Säkerhetsproblem
Du bör använda lämplig åtkomstkontrollista (ACL) för att skydda Svcutil.exe installationsmapp, Svcutil.config och filer som pekas på av /svcutilConfig. Detta kan förhindra att skadliga tillägg registreras och körs.
För att minimera risken för att säkerheten äventyras bör du dessutom inte lägga till ej betrodda tillägg som ska ingå i systemet eller använda icke betrodda kodprovidrar med Svcutil.exe.
Slutligen bör du inte använda verktyget på mellannivån i ditt program, eftersom det kan orsaka denial-of-service till den aktuella processen.