ServiceModel メタデータ ユーティリティ ツール (Svcutil.exe)

ServiceModel メタデータ ユーティリティ ツールを使用して、メタデータ ドキュメントからサービス モデル コードを生成し、サービス モデル コードからメタデータ ドキュメントを生成します。

SvcUtil.exe

ServiceModel メタデータ ユーティリティ ツールは、Windows SDK のインストール場所である %ProgramFiles%\Microsoft SDKs\Windows\v6.0\Bin にあります。

機能

次の表では、このツールによって提供されるさまざまな機能とその使用方法を説明する対応トピックをまとめています。

タイムアウト

メタデータを取得する場合、ツールには、5 分間のタイムアウトがあります。 このタイムアウトは、ネットワーク経由でメタデータを取得する場合にのみ適用されます。 タイムアウトは、そのメタデータの処理には適用されません。

マルチターゲット

このツールは複数バージョン対応機能をサポートしていません。 svcutil.exe から .NET Framework 4 の成果物を生成する場合は、.NET Framework 4 SDK の svcutil.exe を使用します。 .NET Framework 3.5 の成果物を生成するには、.NET Framework 3.5 SDK の実行可能ファイルを使用します。

WSDL ドキュメントへのアクセス

Svcutil を使用して、セキュリティ トークン サービス (STS) への参照がある WSDL ドキュメントにアクセスする場合、Svcutil は WS-MetadataExchange を使用して STS を呼び出します。 ただし、サービスは、WS-MetadataExchange または HTTP GET を使用して WSDL ドキュメントを公開できます。 そのため、STS が HTTP GET のみを使用して WSDL ドキュメントを公開している場合、WinFX で作成されたクライアントは失敗します。 .NET Framework 3.5 で作成されたクライアントの場合、Svcutil では、WS-MetadataExchange と HTTP GET の両方を使用して、STS WSDL の取得を試みます。

SvcUtil.exe の使用

一般的な使用

次の表は、このツールで一般的に使用されるオプションを示しています。

コード生成

Svcutil.exe は、メタデータ ドキュメントからサービス コントラクト、クライアント、およびデータ型のコードを生成できます。 これらのメタデータ ドキュメントは、永続ストレージにあるか、オンラインで取得できます。 オンライン取得は、WS-Metadata Exchange プロトコルまたは DISCO プロトコルに従います (詳細については、「メタデータのダウンロード」セクションを参照してください)。

定義済みの WSDL ドキュメントに基づいてサービスとデータ コントラクトを生成するために SvcUtil.exe ツールを使用できます。 /serviceContract スイッチを使用し、WSDL ドキュメントをダウンロードできるか見つけることができる URL またはファイルの場所を指定します。 こうすると、WSDL ドキュメントで定義されているサービスとデータ コントラクトが生成され、準拠サービスの実装に使用できます。 詳細については、「方法: メタデータの取得および準拠サービスの実装をする」を参照してください。

BasicHttpContextBinding エンドポイントを使用するサービスの場合は代わりに、Svcutil.exe によって、allowCookies 属性が true に設定された BasicHttpBinding が生成されます。 クッキーはサーバー側でのコンテキスト用に使用されます。 サービスでクッキーを使用するときにクライアント側でコンテキストを管理する場合は、コンテキスト バインディングを使用するように構成を手動で変更できます。

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

メタデータのエクスポート

Svcutil.exe は、コンパイル済みアセンブリのサービス、コントラクト、およびデータ型のメタデータをエクスポートできます。 サービスのメタデータをエクスポートするには、/serviceName オプションを使用して、エクスポートするサービスを指定する必要があります。 アセンブリ内のすべてのデータ コントラクト型をエクスポートするには、/dataContractOnly オプションを使用する必要があります。 既定では、入力アセンブリのすべてのサービス コントラクトのメタデータがエクスポートされます。

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

サービスの検証

検証は、サービスをホストせずにサービス実装でエラーを検出するために使用できます。 /serviceName オプションを使用して、検証するサービスを指定する必要があります。

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

メタデータのダウンロード

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>

XmlSerializer 型の生成

XmlSerializer を使用してシリアル化できるデータ型を使用するサービスおよびクライアント アプリケーションは、実行時にこのようなデータ型のシリアル化コードを生成およびコンパイルします。このため、起動時のパフォーマンスが低下することがあります。

Svcutil.exe は、必要な C# シリアル化コードをアプリケーションのコンパイル済みアセンブリから生成できるため、このようなアプリケーションの起動時のパフォーマンスが改善されます。 詳細については、「方法: XmlSerializer を使用する WCF クライアント アプリケーションの起動時間を短縮する」を参照してください。

svcutil.exe /t:xmlSerializer <assemblyPath>*

例

次のコマンドにより、実行中のサービスまたはオンラインのメタデータ ドキュメントからクライアント コードが生成されます。

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

最大 Nametable 文字数のクォータ

svcutil を使用してサービスのメタデータを生成する場合、次のメッセージが表示されます。

エラー: http://localhost:8000/somesservice/mex からメタデータを取得できません。XML データの読み取り中に、最大 nametable 文字数のクォータ (16384) を超えました。 nametable は、XML 処理時に検出された文字列を格納するためのデータ構造です。反復されない要素名、属性名、および属性値が含まれた長い XML ドキュメントによってこのクォータがトリガーされることがあります。 このクォータを増やすには、XML リーダーの作成時に使用される XmlDictionaryReaderQuotas オブジェクトの MaxNameTableCharCount プロパティを変更してください。

このエラーの原因は、メタデータの要求時に大きな WSDL ファイルを返すサービスである可能性があります。 その結果、svcutil.exe ツールの文字のクォータを超えることになります。 この値は、サービス拒否 (dos) 攻撃を防止するために設定されています。 このクォータは、次の svcutil の構成ファイルを指定して増やすことができます。

次の構成ファイルは、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 のコード例をこのファイルにコピーします。 svcutil.exe と同じディレクトリにファイルを配置します。 次回 svcutil.exe が実行されると、新しい設定が適用されます。

セキュリティに関する注意事項

適切なアクセス制御リスト (ACL) を使用して、Svcutil.exe のインストール フォルダー、Svcutil.config、および /svcutilConfig によって示されるファイルを保護する必要があります。 これによって、悪質な拡張機能が登録されて実行されるのを防ぐことができます。

さらに、セキュリティの侵害を最小限に抑えるために、信頼できない拡張機能をシステムの一部として追加したり、信頼できないコード プロバイダーを Svcutil.exe で使用したりしないようにする必要があります。

また、現在のプロセスにサービス拒否を引き起こす可能性があるため、アプリケーションの中間層でツールを使用しないようにする必要があります。

関連項目

• DataContractAttribute
• DataMemberAttribute
• 方法: クライアントを作成する