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

發行項
09/12/2008

ServiceModel 中繼資料公用程式工具用於從中繼資料文件產生服務模型程式碼，以及從服務模型程式碼產生中繼資料文件。

備註

ServiceModel 中繼資料公用程式工具位於 Windows SDK 安裝位置中，具體而言就是 C:\Program Files\Microsoft SDKs\Windows\v6.0\Bin

下表摘要說明這個工具所提供的各種功能，以及討論工具用法的對應主題。

工作	主題
從執行中服務或靜態中繼資料文件產生程式碼。	Generating a WCF Client from Service Metadata
從編譯的程式碼匯出中繼資料文件。	How to: Use Svcutil.exe to Export Metadata from Compiled Service Code
驗證編譯的服務程式碼。	How to: Use Svcutil.exe to Validate Compiled Service Code
從執行中服務下載中繼資料文件。	How to: Download Metadata Documents from a Running Service
產生序列化程式碼。	How to: Use Svcutil.exe to Generate Serialization Code

注意：
如果做為參數所提供的名稱相同，則 Svcutil 將覆寫磁碟上現有的檔案。這會包括程式碼檔案、組態或中繼資料檔案。為了在產生程式碼和組態檔時避免這種情況，請使用 /mergeConfig 參數。此外，用於參考型別的 /r 和 /ct 參數可用於產生資料合約。使用 XmlSerializer 時，這些參數不會運作。

如果做為參數所提供的名稱相同，則 Svcutil 將覆寫磁碟上現有的檔案。這會包括程式碼檔案、組態或中繼資料檔案。為了在產生程式碼和組態檔時避免這種情況，請使用 /mergeConfig 參數。

此外，用於參考型別的 /r 和 /ct 參數可用於產生資料合約。使用 XmlSerializer 時，這些參數不會運作。

這個工具在擷取中繼資料時會有 5 分鐘的逾時。這個逾時只適用於在網路上擷取中繼資料，不適用於該中繼資料的任何處理。

使用 Svcutil 存取參考安全性權杖服務 (STS) 的 WSDL 文件時，Svcutil 會對 STS 進行 WS-MetadataExchange 呼叫。不過，服務可以使用 WS-MetadataExchange 或 HTTP GET 來公開 WSDL 文件。因此，如果 STS 使用 HTTP GET 只公開 WSDL 文件時，寫入 .NET Framework 3.0 中的用戶端將失敗。對於寫入 .NET Framework 3.5 的用戶端，Svcutil 會嘗試使用 WS-MetadataExchange 和 HTTP GET 取得 STS WSDL。

常見使用方式

下表顯示這個工具的一些常用選項。

選項	描述
/directory:<directory>	要建立檔案的目錄。預設：目前的目錄。簡短形式：/d
/help	顯示工具的命令語法和選項。簡短形式：/?
/noLogo	隱藏版權和橫幅訊息。
/svcutilConfig:<configFile>	指定要取代 App.config 檔所使用的自訂組態檔。指定的組態檔可用來註冊 system.serviceModel 副檔名，而不會變更工具的組態檔。
/target:<output type>	指定要由工具產生的輸出。有效值為 code、metadata 或 xmlSerializer。簡短形式：/t

程式碼產生

Svcutil.exe 可從中繼資料文件產生服務合約、用戶端和資料型別的程式碼。這些中繼資料文件可在永久性儲存裝置或線上擷取。線上擷取會遵循 WS-Metadata Exchange 通訊協定或 DISCO 通訊協定 (如需詳細資訊，請參閱「中繼資料下載」一節)。

對於含 BasicHttpContextbinding 端點的服務，Svcutil.exe 會產生 BasicHttpBinding，其 allowCookies 屬性設為 true。Cookie 用於伺服器上的內容。如果您要在服務使用 Cookie 時管理用戶端上的內容，您可以手動修改組態以使用內容繫結。

注意：
Svcutil.exe 會根據 WSDL 或從服務收到的原則檔產生用戶端。使用者主要名稱 (UPN) 是串連使用者名稱、"@" 和完整網域名稱 (FQDN) 所產生的。但是，對於在 Active Directory 上登錄的使用者而言，這個格式無效，且此工具產生的 UPN 會造成 Kerberos 驗證失敗，並顯示「登入嘗試失敗」錯誤訊息。若要解決這個問題，您應手動修復由這個工具產生的用戶端檔案。

Svcutil.exe 會根據 WSDL 或從服務收到的原則檔產生用戶端。使用者主要名稱 (UPN) 是串連使用者名稱、"@" 和完整網域名稱 (FQDN) 所產生的。但是，對於在 Active Directory 上登錄的使用者而言，這個格式無效，且此工具產生的 UPN 會造成 Kerberos 驗證失敗，並顯示「登入嘗試失敗」錯誤訊息。若要解決這個問題，您應手動修復由這個工具產生的用戶端檔案。

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

引數	說明
epr	XML 檔案的路徑，其中包含支援 WS-Metadata Exchange 之服務端點的 WS-Addressing EndpointReference。如需詳細資訊，請參閱「中繼資料下載」一節。
metadataDocumentPath	中繼資料文件 (wsdl 或 xsd) 的路徑，其中包含要匯入程式碼的合約 (.wsdl、.xsd、.wspolicy 或 .wsmex)。如果您指定的是中繼資料的遠端 URL，Svcutil 會根據您的指定執行匯入並包含其中的內容。但是，如果您要處理本機檔案系統上的中繼資料檔，則必須在這個引數中指定所有檔案。如此一來，您就可以在無法取得網路相依性的建置環境中使用 Svcutil。您可以為這個引數使用萬用字元 (例如 .xsd、.wsdl)。
url	提供中繼資料之服務端點的 URL，或裝載於線上之中繼資料文件的 URL。如需如何擷取這些文件的詳細資訊，請參閱「中繼資料下載」一節。

epr

XML 檔案的路徑，其中包含支援 WS-Metadata Exchange 之服務端點的 WS-Addressing EndpointReference。如需詳細資訊，請參閱「中繼資料下載」一節。

metadataDocumentPath

中繼資料文件 (wsdl 或 xsd) 的路徑，其中包含要匯入程式碼的合約 (.wsdl、.xsd、.wspolicy 或 .wsmex)。

如果您指定的是中繼資料的遠端 URL，Svcutil 會根據您的指定執行匯入並包含其中的內容。但是，如果您要處理本機檔案系統上的中繼資料檔，則必須在這個引數中指定所有檔案。如此一來，您就可以在無法取得網路相依性的建置環境中使用 Svcutil。您可以為這個引數使用萬用字元 (例如 *.xsd、*.wsdl)。

url

提供中繼資料之服務端點的 URL，或裝載於線上之中繼資料文件的 URL。如需如何擷取這些文件的詳細資訊，請參閱「中繼資料下載」一節。

選項	說明
/async	同時產生同步與非同步方法簽章。預設：只產生同步方法簽章。簡短形式：/a
/collectionType:<type>	當從結構描述產生程式碼時，指定要做為集合資料型別之型別的完整名稱或組件限定名稱。簡短形式：/ct
/config:<configFile>	指定產生之組態檔的檔案名稱。預設：output.config
/dataContractOnly	只產生資料合約類型的程式碼。不會產生「服務合約」類型。這個選項應該只能指定本機中繼資料檔案。簡短形式：/dconly
/enableDataBinding	在所有「資料合約」類型上實作 INotifyPropertyChanged 介面，以啟用資料繫結。簡短形式：/edb
/excludeType:<type>	指定要從參考的合約類型排除的完整型別名稱或組件限定型別名稱。將這個參數與個別 DLL 的 /r 一起使用時，會參考 XSD 類別的完整名稱。簡短形式：/et
/importXmlTypes	設定資料合約序列化程式，將非資料合約類型匯入為 IXmlSerializable 類型。
/internal	產生標示為內部的類別。預設：只產生公用類別。簡短形式：/i
/language:<language>	指定要用於產生程式碼的程式語言。您應提供在 Machine.config 檔案中註冊的語言名稱，或繼承自 CodeDomProvider 之類別的完整名稱。值：c#、cs、csharp、vb、visualbasic、c++、cpp 預設：csharp 簡短形式：/l 注意：此參數只支援 Visual Studio 2005 SP1 所隨附程式碼提供者的 C++。
/mergeConfig	將產生的組態合併至現有檔案，而非覆寫現有檔案。
/messageContract	產生「訊息合約」類型。簡短形式：/mc
/namespace:<string,string>	指定從 WSDL 或 XML 結構描述 targetNamespace 到 CLR 命名空間的對應。針對 targetNamespace 使用 '*'，將會對應至所有的 targetNamespace，而不會明確對應至該 CLR 命名空間。為了確保訊息合約名稱不會與作業名稱衝突，您應該以 :: 限定型別參考，或確定是唯一的名稱。預設：自資料合約的結構描述文件之目標命名空間衍生而來。預設命名空間用於所有其他產生的型別。簡短形式：/n
/noConfig	不要產生組態檔。
/noStdLib	不引用標準程式庫。預設：引用 Mscorlib.dll 和 System.servicemodel.dll。
/out:<file>	指定產生之程式碼的檔案名稱。預設：衍生自 WSDL 定義名稱、WSDL 服務名稱，或其中一個結構描述的目標命名空間。簡短形式：/o
/serializable	產生已使用 Serializable 屬性標示的類別。簡短形式：/s
/targetClientVersion	指定做為應用程式目標的 .NET Framework 版本。有效值為 Version30 和 Version35。預設值為 Version30，意指 SvcUtil.exe 工具預設以 .NET Framework 3.0 做為目標。簡短形式：/tcv Version30：如果您正在為使用 .NET Framework 3.0 的用戶端產生程式碼，則使用 `/tcv:Version30`。透過使用這個值，SvcUtil.exe 工具會產生程式碼，這個程式碼會參考 .NET Framework 3.0 和上一版中的功能。 Version35：如果您正在為使用 .NET Framework 3.5 的用戶端產生程式碼，則使用 `/tcv:Version35`。透過使用這個值，SvcUtil.exe 工具會產生程式碼，這個程式碼會參考 .NET Framework 3.5 和上一版中的功能。將 `/tcv:Version35` 與 /async 參數一起使用時，會產生事件架構與回呼/委派架構的非同步方法。此外，也會啟用具備 LINQ 功能的資料集和 DateTimeOffset 的支援。
/reference:<file path>	參考指定組件中的型別。產生用戶端時，使用這個選項即可指定組件，這些組件可能包含代表匯入之中繼資料的類型。您無法使用這個參數指定訊息合約和 XmlSerializer 型別。如果已參考 DateTimeOffset，則會使用這個型別，而不會產生新型別。如果應用程式是使用 .NET Framework 3.5 撰寫的，則 SvcUtil.exe 會自動參考 DateTimeOffset。簡短形式：/r
/serializer:Auto	自動選取序列化程式。這會使用資料合約序列化程式。如果這個作業失敗，則使用 XmlSerializer。簡短形式：/ser:Auto
/serializer:DataContractSerializer	產生使用「資料合約序列化程式」以進行序列化與還原序列化的資料型別。簡短形式：/ser:DataContractSerializer
/serializer:XmlSerializer	產生使用 XmlSerializer 以進行序列化與還原序列化的資料型別。簡短形式：/ser:XmlSerializer

注意：
服務繫結為其中一個系統所提供繫結 (請參閱System-Provided Bindings)，且 ProtectionLevel 屬性設為 None 或 Sign 時，Svcutil 會使用 <customBinding> 項目產生組態檔，而非使用預期的系統提供項目。例如，如果服務使用 <wsHttpBinding> 項目，其中 ProtectionLevel 設為 Sign，則產生的組態會在繫結區段中有 <customBinding>，而非 <wsHttpBinding>。如需保護層級的詳細資訊，請參閱Understanding Protection Level。

服務繫結為其中一個系統所提供繫結 (請參閱System-Provided Bindings)，且 ProtectionLevel 屬性設為 None 或 Sign 時，Svcutil 會使用 <customBinding> 項目產生組態檔，而非使用預期的系統提供項目。例如，如果服務使用 <wsHttpBinding> 項目，其中 ProtectionLevel 設為 Sign，則產生的組態會在繫結區段中有 <customBinding>，而非 <wsHttpBinding>。如需保護層級的詳細資訊，請參閱Understanding Protection Level。

中繼資料匯出

Svcutil.exe 可匯出服務中繼資料、合約以及編譯組件中的資料型別。若要匯出服務的中繼資料，您必須使用 /serviceName 選項指定要匯出的服務。若要匯出組件內的所有資料合約類型，請使用 /dataContractOnly 選項。根據預設，會匯出輸入組件中所有服務合約的中繼資料。

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

引數	說明
assemblyPath	指定包含要匯出之服務、合約或資料合約類型的組件路徑。標準命令列萬用字元可用於提供多個檔案做為輸入。

選項	說明
/serviceName:<serviceConfigName>	指定要匯出的服務其組態名稱。如果使用這個選項，必須將可執行的組件和相關聯的組態檔當做輸入傳遞。Svcutil.exe 會搜尋所有相關聯組態檔中的服務組態。如果組態檔包含任何延伸型別，則包含這些型別的組件必須在 GAC 中或使用 /reference 選項明確地提供。
/reference:<file path>	將指定的組件新增至用於解析型別參考的組件集合中。如果您正在匯出或驗證的服務使用的是註冊於組態中的協力廠商擴充功能 (Behavior、Binding 和 BindingElement)，請使用這個選項找出不在 GAC 中的擴充功能組件。簡短形式：/r
/dataContractOnly	只在資料合約類型上操作。不處理服務合約。這個選項應該只能指定本機中繼資料檔案。簡短形式：/dconly
/excludeType:<type>	指定要從匯出作業排除的型別其完整名稱或組件限定名稱。在匯出服務中繼資料或是一組服務合約時，如果要從匯出作業排出某些型別，則可以使用這個選項。這個選項無法與 /dconly 選項一起使用。當您有單一組件包含多個服務，且每個服務使用具有相同 XSD 名稱的不同類別時，在指定這個參數時應使用服務名稱而不是 XSD 類別名稱。不支援 XSD 或資料合約類型。簡短形式：/et

服務驗證

您可以使用驗證來偵測服務實作中的錯誤，而不需要裝載服務。您必須使用 /serviceName 選項來指出您要驗證的服務。

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

引數	說明
assemblyPath	指定包含要驗證的服務類型之組件的路徑。組件必須具有相關聯的組態檔，才能提供服務組態。標準命令列萬用字元可用於提供多個組件。

選項	說明
/validate	驗證由 /serviceName 選項指定的服務實作。如果使用這個選項，必須將可執行的組件和相關聯的組態檔當做輸入傳遞。簡短形式：/v
/serviceName:<serviceConfigName>	指定要驗證的服務其組態名稱。Svcutil.exe 會搜尋所有輸入組件其所有相關聯組態檔中的服務組態。如果組態檔包含任何延伸型別，則包含這些型別的組件必須在 GAC 中或使用 /reference 選項明確地提供。
/reference:<file path>	將指定的組件新增至用於解析型別參考的組件集合中。如果您正在匯出或驗證的服務使用的是註冊於組態中的協力廠商擴充功能 (Behavior、Binding 和 BindingElement)，請使用這個選項找出不在 GAC 中的擴充功能組件。簡短形式：/r
/dataContractOnly	只在資料合約類型上操作。不處理服務合約。這個選項應該只能指定本機中繼資料檔案。簡短形式：/dconly
/excludeType:<type>	指定要從驗證作業排除的型別其完整名稱或組件限定名稱。簡短形式：/et

中繼資料下載

Svcutil.exe 可用於從執行中服務下載中繼資料，並將中繼資料儲存至本機檔案中。若要下載中繼資料，您必須指定 /t:metadata 選項。否則，會產生用戶端程式碼。對於 HTTP 和 HTTPS URL 結構描述，Svcutil.exe 會嘗試使用 WS-Metadata Exchange 和 DISCO 擷取中繼資料。對於所有其他的 URL 結構描述，Svcutil.exe 只使用 WS-Metadata Exchange。

Svcutil 會同時發出以下中繼資料要求，以擷取中繼資料。

對所提供位址的 MEX (WS-Transfer) 要求
對附加 /mex 之所提供位址的 MEX 要求
對所提供位址的 DISCO 要求 (使用 ASMX 中的 DiscoveryClientProtocol)。

根據預設，Svcutil.exe 會使用在 MetadataExchangeBindings 類別中定義的繫結進行 MEX 要求。若要設定用於 WS-Metadata Exchange 的繫結，您必須在使用 IMetadataExchange 合約的組態中定義用戶端端點。這可在 Svcutil.exe 的組態檔中定義，或在使用 /svcutilConfig 選項所指定的另一個組態檔中定義。

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

引數	說明
url	提供中繼資料之服務端點的 URL，或裝載於線上之中繼資料文件的 URL。
epr	XML 檔案的路徑，其中包含支援 WS-Metadata Exchange 之服務端點的 WS-Addressing EndpointReference。

XmlSerializer 型別產生

使用資料型別 (可使用 XmlSerializer 加以序列化) 的服務和用戶端應用程式會在執行階段針對這些資料型別產生和編譯序列化程式碼，這可能會導致啟動的效能變慢。

注意：
預先產生的序列化程式碼只能用於用戶端應用程式中，而不能用於服務中。

Svcutil.exe 可從應用程式的已編譯組件產生必要的 C# 序列化程式碼，因此可改善這些應用程式的啟動效能。如需詳細資訊，請參閱 How to: Improve the Startup Time of WCF Client Applications using the XmlSerializer。

注意：
Svcutil.exe 只會針對輸入組件中的服務合約所使用的型別產生程式碼。

svcutil.exe /t:xmlSerializer <assemblyPath>*

引數	說明
assemblyPath	指定包含服務合約類型之組件的路徑。會針對每個合約中的所有 Xml 可序列化型別產生序列化型別。

選項	說明
/reference:<file path>	將指定的組件新增至用於解析型別參考的組件集合中。簡短形式：/r
/excludeType:<type>	指定要從匯出作業或驗證作業排除的型別其完整名稱或組件限定名稱。簡短形式：/et
/out:<file>	指定產生之程式碼的檔案名稱。將多個組件做為工具的輸入傳遞時，會忽略這個選項。預設：衍生自組件名稱。簡短形式：/o
/UseSerializerForFaults	指定應使用 XmlSerializer 來讀取和寫入錯誤，而非使用預設 DataContractSerializer。

範例

下列命令會從執行中服務或線上中繼資料文件產生用戶端程式碼。

svcutil http://service/metadataEndpoint

下列命令會從本機中繼資料文件產生用戶端程式碼。

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

下列命令會使用 Visual Basic 從本機結構描述文件產生用戶端合約類型。

svcutil /dconly *.xsd /language:VB

下列命令會從執行中服務下載中繼資料文件。

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

下列命令會在組件中產生服務合約和相關類型的中繼資料文件。

svcutil myAssembly.dll

下列命令會在組件中產生服務、所有相關服務合約和資料型別的中繼資料文件。

svcutil myServiceHost.exe /serviceName:myServiceName

下列命令會在組件中產生資料型別的中繼資料文件。

svcutil myServiceHost.exe /dconly

下列命令會驗證服務裝載。

svcutil /validate /serviceName:myServiceName myServiceHost.exe

下列命令會針對組件中任何服務合約所使用的 XmlSerializer 型別，產生序列化型別。

svcutil /t:xmlserializer myContractLibrary.exe

安全性考量

您應該使用適當的存取控制清單 (ACL) 來保護 Svcutil.exe 的安裝資料夾、Svcutil.config 和 /svcutilConfig 指向的檔案。這可以防止註冊和執行惡意的延伸。

此外，為了將安全性遭受危害的機會降到最小，您不應該將未受信任的延伸新增為系統的一部分，或使用具有 Svcutil.exe 的未受信任程式碼提供者。

最後，您不應該在應用程式的中介層 (Middle Tier) 使用這個工具，因為它可能會對目前處理序造成阻絕服務攻擊。

共用方式為