ServiceModel メタデータ ユーティリティ ツールを使用して、メタデータ ドキュメントからサービス モデル コードを生成したり、サービス モデル コードからメタデータ ドキュメントを生成します。
解説
ServiceModel メタデータ ユーティリティ ツールは、Windows SDK のインストール場所である C:\Program Files\Microsoft SDKs\Windows\v6.0\Bin にあります。
次の表は、このツールによって提供されるさまざまな機能とその使用方法を説明する対応トピックを示します。
.gif) 注意 : |
|---|
|
パラメータに指定された名前が同じ場合、Svcutil はディスク上の既存のファイルを上書きします。これには、コード ファイル、構成ファイル、またはメタデータ ファイルが含まれます。コード ファイルや構成ファイルの生成時にこれを回避するには、/mergeConfig スイッチを使用します。
また、データ コントラクト生成には、型参照用の /r スイッチと /ct スイッチがあります。XmlSerializer の使用時には、これらのスイッチは機能しません。
|
メタデータを取得する場合、ツールには、5 分間のタイムアウトがあります。このタイムアウトは、ネットワーク経由でメタデータを取得する場合にのみ適用されます。タイムアウトは、そのメタデータの処理には適用されません。
Svcutil を使用して、セキュリティ トークン サービス (STS) への参照がある WSDL ドキュメントにアクセスする場合、Svcutil は WS-MetadataExchange を使用して STS を呼び出します。ただし、サービスは、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>
|
ツールによって生成される出力を指定します。
有効な値は、コード、メタデータ、または xmlSerializer です。
短縮形 : /t
|
コード生成オプション
Svcutil.exe は、メタデータ ドキュメントからサービス コントラクト、クライアント、およびデータ型のコードを生成できます。これらのメタデータ ドキュメントは、永続ストレージにあるか、オンラインで取得できます。オンライン取得は、WS-Metadata Exchange プロトコルまたは DISCO プロトコルに従います (詳細については、「メタデータのダウンロード」セクションを参照してください)。
BasicHttpContextbinding エンドポイントを使用するサービスの場合は代わりに、Svcutil.exe が、allowCookies 属性を true に設定した BasicHttpBinding を生成します。Cookie はサーバー側でのコンテキスト用に使用されます。サービスで Cookie を使用するときにクライアント側でコンテキストを管理する場合は、コンテキスト バインディングを使用するように構成を手動で変更できます。
| 注意 : |
|---|
|
Svcutil.exe は、WSDL またはサービスから受け取るポリシー ファイルに基づいてクライアントを生成します。ユーザー プリンシパル名 (UPN) は、ユーザー名、"@"、および完全修飾ドメイン名 (FQDN) を連結して生成されます。ただし、Active Directory に登録されているユーザーの場合、この形式は無効であり、ツールが生成する UPN を使用すると、Kerberos 認証でエラーが発生し、エラー メッセージ "ログインに失敗しました" が表示されます。この問題を解決するには、このツールが生成するクライアント ファイルを手動で修正する必要があります。
|
svcutil.exe [/t:code] <metadataDocumentPath>* | <url>* | <epr>
|
引数
|
説明
|
|---|
|
epr
|
WS-Metadata Exchange をサポートするサービス エンドポイントで使用する WS-Addressing EndpointReference を含む XML ファイルへのパス。詳細については、「メタデータのダウンロード」セクションを参照してください。
|
|
metadataDocumentPath
|
コード (.wsdl、.xsd、.wspolicy、または .wsmex) にインポートするためのコントラクトを含むメタデータ ドキュメント (wsdl または xsd) へのパス。
Svcutil は、メタデータにリモート URL を指定するときのインポートとインクルードに従います。ただし、ローカル ファイル システムでメタデータ ファイルを処理する場合は、この引数にすべてのファイルを指定する必要があります。この方法では 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
.gif) メモ :
スイッチは、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 サービス名、またはスキーマの 1 つのターゲット名前空間から派生します。
短縮形 : /o
|
|
/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 および以前のバージョンの機能を参照するコードを生成します。/async スイッチを指定して /tcv:Version35 を使用している場合は、イベントベースおよびコールバック/デリゲートベースの非同期メソッドが生成されます。また、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
|
メタデータのエクスポート
Svcutil.exe は、コンパイル済みアセンブリのサービス、コントラクト、およびデータ型のメタデータをエクスポートできます。サービスのメタデータをエクスポートするには、/serviceName オプションを使用して、エクスポートするサービスを指定する必要があります。アセンブリ内のすべてのデータ コントラクト型をエクスポートするには、/dataContractOnly オプションを使用する必要があります。既定では、入力アセンブリのすべてのサービス コントラクトのメタデータがエクスポートされます。
svcutil.exe [/t:metadata] [/serviceName:<serviceConfigName>] [/dataContractOnly] <assemblyPath>*
|
引数
|
説明
|
|---|
|
assemblyPath
|
エクスポートされるサービス、コントラクト、またはデータ コントラクト型を格納するアセンブリへのパスを指定します。標準のコマンド ライン ワイルドカードを使用して、複数のファイルを入力として指定できます。
|
|
オプション
|
説明
|
|---|
|
/serviceName:<serviceConfigName>
|
エクスポートされるサービスの構成名を指定します。このオプションを使用した場合、関連構成ファイルが存在する実行可能アセンブリを入力として渡す必要があります。Svcutil.exe は、すべての関連構成ファイルからサービス構成を検索します。構成ファイルが拡張型を含む場合、これらの型を含むアセンブリは GAC に存在するか、/reference オプションを使用して明示的に指定される必要があります。
|
|
/reference:<file path>
|
指定したアセンブリを、型参照の解決に使用するアセンブリの集合に追加します。サービスのエクスポートまたは検証に、構成に登録されているサードパーティ製拡張機能 (Behaviors、Bindings、および BindingElements) を使用している場合は、このオプションを使用して 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>
|
指定したアセンブリを、型参照の解決に使用するアセンブリの集合に追加します。サービスのエクスポートまたは検証に、構成に登録されているサードパーティ製拡張機能 (Behaviors、Bindings、および BindingElements) を使用している場合は、このオプションを使用して GAC に含まれていない拡張機能アセンブリを指定します。
短縮形 : /r
|
|
/dataContractOnly
|
データ コントラクト型に対してのみ機能します。サービス コントラクトは処理されません。
このオプションにはローカル メタデータ ファイルだけを指定する必要があります。
短縮形 : /dconly
|
|
/excludeType:<type>
|
検証から除外する完全修飾のまたはアセンブリ修飾の型名を指定します。
短縮形 : /et
|
メタデータのダウンロード
Svcutil.exe を使用すると、実行中のサービスからメタデータをダウンロードして、ローカル ファイルに保存できます。メタデータをダウンロードするには、/t:metadata オプションを指定する必要があります。それ以外の場合は、クライアント コードが生成されます。URL スキームが HTTP および HTTPS の場合、Svcutil.exe はメタデータの抽出に WS-Metadata Exchange および DISCO を使用します。その他の URL スキームの場合、Svcutil.exe は WS-Metadata Exchange のみを使用します。
Svcutil は、メタデータを取得するために次のメタデータ要求を同時に発行します。
-
指定されたアドレスへの MEX (WS-Transfer) 要求
-
指定されたアドレスへの /mex 付きの MEX 要求
-
指定されたアドレスへの (ASMX から DiscoveryClientProtocol を使用した) DISCO 要求
既定では、Svcutil.exe は MetadataExchangeBindings クラスに定義されているバインディングを使用して、MEX 要求を行います。WS-Metadata Exchange で使用するバインディングを構成するには、IMetadataExchange コントラクトを使用するクライアント エンドポイントを構成に定義する必要があります。これを定義できる場所は、Svcutil.exe の構成ファイルか、/svcutilConfig オプションを使用して指定された別の構成ファイルです。
svcutil.exe /t:metadata <url>* | <epr>
|
引数
|
説明
|
|---|
|
url
|
メタデータを提供するサービス エンドポイントの URL またはオンラインになっているメタデータ ドキュメントの URL。
|
|
epr
|
WS-Metadata Exchange をサポートするサービス エンドポイントの WS-Addressing EndpointReference を含む XML ファイルへのパスです。
|
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
|
既定の DataContractSerializer ではなく、XmlSerializer をエラーの読み書きに使用する必要があることを指定します。
|
例
次のコマンドにより、実行中のサービスまたはオンラインのメタデータ ドキュメントからクライアント コードが生成されます。
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 で使用しないようにする必要があります。
また、現在のプロセスにサービス拒否を引き起こす可能性があるため、アプリケーションの中間層でツールを使用しないようにする必要があります。
関連項目