サービス コントラクトの設計

  • [アーティクル]

ここでは、サービス コントラクトの概要、定義方法、使用できる操作 (および基になるメッセージ交換の影響)、使用するデータ型、およびシナリオの要件を適切に満たす操作を設計する際に役立つその他の問題について説明します。

サービス コントラクトの作成

サービスは操作のグループです。サービス コントラクトを作成するには、操作をモデル化し、操作のグループ化を指定する必要があります。Windows Communication Foundation (WCF) アプリケーションでは、メソッドを作成し、OperationContractAttribute 属性でマークすることによって操作を定義します。次に、サービス コントラクトを作成するために、ServiceContractAttribute 属性でマークされたインターフェイス内で操作を宣言するか、この属性でマークされたクラス内で操作を定義することにより、操作をグループ化します (基本的な例については、「方法 : Windows Communication Foundation サービス コントラクトを定義する」を参照してください)。

OperationContractAttribute 属性を持たないメソッドはサービス操作ではないため、WCF サービスのクライアントが使用するために公開されることはありません。マネージ メソッドと同様に、このようなメソッドを呼び出すことができるのは、宣言されたアクセス スコープ内のオブジェクトだけです。

同様に、サービス操作を宣言しないサービス コントラクト クラスまたはインターフェイスを作成することも有効です。この効果は、メソッドを持たないクラスまたはインターフェイスと同じです。この種のコントラクトを使用して構築されたサービスは、クライアントが使用するための操作を公開しません。ここでは、サービス コントラクトの設計時に決定すべき以下のポイントについて説明します。

  • クラスとインターフェイスのどちらを使用するか
  • 交換するデータ型の指定方法
  • 使用できる交換パターンの種類
  • コントラクトのセキュリティ要件の部分を明示的に作成できるかどうか
  • 操作の入力と出力の制限

クラスとインターフェイス

クラスとインターフェイスは、いずれも機能のグループ化を表します。したがって、どちらを使用しても WCF サービス コントラクトを定義できます。ただし、インターフェイスはサービス コントラクトを直接モデル化するため、インターフェイスを使用することをお勧めします。実装のないインターフェイスは、特定のシグネチャを持つメソッドのグループ化を定義しているにすぎません。同様に、実装のないサービス コントラクトは、特定のシグネチャを持つ操作のグループ化を定義しているだけとなります。サービス コントラクト インターフェイスを実装してはじめて、WCF サービスを実装したことになります。

サービス コントラクト インターフェイスには、次のようにマネージ インターフェイスのあらゆる利点がもたらされます。

  • サービス コントラクト インターフェイスでは、他のサービス コントラクト インターフェイスをいくつでも拡張できます。
  • これらのサービス コントラクト インターフェイスを実装することにより、1 つのクラスでサービス コントラクトをいくつでも実装できます。
  • インターフェイスの実装を変更することにより、同じサービス コントラクトを引き続き使用したまま、そのコントラクトの実装を変更できます。
  • 以前のインターフェイスと新しいインターフェイスを実装することで、サービスをバージョン管理できます。以前のクライアントは元のバージョンに接続し、新しいクライアントは新しいバージョンに接続できます。
ms733070.note(ja-jp,VS.90).gifメモ :
他のサービス コントラクト インターフェイスから継承した場合、操作のプロパティ (名前や名前空間など) をオーバーライドすることはできません。これを行う場合は、現在のサービス コントラクトに新しい操作を作成します。

インターフェイスを使用したサービス コントラクトの作成の例については 、「方法 : コントラクト インターフェイスを使用してサービスを作成する」を参照してください。

クラスを使用すると、サービス コントラクトの定義と実装を一度に行うことができます。ServiceContractAttribute と OperationContractAttribute をそれぞれクラスとクラスのメソッドに直接適用してサービスを作成する方法には、サービスを迅速かつ簡単に作成できるという利点があります。欠点は、マネージ クラスでは複数の継承をサポートしていないため、サービス コントラクトを一度に 1 つしか実装できないことです。また、クラスまたはメソッド シグネチャに変更を加えると、そのサービスのパブリック コントラクトが変更されるため、変更されていないクライアントがサービスを使用できなくなることがあります。詳細な情報については、次のページを参照してください。 「サービス コントラクトの実装」を参照してください。

クラスを使用してサービス コントラクトの作成と実装を一度に行う例については、「方法 : クラスを使用して Windows Communication Foundation コントラクトを作成する」を参照してください。

これで、サービス コントラクトを定義する際に、インターフェイスを使用した場合とクラスを使用した場合の違いがわかりました。次に、サービスとクライアント間で受け渡しできるデータを決定します。

パラメータと戻り値

各操作は戻り値とパラメータを持ちます (戻り値とパラメータが void の場合も含まれます)。ただし、オブジェクトへの参照をオブジェクト間で渡すことができるローカル メソッドとは異なり、サービス操作ではオブジェクトへの参照を渡しません。代わりに、オブジェクトのコピーを渡します。

これが重要なのは、パラメータまたは戻り値で使用される各型がシリアル化可能でなければならないためです。つまり、その型のオブジェクトをバイト ストリームに変換でき、バイト ストリームからオブジェクトに変換できる必要があります。

プリミティブ型は既定でシリアル化可能であり、.NET Framework の多くの型も同様です。

ms733070.note(ja-jp,VS.90).gifメモ :
操作シグネチャのパラメータ名の値はコントラクトに含まれ、大文字と小文字が区別されます。ローカルでは同じパラメータ名を使用するが、公開されるメタデータでは名前を変更する場合は、System.ServiceModel.MessageParameterAttribute を参照してください。

データ コントラクト

Windows Communication Foundation (WCF) アプリケーションのようなサービス指向アプリケーションは、マイクロソフトとマイクロソフト以外の両方のプラットフォームで、できる限り多くのクライアント アプリケーションと相互運用できるように設計されています。最大限の相互運用性を実現するために、使用する型を DataContractAttribute 属性と DataMemberAttribute 属性でマークして、データ コントラクトを作成することをお勧めします。データ コントラクトは、サービス コントラクトの一部であり、サービス操作で交換するデータを記述したものです。

データ コントラクトは opt-in 方式のコントラクトです。つまり、データ コントラクト属性を明示的に適用しない限り、型またはデータ メンバはシリアル化されません。データ コントラクトはマネージ コードのアクセス スコープとして関連付けられていません。プライベートのデータ メンバはシリアル化され、パブリックにアクセスされる他の場所に送信されます。(データ コントラクトの基本的な例については、「方法 : クラスまたは構造体に基本的なデータ コントラクトを作成する」を参照してください)。WCF は、基になる SOAP メッセージの定義を処理します。このメッセージにより、操作の機能が有効になるだけでなく、データ型とメッセージ本文との間での双方向のシリアル化が可能になります。使用するデータ型がシリアル化可能であれば、操作の設計時に、基盤となるメッセージ交換インフラストラクチャについて考える必要はありません。

通常の WCF アプリケーションは DataContractAttribute 属性および DataMemberAttribute 属性を使用して操作のデータ コントラクトを作成しますが、他のシリアル化機構を使用することもできます。ISerializable、SerializableAttribute、および IXmlSerializable の各標準機構はすべて、基になる SOAP メッセージへのデータ型のシリアル化を処理します。このメッセージはアプリケーション間でデータ型を伝達します。使用するデータ型で特別なサポートが必要な場合は、さらに多くのシリアル化方法を使用できます。WCF アプリケーションでデータ型をシリアル化する際の選択肢詳細については、 、「サービス コントラクトでのデータ転送の指定」を参照してください。

サービス コントラクトとその操作の定義内の CLR 名は重要であるため、混同しないようにすることが大切です。サービス コントラクトの定義に使用する型を混合しないようにするには、ObfuscationAttribute 属性と ObfuscateAssemblyAttribute 属性を使用します。

メッセージ交換へのパラメータと戻り値のマッピング

サービス操作は、特定の標準セキュリティ、トランザクション、およびセッション関連の機能をサポートするためにアプリケーションが必要とするデータに加え、アプリケーション データをやり取りする SOAP メッセージの基になる交換によってサポートされます。このため、サービス操作のシグネチャでは、データ転送と操作に必要な機能をサポートできる、基になるメッセージ交換パターン (MEP: Message Exchange Pattern) を指定します**。WCF プログラミング モデルでは、要求/応答、一方向、および双方向の 3 つのメッセージ パターンを指定できます。

要求/応答

要求/応答パターンでは、要求の送信側 (クライアント アプリケーション) は、その要求に関連付けられた応答を受信します。このパターンでは、1 つの操作において、1 つ以上のパラメータを操作に渡し、操作から戻り値と 1 つ以上の出力値を呼び出し元に返すことができるため、このパターンが既定の MEP となります。たとえば、次の C# コード例は、文字列を 1 つ受け取り、文字列を返す基本的なサービス操作を示しています。

[OperationContractAttribute]
string Hello(string greeting);

次のコードは同等の Visual Basic コードです。

<OperationContractAttribute()>
Function Hello (ByVal greeting As String) As String

この操作シグネチャは、基になるメッセージ交換の形式を指定しています。相関関係がない場合、WCF は戻り値の対象となる操作を特定できません。

別の基になるメッセージ パターンを指定しない限り、void (Visual Basic では Nothing) を返すサービス操作も要求/応答メッセージ交換です。クライアントが操作を非同期で呼び出していない場合、通常、メッセージが空の場合でも、戻りメッセージを受信するまでクライアントは処理を中止します。クライアントが応答で空のメッセージを受信するまで制御が戻らない操作の C# コード例を次に示します。

[OperationContractAttribute]
void Hello(string greeting);

次のコードは同等の Visual Basic コードです。

<OperationContractAttribute()>
Sub Hello (ByVal greeting As String)

上記の例では、実行に時間のかかる操作の場合に、クライアントのパフォーマンスと応答性が低下するおそれがありますが、要求/応答操作で void を返す場合でも、この操作には利点があります。最も明らかな利点は、応答メッセージで SOAP エラーを返すことが可能であるということです。これにより、通信と処理のどちらで発生したかに関係なく、サービス関連の何らかのエラー状態が発生したことがわかります。サービス コントラクトに指定された SOAP エラーは、FaultException オブジェクトとしてクライアント アプリケーションに渡されます。このオブジェクトの型パラメータは、サービス コントラクトで指定された型です。これにより、WCF サービスのエラー状態について、クライアントに簡単に通知できるようになります。例外、SOAP エラー、およびエラー処理詳細については、 、「コントラクトおよびサービスのエラーの指定と処理」を参照してください。要求/応答サービスおよびクライアントの例については、「方法 : 要求/応答コントラクトを作成する」を参照してください。要求/応答パターンに関する問題詳細については、 、「要求/応答サービス」を参照してください。

一方向

WCF サービス アプリケーションのクライアントが操作の完了まで待機する必要がなく、SOAP エラーも処理しない場合は、操作で一方向メッセージ パターンを指定できます。一方向操作では、クライアントが操作を呼び出し、WCF がメッセージをネットワークに書き込んだら、クライアントは処理を続行できます。通常、これは、送信メッセージで送信するデータが膨大な量でない限り、(データ送信時にエラーが発生しなければ) クライアントはほぼすぐに実行を続けることを意味します。この種のメッセージ交換パターンでは、クライアントからサービス アプリケーションへのイベントのような動作をサポートします。

1 つのメッセージを送信し、何も受信しないメッセージ交換では、void 以外の戻り値を指定したサービス操作をサポートすることはできません。この場合、InvalidOperationException 例外がスローされます。

戻りメッセージがないということは、処理または通信時のエラーを示すために SOAP エラーを返すこともできないということです (操作が一方向操作の場合にエラー情報を伝達するには、双方向メッセージ交換パターンが必要です)。

void を返す操作で一方向メッセージ交換を指定するには、次の C# コード例に示すように、IsOneWay プロパティを true に設定します。

[OperationContractAttribute(IsOneWay=true)]
void Hello(string greeting);

次のコードは同等の Visual Basic コードです。

<OperationContractAttribute(IsOneWay := True)>
Sub Hello (ByVal greeting As String)

このメソッドは、前述の要求/応答の例と同じです。ただし、IsOneWay プロパティを true に設定するということは、メソッドは同じでも、サービス操作は戻りメッセージを送信せず、送信メッセージがチャネル レイヤに渡されると、すぐにクライアントに制御が戻ることを意味します。例については、「方法 : 一方向コントラクトを作成する」を参照してください。一方向パターン詳細については、 、「一方向サービス」を参照してください。

双方向

双方向パターンの特徴は、一方向メッセージングと要求/応答メッセージングのどちらを使用しているかに関係なく、サービスとクライアントが共に独立して、相互にメッセージを送信できるという点です。二方向通信のこの形式は、サービスがクライアントと直接通信する必要がある場合や、イベントのような動作など、メッセージを交換するどちらの側も非同期で動作できるようにする場合に役立ちます。

双方向パターンでは、クライアントと通信するための機構が別途必要になるため、要求/応答パターンや一方向パターンに比べると若干複雑になります。

双方向コントラクトを設計する場合、コールバック コントラクトも設計し、そのコールバック コントラクトの型を、サービス コントラクトをマークする ServiceContractAttribute 属性の CallbackContract プロパティに割り当てる必要があります。

双方向パターンを実装するには、クライアントで呼び出されるメソッド宣言を含む 2 つ目のインターフェイスを作成する必要があります。

サービス、およびそのサービスにアクセスするクライアントの作成方法の例については 、「方法 : 双方向コントラクトを作成する」および「方法 : 双方向コントラクトを使用してサービスにアクセスする」を参照してください。実際に動作するサンプルについては、「Service Contract: Duplex」を参照してください。双方向コントラクトの使用に関する問題詳細については、 、「双方向サービス」を参照してください。

ms733070.Caution(ja-jp,VS.90).gif注意 :
サービスは、双方向メッセージを受信すると、その受信メッセージの ReplyTo 要素を参照して応答の送信先を決定します。メッセージの受信に使用するチャネルがセキュリティで保護されていない場合、信頼関係のないクライアントが対象コンピュータの ReplyTo を使用して悪意のあるメッセージを送信し、その対象コンピュータのサービス拒否 (DOS: Denial Of Service) を引き起こすおそれがあります。

Out パラメータと Ref パラメータ

ほとんどの場合、in パラメータ (Visual Basic では ByVal) および out パラメータと ref パラメータ (Visual Basic では ByRef) を使用できます。out パラメータと ref パラメータは、操作からデータが返されることを示すため、操作シグネチャが void を返す場合でも、次のような操作シグネチャによって要求/応答操作が必要であることを指定します。

[ServiceContractAttribute]
public interface IMyContract
{
  [OperationContractAttribute]
  public void PopulateData(ref CustomDataType data);
}

次のコードは同等の Visual Basic コードです。

[Visual Basic]

<ServiceContractAttribute()> _
Public Interface IMyContract
  <OperationContractAttribute()> _
  Public Sub PopulateData(ByRef data As CustomDataType)
End Interface

唯一の例外は、シグネチャに特定の構造体が含まれている場合です。たとえば、NetMsmqBinding バインディングを使用してクライアントと通信できるのは、操作の宣言に使用されたメソッドが void を返す場合だけです。戻り値、ref パラメータ、または out パラメータのいずれであるかに関係なく、出力値を指定することはできません。

また、out パラメータまたは ref パラメータを使用する場合、操作には基になる応答メッセージが必要です。このメッセージが変更されたオブジェクトを返します。操作が一方向操作の場合、実行時に InvalidOperationException 例外がスローされます。

コントラクトでのメッセージ保護レベルの指定

コントラクトの設計時に、コントラクトを実装するサービスのメッセージ保護レベルも決定する必要があります。これは、メッセージ セキュリティをコントラクトのエンドポイントのバインディングに適用する場合にのみ必要です。バインディングのセキュリティが無効になっている場合 (つまり、システム指定のバインディングで System.ServiceModel.SecurityMode の値が System.ServiceModel.SecurityMode.None に設定されている場合)、コントラクトのメッセージ保護レベルを決定する必要はありません。ほとんどの場合、メッセージ レベルのセキュリティが適用されたシステム指定のバインディングは、十分な保護レベルを備えているため、操作ごとまたはメッセージごとに保護レベルを検討する必要はありません。

保護レベルは、サービスをサポートするメッセージ (またはメッセージ部分) が署名されるのか、署名および暗号化されるのか、または署名と暗号化なしで送信されるのかを指定する値です。保護レベルは、さまざまなスコープ (サービス レベル、特定の操作、その操作内のメッセージ、またはメッセージ部分) で設定できます。あるスコープで設定された値は、明示的にオーバーライドしない限り、そのスコープよりも小さなスコープの既定値になります。コントラクトに必要とされる最小限の保護レベルをバインディング構成で提供できない場合は、例外がスローされます。保護レベルの値がコントラクトで明示的に設定されていない場合、バインディングのメッセージ セキュリティが有効であれば、バインディング構成によってすべてのメッセージの保護レベルが制御されます。これが既定の動作です。

ms733070.Important(ja-jp,VS.90).gif メモ :
一般に、コントラクトのさまざまなスコープを完全な保護レベルである System.Net.Security.ProtectionLevel.EncryptAndSign よりも下のレベルに明示的に設定するかどうかは、パフォーマンスの向上と引き換えに、ある程度のセキュリティで妥協できるかどうかという判断によって決まります。このような場合、操作および操作で交換するデータの価値に焦点を絞って判断を下す必要があります。詳細な情報については、次のページを参照してください。 「サービスのセキュリティ保護」を参照してください。

たとえば、次のコード例では、ProtectionLevel も、コントラクトの ProtectionLevel プロパティも設定していません。

[ServiceContract]
public interface ISampleService
{
  [OperationContractAttribute]
  public string GetString();

  [OperationContractAttribute]
  public int GetInt();  
}

次のコードは同等の Visual Basic コードです。

[Visual Basic]

<ServiceContractAttribute()> _
Public Interface ISampleService

  <OperationContractAttribute()> _
  Public Function GetString()As String

  <OperationContractAttribute()> _
  Public Function GetData() As Integer

End Interface

既定の WSHttpBinding (既定の System.ServiceModel.SecurityMode は Message) を使用するエンドポイントの ISampleService 実装とやり取りする場合は、暗号化と署名が既定の保護レベルであるため、すべてのメッセージが暗号化および署名されます。ただし、既定の BasicHttpBinding (既定の SecurityMode は None) を使用して ISampleService サービスを使用すると、すべてのメッセージがテキストとして送信されます。これは、このバインディングにはセキュリティがないため、保護レベルが無視されるためです (つまり、メッセージの暗号化も署名も行われません)。SecurityMode を Message に変更すると、これがこのバインディングの既定の保護レベルになるため、これらのメッセージは暗号化および署名されるようになります。

コントラクトの保護要件を明示的に指定または調整する場合は、ProtectionLevel プロパティ (またはより小さなスコープの ProtectionLevel プロパティのいずれか) をサービス コントラクトに必要なレベルに設定します。この場合、明示的な設定を使用するには、使用するスコープに少なくともその設定をサポートするバインディングが必要です。たとえば、次のコード例では、GetGuid 操作の ProtectionLevel の値を明示的に指定しています。

[C#]

[ServiceContract]
public interface IExplicitProtectionLevelSampleService
{
  [OperationContractAttribute]
  public string GetString();

  [OperationContractAttribute(ProtectionLevel=ProtectionLevel.None)]
  public int GetInt();  
  [OperationContractAttribute(ProtectionLevel=ProtectionLevel.EncryptAndSign)]
  public int GetGuid();  
}

次のコードは同等の Visual Basic コードです。

[Visual Basic]

<ServiceContract()> _ 
Public Interface IExplicitProtectionLevelSampleService 
    <OperationContract()> _ 
    Public Function GetString() As String 
    End Function 

    <OperationContract(ProtectionLevel := ProtectionLevel.None)> _ 
    Public Function GetInt() As Integer 
    End Function 

    <OperationContractAttribute(ProtectionLevel := ProtectionLevel.EncryptAndSign)> _ 
    Public Function GetGuid() As Integer 
    End Function 

End Interface

この IExplicitProtectionLevelSampleService コントラクトを実装し、既定の WSHttpBinding (既定の System.ServiceModel.SecurityMode は Message) を使用するエンドポイントを持つサービスの動作は次のようになります。

  • GetString 操作のメッセージは、暗号化および署名されます。
  • GetInt 操作のメッセージは、暗号化も署名もされない (プレーン) テキストとして送信されます。
  • GetGuid 操作の System.Guid は、暗号化および署名されたメッセージで返されます。

保護レベルとその使用方法詳細については、 、「保護レベルの理解」を参照してください。セキュリティ詳細については、 、「サービスのセキュリティ保護」を参照してください。

操作シグネチャのその他の要件

アプリケーションの一部の機能では、特定の種類の操作シグネチャを必要とします。たとえば、NetMsmqBinding バインディングは、永続的なサービスとクライアントをサポートします。永続的なサービスとクライアントでは、通信の途中でアプリケーションを再起動し、メッセージを失うことなく、アプリケーションが中止された場所を検出できます (詳細な情報については、次のページを参照してください。 「Windows Communication Foundation のキュー」を参照してください)。ただし、永続的操作では、in パラメータを 1 つしか受け取ることができず、戻り値を持つこともできません。

もう 1 つの例として、操作における Stream 型の使用が挙げられます。Stream パラメータにはメッセージの本文全体が含まれるため、入力または出力 (つまり、ref パラメータ、out パラメータ、または戻り値) が Stream 型である場合、操作で指定された入力または出力に限定する必要があります。また、パラメータまたは戻り値の型は Stream、System.ServiceModel.Channels.Message、または System.Xml.Serialization.IXmlSerializable のいずれかである必要があります。ストリーム詳細については、 、「大規模データとストリーミング」を参照してください。

名前、名前空間、および隠ぺい

コントラクトおよび操作の定義内の .NET 型の名前や名前空間は、コントラクトが WSDL に変換されるとき、およびコントラクト メッセージが作成および送信されるときに重要になります。したがって、サービス コントラクトの名前と名前空間は、ServiceContractAttribute、OperationContractAttribute、DataContractAttribute、DataMemberAttribute などの、すべてのサポート対象コントラクト属性や、他のコントラクト属性の Name プロパティと Namespace プロパティを使用して明示的に設定することを強くお勧めします。

この 1 つの結果として、名前と名前空間が明示的に設定されていない場合、アセンブリで IL 隠ぺいを使用すると、コントラクトの型名と名前空間が変更され、その結果、WSDL が変更され、通常はネットワークでのメッセージ交換に失敗します。コントラクトの名前と名前空間を明示的に設定せずに隠ぺいを使用する場合は、ObfuscationAttribute 属性と ObfuscateAssemblyAttribute 属性を使用して、コントラクトの型名と名前空間が変更されないようにします。

関連項目

タスク

方法 : 要求/応答コントラクトを作成する
方法 : 一方向コントラクトを作成する
方法 : 双方向コントラクトを作成する

概念

サービス コントラクトでのデータ転送の指定
コントラクトおよびサービスのエラーの指定と処理
セッションの使用
同期操作と非同期操作
信頼できるサービス
サービスとトランザクション