ServiceModel 中繼資料公用程式工具 (Svcutil.exe)ServiceModel Metadata Utility Tool (Svcutil.exe)

System.servicemodel 中繼資料公用程式工具是用來從元資料檔案產生服務模型程式碼,以及從服務模型程式碼產生元資料檔案。The ServiceModel Metadata Utility tool is used to generate service model code from metadata documents, and metadata documents from service model code.

SvcUtil.exeSvcUtil.exe

您可以在 Windows SDK 安裝位置找到「System.servicemodel 中繼資料公用程式」工具,特別是 %ProgramFiles%\Microsoft SDKs\Windows\v6.0\BinThe ServiceModel Metadata Utility Tool can be found at the Windows SDK installation location, specifically %ProgramFiles%\Microsoft SDKs\Windows\v6.0\Bin.

功能Functionalities

下表摘要說明此工具所提供的各種功能,以及討論其使用方式的對應主題:The following table summarizes the various functionalities provided by this tool, and the corresponding topic that discusses how it is used:

工作Task 主題Topic
從執行中服務或靜態中繼資料文件產生程式碼。Generates code from running services or static metadata documents. 從服務中繼資料產生 WCF 用戶端Generating a WCF Client from Service Metadata
從編譯的程式碼匯出中繼資料文件。Exports metadata documents from compiled code. 如何:使用 Svcutil.exe 來匯出已編譯服務程式碼的中繼資料How to: Use Svcutil.exe to Export Metadata from Compiled Service Code
驗證編譯的服務程式碼。Validates compiled service code. 如何:使用 Svcutil.exe 來驗證已編譯服務程式碼How to: Use Svcutil.exe to Validate Compiled Service Code
從執行中服務下載中繼資料文件。Downloads metadata documents from running services. 如何:使用 Svcutil.exe 來下載中繼資料文件How to: Use Svcutil.exe to Download Metadata Documents
產生序列化程式碼。Generates serialization code. 如何:使用 XmlSerializer 改善 WCF 用戶端應用程式的啟動時間How to: Improve the Startup Time of WCF Client Applications using the XmlSerializer

警告

如果提供作為參數的名稱相同,Svcutil 會覆寫磁片上的現有檔案。Svcutil overwrites existing files on a disk if the names supplied as parameters are identical. 這可能包括程式碼檔案、設定或中繼資料檔案。This can include code files, configuration, or metadata files. 若要在產生程式碼和設定檔案時避免這種情況,請使用 /mergeConfig 參數。To avoid this when generating code and configuration files, use the /mergeConfig switch.

此外,用於參考類型的 /r/ct 參數是用來產生資料合約。In addition, the /r and /ct switches for referencing types are for generating data contracts. 使用 XmlSerializer 時,這些參數不會運作。These switches do not work when using XmlSerializer.

逾時Timeout

此工具在抓取中繼資料時,有五分鐘的時間。The tool has a five minute timeout when retrieving metadata. 這個逾時只適用於在網路上擷取中繼資料,This timeout only applies to retrieving metadata over the network. 不適用於該中繼資料的任何處理。It does not apply to any processing of that metadata.

多目標Multi-targeting

這個工具不支援多目標。The tool does not support multi-targeting. 如果您想要從svcutil產生 .net 4 成品,請使用 .NET 4 SDK 中的svcutil。If you want to generate a .NET 4 artifact from svcutil.exe, use the svcutil.exe from the .NET 4 SDK. 若要產生 .NET 3.5 成品,請使用 .NET 3.5 SDK 中的可執行檔。To generate a .NET 3.5 artifact, use the executable from the .NET 3.5 SDK.

存取 WSDL 文件Accessing WSDL Documents

使用 Svcutil 存取參考安全性權杖服務 (STS) 的 WSDL 文件時,Svcutil 會對 STS 進行 WS-MetadataExchange 呼叫。When you use Svcutil to access a WSDL document that has a reference to a security token service (STS), Svcutil makes a WS-MetadataExchange call to the STS. 不過,服務可以使用 WS-MetadataExchange 或 HTTP GET 來公開 WSDL 文件。However, the service can expose its WSDL documents using either WS-MetadataExchange or HTTP GET. 因此,如果 STS 僅使用 HTTP GET 公開 WSDL 檔案,則以 WinFX 撰寫的用戶端將會失敗。Therefore, if the STS has only exposed the WSDL document using HTTP GET, a client written in WinFX will fail. 對於以 .NET Framework 3.5.NET Framework 3.5 撰寫的用戶端,Svcutil 會嘗試使用透過 ws-metadataexchange 和 HTTP GET 取得 STS WSDL。For clients written in .NET Framework 3.5.NET Framework 3.5, Svcutil attempts to use both WS-MetadataExchange and HTTP GET to obtain the STS WSDL.

使用 SvcUtil.exeUsing SvcUtil.exe

常見使用方式Common Usages

下表顯示此工具的一些常用選項:The following table shows some commonly used options for this tool:

選項Option 描述Description
/目錄: <directory >/directory:<directory> 要建立檔案的目錄。Directory to create files in.

預設:目前的目錄。Default: The current directory.

簡短形式:/dShort form: /d
/help/help 顯示工具的命令語法和選項。Displays the command syntax and options for the tool.

簡短形式:/?Short form: /?
/noLogo/noLogo 隱藏版權和橫幅訊息。Suppress the copyright and banner message.
/svcutilConfig: <configFile >/svcutilConfig:<configFile> 指定要取代 App.config 檔所使用的自訂組態檔。Specifies a custom configuration file to use instead of the App.config file. 指定的組態檔可用來註冊 system.serviceModel 副檔名,而不會變更工具的組態檔。This can be used to register system.serviceModel extensions without altering the tool's configuration file.
/target: <output 類型 >/target:<output type> 指定要由工具產生的輸出。Specifies the output to be generated by the tool.

有效值為 code、metadata 或 xmlSerializer。Valid values are code, metadata or xmlSerializer.

簡短形式:/tShort form: /t

程式碼產生Code Generation

Svcutil.exe 可從中繼資料文件產生服務合約、用戶端和資料型別的程式碼。Svcutil.exe can generate code for service contracts, clients and data types from metadata documents. 這些中繼資料文件可在永久性儲存裝置或線上擷取。These metadata documents can be on a durable storage, or be retrieved online. 線上擷取會遵循 WS-Metadata Exchange 通訊協定或 DISCO 通訊協定 (如需詳細資訊,請參閱「中繼資料下載」一節)。Online retrieval follows either the WS-Metadata Exchange protocol or the DISCO protocol (for details see the Metadata Download section).

您可以使用SvcUtil工具,根據預先定義的 WSDL 檔案來產生服務和資料合約。You can use the SvcUtil.exe tool to generate service and data contracts based on a predefined WSDL document. 使用 /serviceContract 參數,並指定可以下載或找到 WSDL 文件的 URL 或檔案位置。Use the /serviceContract switch and specify a URL or file location where the WSDL document can be downloaded or found. 這會產生 WSDL 檔案中所定義的服務和資料合約,然後用來執行抱怨服務。This generates the service and data contracts defined in the WSDL document that can then be used to implement a complaint service. 如需詳細資訊,請參閱如何:抓取中繼資料和執行相容的服務For more information, see How to: Retrieve Metadata and Implement a Compliant Service.

針對具有 BasicHttpCoNtextBinding 端點的服務, Svcutil會產生 BasicHttpBinding,並將 allowCookies 屬性設為 trueFor a service with a BasicHttpContextBinding endpoint, Svcutil.exe generates a BasicHttpBinding with the allowCookies attribute set to true instead. Cookie 用於伺服器上的內容。The cookies are used for context on the server. 如果您要在服務使用 Cookie 時管理用戶端上的內容,您可以手動修改組態以使用內容繫結。If you would like to manage context on the client when the service uses cookies, you can manually modify the configuration to use a context binding.

警告

Svcutil.exe 會根據 WSDL 或從服務收到的原則檔產生用戶端。Svcutil.exe generates the client based on the WSDL or policy file received from the service. 使用者主體名稱(UPN)是藉由串連 username、"@" 和完整功能變數名稱(FQDN)所產生。The user principal name (UPN) is generated by concatenating username, "@" and a fully-qualified domain name (FQDN). 但是,對於在 Active Directory 上登錄的使用者而言,這個格式無效,且此工具產生的 UPN 會造成 Kerberos 驗證失敗,並顯示「登入嘗試失敗」錯誤訊息。However, for users who registered on Active Directory, this format is not valid and the UPN generated by the tool causes a failure in Kerberos authentication with the error message "The logon attempt failed". 若要解決這個問題,您應手動修復由這個工具產生的用戶端檔案。To resolve this problem, you should manually fix the client file generated by this tool.

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

引數Argument 描述Description
epr XML 檔案的路徑,其中包含支援 WS-Metadata Exchange 之服務端點的 WS-Addressing EndpointReference。The path to an XML file that contains a WS-Addressing EndpointReference for a service endpoint that supports WS-Metadata Exchange. 如需詳細資訊,請參閱「中繼資料下載」一節。For more information, see the Metadata Download section.
metadataDocumentPath 元資料檔案(wsdlxsd)的路徑,其中包含要匯入至程式碼(.wsdl、.xsd、wspolicy 或 wsmex)的合約。The path to a metadata document (wsdl or xsd) that contains the contract to import into code (.wsdl, .xsd, .wspolicy, or .wsmex).

如果您指定的是中繼資料的遠端 URL,Svcutil 會根據您的指定執行匯入並包含其中的內容。Svcutil follows imports and includes when you specify a remote URL for metadata. 但是,如果您要處理本機檔案系統上的中繼資料檔,則必須在這個引數中指定所有檔案。However, if you want to process metadata files on the local file system, you must specify all files in this argument. 如此一來,您就可以在無法取得網路相依性的建置環境中使用 Svcutil。In this way, you can use Svcutil in a build environment where you cannot have network dependencies. 您可以為這個引數使用萬用字元(* .xsd,* .wsdl)。You can use wildcards (*.xsd, *.wsdl) for this argument.
url 提供中繼資料之服務端點的 URL,或裝載於線上之中繼資料文件的 URL。The URL to a service endpoint that provides metadata or to a metadata document hosted online. 如需如何擷取這些文件的詳細資訊,請參閱「中繼資料下載」一節。For more information on how these documents are retrieved, see the Metadata Download section.
選項Option 描述Description
/async/async 同時產生同步與非同步方法簽章。Generates both synchronous and asynchronous method signatures.

預設:只產生同步方法簽章。Default: generate only synchronous method signatures.

簡短形式:/aShort Form: /a
/collectionType: <type >/collectionType:<type> 指定 WCF 用戶端的清單集合類型。Specifies the list collection type for a WCF client.

預設值:集合類型為 System.object。Default: collection type is System.Array.

簡短形式:/ctShort Form: /ct
/config: <configFile >/config:<configFile> 指定產生之組態檔的檔案名稱。Specifies the filename for the generated configuration file.

預設:output.configDefault: output.config
/dataContractOnly/dataContractOnly 只產生資料合約類型的程式碼。Generates code for data contract types only. 不會產生「服務合約」類型。Service Contract types are not generated.

這個選項應該只能指定本機中繼資料檔案。You should only specify local metadata files for this option.

簡短形式:/dconlyShort Form: /dconly
/enableDataBinding/enableDataBinding 在所有「資料合約」類型上實作 INotifyPropertyChanged 介面,以啟用資料繫結。Implements the INotifyPropertyChanged interface on all Data Contract types to enable data binding.

簡短形式:/edbShort Form: /edb
/excludeType: <type >/excludeType:<type> 指定要從參考的合約類型排除的完整型別名稱或組件限定型別名稱。Specifies a fully-qualified or assembly-qualified type name to be excluded from referenced contract types.

將這個參數與個別 DLL 的 /r 一起使用時,會參考 XSD 類別的完整名稱。When using this switch together with /r from separate DLLs, the full name of the XSD class is referenced.

簡短形式:/etShort Form: /et
/importXmlTypes/importXmlTypes 設定資料合約序列化程式,將非資料合約類型匯入為 IXmlSerializable 類型。Configures the Data Contract serializer to import non-Data Contract types as IXmlSerializable types.
/internal/internal 產生標示為內部的類別。Generates classes that are marked as internal. 預設:只產生公用類別。Default: generate public classes only.

簡短形式:/iShort Form: /i
/language: <language >/language:<language> 指定要用於產生程式碼的程式語言。Specifies the programming language to use for code generation. 您應提供在 Machine.config 檔案中註冊的語言名稱,或繼承自 CodeDomProvider 之類別的完整名稱。You should provide either a language name registered in the Machine.config file, or the fully qualified name of a class that inherits from CodeDomProvider.

值:c#、cs、csharp、vb、visualbasic、c++、cppValues: c#, cs, csharp, vb, visualbasic, c++, cpp

預設:csharpDefault: csharp

簡短形式:/lShort form: /l
/mergeConfig/mergeConfig 將產生的組態合併至現有檔案,而非覆寫現有檔案。Merges the generated configuration into an existing file, instead of overwriting the existing file.
/messageContract/messageContract 產生「訊息合約」類型。Generates Message Contract types.

簡短形式:/mcShort Form: /mc
/namespace: <string,字串 >/namespace:<string,string> 指定從 WSDL 或 XML 結構描述 targetNamespace 到 CLR 命名空間的對應。Specifies a mapping from a WSDL or XML Schema targetNamespace to a CLR namespace. 使用適用于 targetNamespace 的 ' * ' 會對應所有 Targetnamespace,而不會明確對應至該 CLR 命名空間。Using '*' for the targetNamespace maps all targetNamespaces without an explicit mapping to that CLR namespace.

為了確保訊息合約名稱不會與作業名稱衝突,您應該以 :: 限定型別參考,或確定是唯一的名稱。To make sure that the message contract name does not collide with operation name, you should either qualify the type reference with ::, or make sure the names are unique.

預設:自資料合約的結構描述文件之目標命名空間衍生而來。Default: Derived from the target namespace of the schema document for Data Contracts. 預設命名空間用於所有其他產生的型別。The default namespace is used for all other generated types.

簡短形式: /n注意: 產生要與 XmlSerializer 搭配使用的類型時,只支援單一命名空間對應。Short Form: /n Note: When generating types to use with XmlSerializer, only a single namespace mapping is supported. 所有產生的類型都會在預設命名空間或 ' * ' 指定的命名空間中。All generated types will either be in the default namespace or the namespace specified by '*'.
/noConfig/noConfig 不要產生組態檔。Do not generate configuration files.
/noStdLib/noStdLib 不引用標準程式庫。Do not reference standard libraries.

預設:引用 Mscorlib.dll 和 System.servicemodel.dll。Default: Mscorlib.dll and System.servicemodel.dll are referenced.
/out: <file >/out:<file> 指定產生之程式碼的檔案名稱。Specifies the file name for the generated code.

預設:衍生自 WSDL 定義名稱、WSDL 服務名稱,或其中一個結構描述的目標命名空間。Default: Derived from the WSDL definition name, WSDL service name or target namespace of one of the schemas.

簡短形式:/oShort form: /o
/reference: <file 路徑 >/reference:<file path> 參考指定組件中的型別。References types in the specified assembly. 產生用戶端時,使用這個選項即可指定組件,這些組件可能包含代表匯入之中繼資料的類型。When generating clients, use this option to specify assemblies that might contain types that represent the metadata being imported.

您無法使用這個參數指定訊息合約和 XmlSerializer 型別。You cannot specify message contracts and XmlSerializer types using this switch.

如果已參考 DateTimeOffset,則會使用這個型別,而不會產生新型別。If DateTimeOffset referenced, this type is used instead of generating a new type. 如果應用程式是使用 .NET Framework 3.5.NET Framework 3.5 撰寫的,則 SvcUtil.exe 會自動參考 DateTimeOffsetIf the application is written using .NET Framework 3.5.NET Framework 3.5, SvcUtil.exe references DateTimeOffset automatically.

簡短形式:/rShort Form: /r
/serializable/serializable 產生已使用 Serializable 屬性標示的類別。Generates classes marked with the Serializable Attribute.

簡短形式:/sShort Form: /s
/serviceContract/serviceContract 只產生服務合約的程式碼。Generate code for service contracts only. 不會產生用戶端類別和組態Client class and configuration will not be generated

簡短形式:/scShort Form: /sc
/serializer:Auto/serializer:Auto 自動選取序列化程式。Automatically select the serializer. 這會嘗試使用資料合約序列化程式,並在發生失敗時使用 XmlSerializer。This tries to use the Data Contract serializer and uses the XmlSerializer if that fails.

簡短形式:/serShort Form: /ser
/serializer:DataContractSerializer/serializer:DataContractSerializer 產生使用「資料合約序列化程式」以進行序列化與還原序列化的資料型別。Generates data types that use the Data Contract Serializer for serialization and deserialization.

簡短形式:/ser:DataContractSerializerShort Form: /ser:DataContractSerializer
/serializer:XmlSerializer/serializer:XmlSerializer 產生使用 XmlSerializer 以進行序列化與還原序列化的資料型別。Generates data types that use the XmlSerializer for serialization and deserialization.

簡短形式:/ser:XmlSerializerShort Form: /ser:XmlSerializer
/targetClientVersion/targetClientVersion 指定應用程式的目標 .NET Framework 版本。Specify which version of .NET Framework the application is targeting. 有效值為 Version30Version35Valid values are Version30 and Version35. 預設值是 Version30The default value is Version30.

簡短形式:/tcvShort Form: /tcv

Version30:如果您要為使用 WinFX 的用戶端產生程式碼,請使用 /tcv:Version30Version30: Use /tcv:Version30 if you are generating code for clients that use WinFX.

Version35:如果您正在為使用 /tcv:Version35 的用戶端產生程式碼,則使用 .NET Framework 3.5.NET Framework 3.5Version35: Use /tcv:Version35 if you are generating code for clients that use .NET Framework 3.5.NET Framework 3.5. /tcv:Version35/async 參數一起使用時,會產生事件架構與回呼/委派架構的非同步方法。When using /tcv:Version35 with the /async switch, both event-based and callback/delegate-based asynchronous methods are generated. 此外,也會啟用具備 LINQ 功能的資料集和 DateTimeOffset 的支援。In addition, support for LINQ-enabled DataSets and DateTimeOffset is enabled.
/wrapped/wrapped 控制是否將特殊大小寫搭配 wrapped 參數用於文件常值樣式的文件。Controls whether special-casing is used for document-literal styled documents with wrapped parameters. 使用 /wrapped參數搭配服務模型中繼資料公用程式工具(Svcutil)工具來指定正常的大小寫。Use the /wrapped switch with the Service Model Metadata Utility Tool (Svcutil.exe) tool to specify normal casing.

注意

當服務系結為其中一個系統提供的系結時(請參閱系統提供的系結),而且 ProtectionLevel 屬性會設定為 NoneSign 時,Svcutil 會使用 <customBinding 來產生設定檔>元素,而不是預期的系統提供元素。When the service binding is one of the system-provided bindings (see System-Provided Bindings), and the ProtectionLevel property is set to either None or Sign, Svcutil generates a configuration file using the <customBinding> element instead of the expected system-provided element. 例如,如果服務使用 <wsHttpBinding> 項目,其中 ProtectionLevel 設為 Sign,則產生的組態會在繫結區段中有 <customBinding>,而非 <wsHttpBinding>For example, if the service uses the <wsHttpBinding> element with the ProtectionLevel set to Sign, the generated configuration has <customBinding> in the bindings section instead of <wsHttpBinding>. 如需保護層級的詳細資訊,請參閱瞭解保護層級For more information about the protection level, see Understanding Protection Level.

中繼資料匯出Metadata Export

Svcutil.exe 可匯出服務中繼資料、合約以及編譯組件中的資料型別。Svcutil.exe can export metadata for services, contracts and data types in compiled assemblies. 若要匯出服務的中繼資料,您必須使用 /serviceName 選項指定要匯出的服務。To export metadata for a service, you must use the /serviceName option to specify the service you would like to export. 若要匯出組件內的所有資料合約類型,請使用 /dataContractOnly 選項。To export all data contract types within an assembly, you should use the /dataContractOnly option. 根據預設,會匯出輸入組件中所有服務合約的中繼資料。By default, metadata is exported for all service contracts in the input assemblies.

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

引數Argument 描述Description
assemblyPath 指定包含要匯出之服務、合約或資料合約類型的組件路徑。Specifies the path to an assembly that contains services, contracts or data contract types to be exported. 標準命令列萬用字元可用於提供多個檔案做為輸入。Standard command line wildcards can be used to provide multiple files as input.
選項Option 描述Description
/serviceName: <serviceConfigName >/serviceName:<serviceConfigName> 指定要匯出的服務其組態名稱。Specifies the configuration name of a service to be exported. 如果使用這個選項,必須將可執行的組件和相關聯的組態檔當做輸入傳遞。If this option is used, an executable assembly with an associated configuration file must be passed as input. Svcutil.exe 會搜尋所有相關聯組態檔中的服務組態。Svcutil.exe searches all associated configuration files for the service configuration. 如果組態檔包含任何延伸型別,則包含這些型別的組件必須在 GAC 中或使用 /reference 選項明確地提供。If the configuration files contain any extension types, the assemblies that contain these types must either be in the GAC or explicitly provided using the /reference option.
/reference: <file 路徑 >/reference:<file path> 將指定的組件新增至用於解析型別參考的組件集合中。Adds the specified assembly to the set of assemblies used for resolving type references. 如果您正在匯出或驗證的服務使用的是註冊於組態中的協力廠商擴充功能 (Behavior、Binding 和 BindingElement),請使用這個選項找出不在 GAC 中的擴充功能組件。If you are exporting or validating a service that uses 3rd-party extensions (Behaviors, Bindings and BindingElements) registered in configuration, use this option to locate extension assemblies that are not in the GAC.

簡短形式:/rShort Form: /r
/dataContractOnly/dataContractOnly 只在資料合約類型上操作。Operates on data contract types only. 不處理服務合約。Service Contracts are not processed.

這個選項應該只能指定本機中繼資料檔案。You should only specify local metadata files for this option.

簡短形式:/dconlyShort Form: /dconly
/excludeType: <type >/excludeType:<type> 指定要從匯出作業排除的型別其完整名稱或組件限定名稱。Specifies the fully-qualified or assembly-qualified name of a type to be excluded from export. 在匯出服務中繼資料或是一組服務合約時,如果要從匯出作業排出某些型別,則可以使用這個選項。This option can be used when exporting metadata for a service, or a set of service contracts to exclude types from being exported. 這個選項無法與 /dconly 選項一起使用。This option cannot be used together with the /dconly option.

當您有單一組件包含多個服務,且每個服務使用具有相同 XSD 名稱的不同類別時,在指定這個參數時應使用服務名稱而不是 XSD 類別名稱。When you have a single assembly containing multiple services, and each uses separate classes with the same XSD name, you should specify the service name instead of the XSD class name for this switch.

不支援 XSD 或資料合約類型。XSD or data contract types are not supported.

簡短形式:/etShort Form: /et

服務驗證Service Validation

您可以使用驗證來偵測服務實作中的錯誤,而不需要裝載服務。Validation can be used to detect errors in service implementations without hosting the service. 您必須使用 /serviceName 選項來指出您要驗證的服務。You must use the /serviceName option to indicate the service you want to validate.

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

引數Argument 描述Description
assemblyPath 指定包含要驗證的服務類型之組件的路徑。Specifies the path to an assembly that contains service types to be validated. 組件必須具有相關聯的組態檔,才能提供服務組態。The assembly must have an associated configuration file to provide service configuration. 標準命令列萬用字元可用於提供多個組件。Standard command-line wildcards can be used to provide multiple assemblies.
選項Option 描述Description
/validate/validate 驗證由 /serviceName 選項指定的服務實作。Validates a service implementation specified by the /serviceName option. 如果使用這個選項,必須將可執行的組件和相關聯的組態檔當做輸入傳遞。If this option is used, an executable assembly with an associated configuration file must be passed as input.

簡短形式:/vShort Form: /v
/serviceName: <serviceConfigName >/serviceName:<serviceConfigName> 指定要驗證的服務其組態名稱。Specifies the configuration name of a service to be validated. Svcutil.exe 會搜尋所有輸入組件其所有相關聯組態檔中的服務組態。Svcutil.exe searches all associated configuration files of all input assemblies for the service configuration. 如果組態檔包含任何延伸型別,則包含這些型別的組件必須在 GAC 中或使用 /reference 選項明確地提供。If the configuration files contain any extension types, the assemblies that contains these types must either be in the GAC or explicitly provided using the /reference option.
/reference: <file 路徑 >/reference:<file path> 將指定的組件新增至用於解析型別參考的組件集合中。Adds the specified assembly to the set of assemblies used for resolving type references. 如果您正在匯出或驗證的服務使用的是註冊於組態中的協力廠商擴充功能 (Behavior、Binding 和 BindingElement),請使用這個選項找出不在 GAC 中的擴充功能組件。If you are exporting or validating a service that uses 3rd-party extensions (Behaviors, Bindings and BindingElements) registered in configuration, use this option to locate extension assemblies that are not in the GAC.

簡短形式:/rShort Form: /r
/dataContractOnly/dataContractOnly 只在資料合約類型上操作。Operates on data contract types only. 不處理服務合約。Service Contracts are not processed.

這個選項應該只能指定本機中繼資料檔案。You should only specify local metadata files for this option.

簡短形式:/dconlyShort Form: /dconly
/excludeType: <type >/excludeType:<type> 指定要從驗證作業排除的型別其完整名稱或組件限定名稱。Specifies the fully-qualified or assembly-qualified name of a type to be excluded from validation.

簡短形式:/etShort Form: /et

中繼資料下載Metadata Download

Svcutil.exe 可用於從執行中服務下載中繼資料,並將中繼資料儲存至本機檔案中。Svcutil.exe can be used to download metadata from running services, and save the metadata to local files. 若要下載中繼資料,您必須指定 /t:metadata 選項。To download metadata, you must specify the /t:metadata option. 否則,會產生用戶端程式碼。Otherwise, client code is generated. 對於 HTTP 和 HTTPS URL 結構描述,Svcutil.exe 會嘗試使用 WS-Metadata Exchange 和 DISCO 擷取中繼資料。For HTTP and HTTPS URL schemes, Svcutil.exe attempts to retrieve metadata using WS-Metadata Exchange and DISCO. 對於所有其他的 URL 結構描述,Svcutil.exe 只使用 WS-Metadata Exchange。For all other URL schemes, Svcutil.exe only uses WS-Metadata Exchange.

Svcutil 會同時發出以下中繼資料要求,以擷取中繼資料。Svcutil issues the following metadata requests simultaneously to retrieve metadata.

  • 對所提供位址的 MEX (WS-Transfer) 要求MEX (WS-Transfer) request to the supplied address

  • 對附加 /mex 之所提供位址的 MEX 要求MEX request to the supplied address with /mex appended

  • 對所提供位址的 DISCO 要求 (使用 ASMX 中的 DiscoveryClientProtocol)。DISCO request (using the DiscoveryClientProtocol from ASMX) to the supplied address.

根據預設,Svcutil.exe 會使用在 MetadataExchangeBindings 類別中定義的繫結進行 MEX 要求。By default, Svcutil.exe uses the bindings defined in the MetadataExchangeBindings class to make MEX requests. 若要設定用於 WS-Metadata Exchange 的繫結,您必須在使用 IMetadataExchange 合約的組態中定義用戶端端點。To configure the binding used for WS-Metadata Exchange, you must define a client endpoint in configuration that uses the IMetadataExchange contract. 這可在 Svcutil.exe 的組態檔中定義,或在使用 /svcutilConfig 選項所指定的另一個組態檔中定義。This can be defined either in the configuration file of Svcutil.exe, or in another configuration file specified using the /svcutilConfig option.

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

引數Argument 描述Description
url 提供中繼資料之服務端點的 URL,或裝載於線上之中繼資料文件的 URL。The URL to a service endpoint that provides metadata or to a metadata document hosted online.
epr XML 檔案的路徑,其中包含支援 WS-Metadata Exchange 之服務端點的 WS-Addressing EndpointReference。The path to an XML file that contains a WS-Addressing EndpointReference for a service endpoint that supports WS-Metadata Exchange.

XmlSerializer 型別產生XmlSerializer Type Generation

使用資料型別 (可使用 XmlSerializer 加以序列化) 的服務和用戶端應用程式會在執行階段針對這些資料型別產生和編譯序列化程式碼,這可能會導致啟動的效能變慢。Services and client applications that use data types that are serializable using the XmlSerializer generate and compile serialization code for those data types at runtime, which can result in slow start-up performance.

注意

預先產生的序列化程式碼只能用於用戶端應用程式中,而不能用於服務中。Pre-generated serialization code can only be used in client applications and not in services.

Svcutil.exe 可從應用程式的已編譯組件產生必要的 C# 序列化程式碼,因此可改善這些應用程式的啟動效能。Svcutil.exe can generate the necessary C# serialization code from the compiled assemblies for the application, thus improving start-up performance for these applications. 如需詳細資訊,請參閱如何:使用 XmlSerializer 改善 WCF 用戶端應用程式的啟動時間For more information, see How to: Improve the Startup Time of WCF Client Applications using the XmlSerializer.

注意

Svcutil.exe 只會針對輸入組件中的服務合約所使用的型別產生程式碼。Svcutil.exe only generates code for types used by Service Contracts found in the input assemblies.

svcutil.exe /t:xmlSerializer <assemblyPath>*

引數Argument 描述Description
assemblyPath 指定包含服務合約類型之組件的路徑。Specifies the path to an assembly that contains service contract types. 會針對每個合約中的所有 Xml 可序列化型別產生序列化型別。Serialization types are generated for all Xml Serializable types in each contract.
選項Option 描述Description
/reference: <file 路徑 >/reference:<file path> 將指定的組件新增至用於解析型別參考的組件集合中。Adds the specified assembly to the set of assemblies used for resolving type references.

簡短形式:/rShort Form: /r
/excludeType: <type >/excludeType:<type> 指定要從匯出作業或驗證作業排除的型別其完整名稱或組件限定名稱。Specifies the fully-qualified or assembly-qualified name of a type to be excluded from export or validation.

簡短形式:/etShort Form: /et
/out: <file >/out:<file> 指定產生之程式碼的檔案名稱。Specifies the filename for the generated code. 將多個組件做為工具的輸入傳遞時,會忽略這個選項。This option is ignored when multiple assemblies are passed as input to the tool.

預設:衍生自組件名稱。Default: Derived from the assembly name.

簡短形式:/oShort Form: /o
/UseSerializerForFaults/UseSerializerForFaults 指定應使用 XmlSerializer 來讀取和寫入錯誤,而非使用預設 DataContractSerializerSpecifies that the XmlSerializer should be used for reading and writing faults, instead of the default DataContractSerializer.

範例Examples

下列命令會從執行中服務或線上中繼資料文件產生用戶端程式碼。The following command generates client code from a running service or online metadata documents.

svcutil http://service/metadataEndpoint

下列命令會從本機中繼資料文件產生用戶端程式碼。The following command generates client code from local metadata documents.

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

下列命令會使用 Visual Basic 從本機結構描述文件產生用戶端合約類型。The following command generates data contract types in Visual Basic from local schema documents.

svcutil /dconly *.xsd /language:VB

下列命令會從執行中服務下載中繼資料文件。The following command downloads metadata documents from running services.

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

下列命令會在組件中產生服務合約和相關類型的中繼資料文件。The following command generates metadata documents for service contracts and associated types in an assembly.

svcutil myAssembly.dll

下列命令會在組件中產生服務、所有相關服務合約和資料型別的中繼資料文件。The following command generates metadata documents for a service, and all associated service contracts and data types in an assembly.

svcutil myServiceHost.exe /serviceName:myServiceName

下列命令會在組件中產生資料型別的中繼資料文件。The following command generates metadata documents for data types in an assembly.

svcutil myServiceHost.exe /dconly

下列命令會驗證服務裝載。The following command verifies service hosting.

svcutil /validate /serviceName:myServiceName myServiceHost.exe

下列命令會針對組件中任何服務合約所使用的 XmlSerializer 型別,產生序列化型別。The following command generates serialization types for XmlSerializer types used by any service contracts in the assembly.

svcutil /t:xmlserializer myContractLibrary.exe

最大名稱表格字元計數配額Maximum Nametable Character Count Quota

使用 svcutil 產生服務中繼資料時,可能會出現下列訊息:When using svcutil to generate metadata for a service, you may get the following message:

錯誤:讀取 XML 資料時,無法從 http://localhost:8000/somesservice/mex 取得中繼資料,但已超過最大的資料表數位符計數配額(16384)。Error: Cannot obtain Metadata from http://localhost:8000/somesservice/mex The maximum nametable character count quota (16384) has been exceeded while reading XML data. 名稱表格是一種資料結構,用來儲存在 XML 處理過程中所遇到的字串 - 具有不重複的項目名稱、屬性名稱及屬性值的冗長 XML 文件可能會觸發此配額限制。The nametable is a data structure used to store strings encountered during XML processing - long XML documents with non-repeating element names, attribute names and attribute values may trigger this quota. 在建立 XML 讀取器時變更 XmlDictionaryReaderQuotas 物件上使用的 MaxNameTableCharCount 屬性,便可以增加此配額。This quota may be increased by changing the MaxNameTableCharCount property on the XmlDictionaryReaderQuotas object used when creating the XML reader.

這個錯誤可能是當您要求服務的中繼資料時,傳回大型 WSDL 檔案的服務所導致。This error can be caused by a service that returns a large WSDL file when you request its metadata. 這時候的問題是已超過 svcutil.exe 工具的字元配額。The problem is that the character quota for the svcutil.exe tool is exceeded. 設定此值是為了防止阻斷服務 (DOS) 攻擊。This value is set to help prevent denial of service (dos) attacks. 可對 svcutil 指定下列組態檔,增加此配額。You can increase this quota by specifying the following config file for svcutil.

下列組態檔顯示如何設定 svcutil 的讀取器配額。The following config file shows how to set the reader quotas for 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>

建立名為 svcutil.exe.config 的新檔案,並將 XML 範例程式碼複製到此檔案。Create a new file called svcutil.exe.config and copy the XML example code into it. 然後將檔案放置在和 svcutil.exe 相同的目錄中。Then place the file in the same directory as svcutil.exe. 下次 svcutil.exe 執行時便會啟用新設定。The next time svcutil.exe is run it will pick up the new settings.

安全性考量Security Concerns

您應該使用適當的存取控制清單 (ACL) 來保護 Svcutil.exe 的安裝資料夾、Svcutil.config 和 /svcutilConfig 指向的檔案。You should use the appropriate Access Control List (ACL) to protect Svcutil.exe's installation folder, Svcutil.config, and files being pointed to by /svcutilConfig. 這可以防止註冊和執行惡意的延伸。This can prevent malicious extensions from being registered and run.

此外,為了將安全性危害的機率降到最低,您不應該將未受信任的延伸模組新增為系統的一部分,或使用不受信任的程式碼提供者搭配 Svcutil。In addition, to minimize the chance that security be compromised, you should not add untrusted extensions to be part of the system or use untrusted code providers with Svcutil.exe.

最後,您不應該在應用程式的中介層 (Middle Tier) 使用這個工具,因為它可能會對目前處理序造成阻絕服務攻擊。Finally, you should not use the tool in the middle-tier of your application, as it may cause denial-of-service to the current process.

請參閱See also