Nástroj ServiceModel Metadata Utility (Svcutil.exe)

Nástroj ServiceModel Metadata Utility slouží ke generování kódu modelu služby z dokumentů metadat a dokumentů metadat z kódu modelu služby.

SvcUtil.exe

Nástroj ServiceModel Metadata Utility najdete v umístění instalace sady Windows SDK, konkrétně %ProgramFiles%\Microsoft SDK\Windows\v6.0\Bin.

Funkce

Následující tabulka shrnuje různé funkce poskytované tímto nástrojem a odpovídající téma, které popisuje, jak se používá:

Úloha	Téma
Generuje kód ze spuštěných služeb nebo statických dokumentů metadat.	Generování klienta WCF z metadat služby
Exportuje dokumenty metadat z kompilovaného kódu.	Postupy: Použití nástroje Svcutil.exe k exportu metadat z kompilovaného kódu služby
Ověřuje zkompilovaný kód služby.	Postupy: Ověření zkompilovaného kódu služby pomocí nástroje Svcutil.exe
Stáhne dokumenty metadat ze spuštěných služeb.	Postupy: Stažení dokumentů metadat pomocí nástroje Svcutil.exe
Generuje serializační kód.	Postupy: Vylepšení doby spouštění klientských aplikací WCF pomocí XmlSerializer

Upozornění

Nástroj Svcutil přepíše existující soubory na disku, pokud jsou názvy zadané jako parametry identické. To může zahrnovat soubory kódu, konfiguraci nebo soubory metadat. Pokud se tomu chcete vyhnout při generování kódu a konfiguračních souborů, použijte /mergeConfig přepínač.

Kromě toho /r jsou přepínače pro /ct odkazování na typy určené ke generování kontraktů dat. Tyto přepínače nefungují při použití XmlSerializer.

Timeout

Nástroj má při načítání metadat časový limit pět minut. Tento časový limit platí jenom pro načítání metadat přes síť. Nevztahuje se na žádné zpracování těchto metadat.

Cílení na více verzí

Nástroj nepodporuje cílení na více verzí. Pokud chcete vygenerovat artefakt rozhraní .NET Framework 4 z svcutil.exe, použijte svcutil.exe ze sady .NET Framework 4 SDK. Pokud chcete vygenerovat artefakt rozhraní .NET Framework 3.5, použijte spustitelný soubor ze sady .NET Framework 3.5 SDK.

Přístup k dokumentům WSDL

Při použití nástroje Svcutil pro přístup k dokumentu WSDL, který má odkaz na službu tokenů zabezpečení (STS), Svcutil provede volání WS-MetadataExchange do služby tokenů zabezpečení. Služba však může vystavit své dokumenty WSDL pomocí WS-MetadataExchange nebo HTTP GET. Proto pokud služba STS odhalila pouze dokument WSDL pomocí HTTP GET, klient napsaný ve WinFX selže. Pro klienty napsané v rozhraní .NET Framework 3.5 se Svcutil pokusí použít WS-MetadataExchange i HTTP GET k získání STS WSDL.

Použití SvcUtil.exe

Běžná použití

Následující tabulka uvádí některé běžně používané možnosti pro tento nástroj:

Možnost	Popis
/directory:<directory>	Adresář pro vytváření souborů. Výchozí: Aktuální adresář. Krátký formulář: /d
/help	Zobrazí syntaxi příkazu a možnosti nástroje. Krátký formulář: /?
/noLogo	Potlačit autorská práva a bannerovou zprávu.
/svcutilConfig:<configFile>	Určuje vlastní konfigurační soubor, který se má použít místo souboru App.config. Dá se použít k registraci rozšíření system.serviceModel beze změny konfiguračního souboru nástroje.
/target:<output type>	Určuje výstup, který má nástroj vygenerovat. Platné hodnoty jsou kód, metadata nebo xmlSerializer. Krátký formulář: /t

Vytvoření kódu

Svcutil.exe může generovat kód pro kontrakty služeb, klienty a datové typy z dokumentů metadat. Tyto dokumenty metadat můžou být v trvalém úložišti nebo se načítají online. Online načítání se řídí protokolem WS-Metadata Exchange nebo DISKO (podrobnosti naleznete v části Stažení metadat).

Pomocí nástroje SvcUtil.exe můžete generovat kontrakty služeb a dat na základě předdefinovaného dokumentu WSDL. Použijte přepínač /serviceContract a zadejte adresu URL nebo umístění souboru, kde lze stáhnout nebo najít dokument WSDL. Tím se vygenerují kontrakty služeb a dat definované v dokumentu WSDL, které je pak možné použít k implementaci služby stížností. Další informace naleznete v tématu Postupy: Načtení metadat a implementace kompatibilní služby.

Pro službu s koncovým bodem BasicHttpContextBinding Svcutil.exe vygeneruje BasicHttpBinding s atributem allowCookies nastaveným na true místo toho. Soubory cookie se používají pro kontext na serveru. Pokud chcete spravovat kontext v klientovi, když služba používá soubory cookie, můžete konfiguraci ručně upravit tak, aby používala kontextovou vazbu.

Upozornění

Svcutil.exe vygeneruje klienta na základě souboru WSDL nebo zásady přijatého ze služby. Hlavní název uživatele (UPN) se generuje zřetězením uživatelského jména ,@" a plně kvalifikovaného názvu domény (FQDN). Pro uživatele, kteří se zaregistrovali ve službě Active Directory, ale tento formát není platný a hlavní název uživatele vygenerovaný nástrojem způsobí selhání při ověřování protokolem Kerberos s chybovou zprávou "Pokus o přihlášení selhal". Chcete-li tento problém vyřešit, měli byste ručně opravit klientský soubor vygenerovaný tímto nástrojem.

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

Argument	Popis
epr	Cesta k souboru XML, který obsahuje koncový bod ws-Adresování EndpointReference pro koncový bod služby, který podporuje WS-Metadata Exchange. Další informace najdete v části Stažení metadat.
metadataDocumentPath	Cesta k dokumentu metadat (wsdl nebo xsd), který obsahuje kontrakt pro import do kódu (.wsdl, .xsd, .wspolicy nebo .wsmex). Svcutil sleduje importy a zahrnuje při zadání vzdálené adresy URL pro metadata. Pokud však chcete zpracovávat soubory metadat v místním systému souborů, musíte v tomto argumentu zadat všechny soubory. Tímto způsobem můžete použít nástroj Svcutil v prostředí sestavení, kde nemůžete mít síťové závislosti. Pro tento argument můžete použít zástupné znaky (*.xsd, *.wsdl).
url	Adresa URL koncového bodu služby, který poskytuje metadata nebo dokument metadat hostovaný online. Další informace o tom, jak se tyto dokumenty načítají, najdete v části Stažení metadat.

Možnost	Popis
/Asynchronní	Generuje synchronní i asynchronní podpisy metod. Výchozí: Vygenerujte pouze synchronní podpisy metod. Krátký formulář: /a
/collectionType:<type>	Určuje typ kolekce seznamů pro klienta WCF. Výchozí hodnota: typ kolekce je System.Array. Krátký formulář: /ct
/config:<configFile>	Určuje název souboru pro vygenerovaný konfigurační soubor. Výchozí: output.config
/dataContractOnly	Generuje kód pouze pro typy kontraktů dat. Typy kontraktů služeb se negenerují. Pro tuto možnost byste měli zadat pouze místní soubory metadat. Krátký formulář: /dconly
/enableDataBinding	Implementuje rozhraní pro všechny typy datových kontraktů INotifyPropertyChanged , aby bylo možné datová vazba. Krátký formulář: /edb
/excludeType:<type>	Určuje plně kvalifikovaný název typu nebo název sestavení, který má být vyloučen z odkazovaných typů kontraktů. Při použití tohoto přepínače společně s samostatnými knihovnami /r DLL se odkazuje na úplný název třídy XSD. Krátký formulář: /et
/importXmlTypes	Konfiguruje serializátor kontraktu dat pro import ne-Data Contract typy jako IXmlSerializable typy.
/interní	Generuje třídy, které jsou označeny jako interní. Výchozí: Vygenerujte pouze veřejné třídy. Krátký formulář: /i
/language:<language>	Určuje programovací jazyk, který se má použít pro generování kódu. Měli byste zadat buď název jazyka zaregistrovaný v souboru Machine.config, nebo plně kvalifikovaný název třídy, která dědí z CodeDomProvider. Hodnoty: c#, cs, csharp, vb, visualbasic, c++, cpp Výchozí: csharp Krátký formulář: /l
/mergeConfig	Sloučí vygenerovanou konfiguraci do existujícího souboru místo přepsání existujícího souboru.
/messageContract	Generuje typy kontraktů zpráv. Krátký formulář: /mc
/namespace:<string, string>	Určuje mapování z objektu WSDL nebo XML Schema targetNamespace na obor názvů CLR. Použití *pro targetNamespace mapuje všechny objekty targetNamespace bez explicitního mapování na tento obor názvů CLR. Abyste měli jistotu, že název kontraktu zprávy nekoliduje s názvem operace, měli byste buď kvalifikovat odkaz na typ, ::nebo se ujistit, že názvy jsou jedinečné. Výchozí: Odvozeno z cílového oboru názvů dokumentu schématu pro kontrakty dat. Výchozí obor názvů se používá pro všechny ostatní generované typy. Krátký formulář: Poznámka: /n Při generování typů pro použití s XmlSerializer je podporováno pouze jedno mapování oboru názvů. Všechny vygenerované typy budou buď ve výchozím oboru názvů, nebo v oboru názvů určeném znakem *.
/noConfig	Nevygenerujte konfigurační soubory.
/noStdLib	Neodkazujte na standardní knihovny. Výchozí hodnota: odkazuje na Mscorlib.dll a System.servicemodel.dll.
/out:<file>	Určuje název souboru pro vygenerovaný kód. Výchozí: Odvozeno od názvu definice WSDL, názvu služby WSDL nebo cílového oboru názvů jednoho ze schémat. Krátký formulář: /o
/reference:<cesta k souboru>	Odkazy na typy v zadaném sestavení. Při generování klientů použijte tuto možnost k určení sestavení, která mohou obsahovat typy představující importovaná metadata. Pomocí tohoto přepínače nelze zadat kontrakty a XmlSerializer typy zpráv. Pokud DateTimeOffset na tento typ odkazujete, použije se tento typ místo generování nového typu. Pokud je aplikace napsaná pomocí rozhraní .NET Framework 3.5, SvcUtil.exe odkazy DateTimeOffset automaticky. Krátký formulář: /r
/Serializovatelný	Generuje třídy označené serializovatelným atributem. Krátký formulář: /s
/serviceContract	Vygenerujte kód pouze pro kontrakty služeb. Třída klienta a konfigurace nebudou generovány. Krátký formulář: /sc
/serializer:Auto	Automaticky vyberte serializátor. Toto se pokusí použít serializátor kontraktu dat a použije XmlSerializer, pokud se to nezdaří. Krátký formulář: /ser
/serializer:DataContractSerializer	Generuje datové typy, které používají Serializátor kontraktu dat pro serializaci a deserializaci. Krátký formulář: /ser:DataContractSerializer
/serializer:XmlSerializer	Generuje datové typy, které používají XmlSerializer serializaci a deserializaci. Krátký formulář: /ser:XmlSerializer
/targetClientVersion	Určete, na jakou verzi rozhraní .NET Framework cílí aplikace. Platné hodnoty jsou Version30 a Version35. Výchozí hodnota je typu Version30. Krátký formulář: /tcv Version30: Používá /tcv:Version30 se, pokud generujete kód pro klienty, kteří používají WinFX. Version35: Používá /tcv:Version35 se, pokud generujete kód pro klienty, kteří používají rozhraní .NET Framework 3.5. Při použití /tcv:Version35 s /async přepínačem se generují asynchronní metody založené na událostech i zpětné volání/delegování. Kromě toho je povolená podpora datových DateTimeOffset sad s podporou LINQ.
/zabalený	Určuje, jestli se speciální písmena používají pro dokumenty ve stylu literálu dokumentu s zabalenými parametry. Pomocí přepínače /wrapped s nástrojem Service Model Metadata Utility Tool (Svcutil.exe) zadejte normální velikost velikosti.

Poznámka:

Pokud je vazba služby jednou ze systémových vazeb (viz System-Provided Bindings) a ProtectionLevel vlastnost je nastavena na None buď nebo Sign, Svcutil generuje konfigurační soubor pomocí <customBinding> element místo očekávaného systémového prvku. Například pokud služba používá <wsHttpBinding> prvek se nastavenou nastavenou ProtectionLevel Sign, vygenerovaná konfigurace má <customBinding> v části vazby místo <wsHttpBinding>. Další informace o úrovni ochrany najdete v tématu Principy úrovně ochrany.

Export metadat

Svcutil.exe může exportovat metadata pro služby, kontrakty a datové typy v kompilovaných sestaveních. Pokud chcete exportovat metadata pro službu, musíte použít /serviceName možnost určit službu, kterou chcete exportovat. Pokud chcete exportovat všechny typy kontraktů dat v rámci sestavení, měli byste použít /dataContractOnly tuto možnost. Ve výchozím nastavení se metadata exportují pro všechny kontrakty služeb ve vstupních sestaveních.

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

Argument	Popis
assemblyPath	Určuje cestu k sestavení, které obsahuje služby, kontrakty nebo datové typy kontraktů, které se mají exportovat. Standardní zástupné čáry příkazového řádku lze použít k zadání více souborů jako vstupu.

Možnost	Popis
/serviceName:<serviceConfigName>	Určuje název konfigurace služby, která se má exportovat. Pokud se tato možnost použije, musí se jako vstup předat spustitelné sestavení s přidruženým konfiguračním souborem. Svcutil.exe vyhledá všechny přidružené konfigurační soubory pro konfiguraci služby. Pokud konfigurační soubory obsahují nějaké typy rozšíření, sestavení, která obsahují tyto typy, musí být buď v GAC, nebo explicitně zadanou /reference pomocí této možnosti.
/reference:<cesta k souboru>	Přidá zadané sestavení do sady sestavení použitých k překladu odkazů na typ. Pokud exportujete nebo ověřujete službu, která používá rozšíření třetích stran (chování, vazby a vazby) zaregistrované v konfiguraci, pomocí této možnosti vyhledejte sestavení rozšíření, která nejsou v GAC. Krátký formulář: /r
/dataContractOnly	Funguje pouze u datových typů kontraktů. Kontrakty služeb se nezpracovávají. Pro tuto možnost byste měli zadat pouze místní soubory metadat. Krátký formulář: /dconly
/excludeType:<type>	Určuje plně kvalifikovaný název nebo název sestavení typu, který má být vyloučen z exportu. Tuto možnost můžete použít při exportu metadat pro službu nebo sady kontraktů služeb k vyloučení typů z exportu. Tuto možnost nelze použít společně s /dconly touto možností. Pokud máte jedno sestavení obsahující více služeb a každý používá samostatné třídy se stejným názvem XSD, měli byste místo názvu třídy XSD pro tento přepínač zadat název služby. XSD nebo datové typy kontraktů nejsou podporovány. Krátký formulář: /et

Ověření služby

Ověřování se dá použít k detekci chyb v implementacích služeb bez hostování služby. Tuto možnost musíte použít /serviceName k označení služby, kterou chcete ověřit.

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

Argument	Popis
assemblyPath	Určuje cestu k sestavení, které obsahuje typy služeb, které se mají ověřit. Sestavení musí mít přidružený konfigurační soubor pro zajištění konfigurace služby. Standardní zástupné čáry příkazového řádku lze použít k poskytování více sestavení.

Možnost	Popis
/ověřit	Ověří implementaci služby určenou možností /serviceName . Pokud se tato možnost použije, musí se jako vstup předat spustitelné sestavení s přidruženým konfiguračním souborem. Krátký formulář: /v
/serviceName:<serviceConfigName>	Určuje název konfigurace služby, která se má ověřit. Svcutil.exe prohledá všechny přidružené konfigurační soubory všech vstupních sestavení pro konfiguraci služby. Pokud konfigurační soubory obsahují nějaké typy rozšíření, sestavení, která tyto typy obsahují, musí být buď v GAC, nebo explicitně poskytnuté pomocí /reference této možnosti.
/reference:<cesta k souboru>	Přidá zadané sestavení do sady sestavení použitých k překladu odkazů na typ. Pokud exportujete nebo ověřujete službu, která používá rozšíření třetích stran (chování, vazby a vazby) zaregistrované v konfiguraci, pomocí této možnosti vyhledejte sestavení rozšíření, která nejsou v GAC. Krátký formulář: /r
/dataContractOnly	Funguje pouze u datových typů kontraktů. Kontrakty služeb se nezpracovávají. Pro tuto možnost byste měli zadat pouze místní soubory metadat. Krátký formulář: /dconly
/excludeType:<type>	Určuje plně kvalifikovaný název nebo název sestavení typu, který má být vyloučen z ověření. Krátký formulář: /et

Stažení metadat

Svcutil.exe lze použít ke stahování metadat ze spuštěných služeb a ukládání metadat do místních souborů. Pokud chcete stáhnout metadata, musíte zadat /t:metadata možnost. Jinak se vygeneruje klientský kód. V případě schémat ADRES URL HTTP a HTTPS se Svcutil.exe pokusí načíst metadata pomocí serveru WS-Metadata Exchange a DISCO. Pro všechna ostatní schémata adres URL Svcutil.exe používá pouze exchange WS-Metadata.

Svcutil současně vydává následující požadavky na metadata pro načtení metadat.

• Požadavek MEX (WS-Transfer) na zadanou adresu

• Požadavek MEX na zadanou adresu s připojeným řetězcem /mex

• POŽADAVEK DISCO (pomocí DiscoveryClientProtocol z ASMX) na zadanou adresu.

Ve výchozím nastavení Svcutil.exe používá vazby definované ve MetadataExchangeBindings třídě k provádění požadavků MEX. Chcete-li nakonfigurovat vazbu použitou pro server WS-Metadata Exchange, je nutné definovat koncový bod klienta v konfiguraci, který používá kontrakt IMetadataExchange. To lze definovat buď v konfiguračním souboru Svcutil.exe, nebo v jiném konfiguračním souboru zadaném /svcutilConfig pomocí této možnosti.

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

Argument	Popis
url	Adresa URL koncového bodu služby, který poskytuje metadata nebo dokument metadat hostovaný online.
epr	Cesta k souboru XML, který obsahuje koncový bod ws-Adresování EndpointReference pro koncový bod služby, který podporuje WS-Metadata Exchange.

Generování typů XmlSerializer

Služby a klientské aplikace, které používají datové typy serializovatelné pomocí XmlSerializer kódu generování a kompilace serializace pro tyto datové typy za běhu, což může vést k pomalému spuštění výkonu.

Poznámka:

Předgenerovaný kód serializace lze použít pouze v klientských aplikacích a ne ve službách.

Svcutil.exe může vygenerovat potřebný kód serializace jazyka C# z kompilovaných sestavení pro aplikaci, čímž se zlepší spouštěcí výkon pro tyto aplikace. Další informace naleznete v tématu Postupy: Zlepšení doby spuštění klientských aplikací WCF pomocí XmlSerializer.

Poznámka:

Svcutil.exe generuje kód pouze pro typy používané kontrakty služeb nalezené ve vstupních sestaveních.

svcutil.exe /t:xmlSerializer <assemblyPath>*

Argument	Popis
assemblyPath	Určuje cestu k sestavení, které obsahuje typy kontraktů služeb. Typy serializace jsou generovány pro všechny serializovatelné typy Xml v každém kontraktu.

Možnost	Popis
/reference:<cesta k souboru>	Přidá zadané sestavení do sady sestavení použitých k překladu odkazů na typ. Krátký formulář: /r
/excludeType:<type>	Určuje plně kvalifikovaný název nebo název sestavení typu, který má být vyloučen z exportu nebo ověření. Krátký formulář: /et
/out:<file>	Určuje název souboru vygenerovaného kódu. Tato možnost se ignoruje, pokud je nástroji předáno více sestavení jako vstup. Výchozí: Odvozeno z názvu sestavení. Krátký formulář: /o
/UseSerializerForFaults	Určuje, že XmlSerializer se má použít pro čtení a zápis chyb místo výchozího DataContractSerializer.

Příklady

Následující příkaz vygeneruje klientský kód ze spuštěné služby nebo dokumentů metadat online.

svcutil http://service/metadataEndpoint

Následující příkaz vygeneruje klientský kód z místních dokumentů metadat.

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

Následující příkaz vygeneruje typy kontraktů dat v jazyce Visual Basic z dokumentů místního schématu.

svcutil /dconly *.xsd /language:VB

Následující příkaz stáhne dokumenty metadat ze spuštěných služeb.

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

Následující příkaz vygeneruje dokumenty metadat pro kontrakty služeb a přidružené typy v sestavení.

svcutil myAssembly.dll

Následující příkaz vygeneruje dokumenty metadat pro službu a všechny přidružené kontrakty služeb a datové typy v sestavení.

svcutil myServiceHost.exe /serviceName:myServiceName

Následující příkaz vygeneruje dokumenty metadat pro datové typy v sestavení.

svcutil myServiceHost.exe /dconly

Následující příkaz ověří hostování služby.

svcutil /validate /serviceName:myServiceName myServiceHost.exe

Následující příkaz generuje typy serializace pro XmlSerializer typy používané všemi kontrakty služeb v sestavení.

svcutil /t:xmlserializer myContractLibrary.exe

Maximální kvóta počtu znaků názvové tabulky

Při použití nástroje svcutil k vygenerování metadat pro službu se může zobrazit následující zpráva:

Chyba: Při čtení dat XML nelze získat metadata z http://localhost:8000/somesservice/mex maximální kvóty počtu znaků názvové tabulky (16384). Názvová tabulka je datová struktura používaná k ukládání řetězců zjištěných během zpracování XML – dlouhé dokumenty XML s neopakujícími názvy elementů, názvy atributů a hodnoty atributů mohou tuto kvótu aktivovat. Tato kvóta může být zvýšena změnou MaxNameTableCharCount vlastnost XmlDictionaryReaderQuotas objekt použitý při vytváření čtečky XML.

Příčinou této chyby může být služba, která při vyžádání metadat vrací velký soubor WSDL. Problém je, že je překročena kvóta znaků pro nástroj svcutil.exe. Tato hodnota je nastavená tak, aby zabránila útokům dos (dos). Tuto kvótu můžete zvýšit zadáním následujícího konfiguračního souboru pro nástroj svcutil.

Následující konfigurační soubor ukazuje, jak nastavit kvóty čtečky pro nástroj 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>

Vytvořte nový soubor s názvem svcutil.exe.config a zkopírujte do něj ukázkový kód XML. Potom soubor umístěte do stejného adresáře jako svcutil.exe. Při příštím spuštění svcutil.exe se nové nastavení vyzvedne.

Aspekty zabezpečení

Měli byste použít příslušný seznam řízení přístupu (ACL) k ochraně instalační složky Svcutil.exe, Svcutil.config a souborů, na které /svcutilConfigodkazuje . To může zabránit registraci a spuštění škodlivých rozšíření.

Kromě toho, abyste minimalizovali pravděpodobnost ohrožení zabezpečení, neměli byste přidávat nedůvěryhodná rozšíření, která budou součástí systému, nebo používat nedůvěryhodné zprostředkovatele kódu s Svcutil.exe.

Nakonec byste nástroj neměli používat ve střední vrstvě aplikace, protože může způsobit odepření služby aktuálnímu procesu.

Viz také

• DataContractAttribute
• DataMemberAttribute
• Postupy: Vytvoření klienta