メッセージコントラクトの使用

一般に、Windows Communication Foundation (WCF) アプリケーションを構築するときに、開発者はデータ構造とシリアル化の問題には細心の注意を払いますが、データを送信するメッセージ構造について懸念する必要はありません。このようなアプリケーションでは、パラメーターまたは戻り値用にデータコントラクトを作成するのは簡単です (詳細については、「サービスコントラクトでのデータ転送の指定」を参照してください。)

ただし、SOAP メッセージの構造を完全に制御することがメッセージの内容の制御と同様に重要となる場合があります。これが特に当てはまるのは、相互運用性が重要である場合、具体的にはメッセージまたはメッセージ部分のレベルでセキュリティの問題を制御する場合です。このような場合、必要とされる正確な SOAP メッセージの構造を指定できる、"メッセージコントラクト" を作成できます。

ここでは、メッセージコントラクトの各種属性を使用して、ユーザー操作に専用のメッセージコントラクトを作成する方法について説明します。

処理におけるメッセージコントラクトの使用

WCF では、"リモートプロシージャコール (RPC: Remote Procedure Call) スタイル"、または "メッセージングスタイル" でモデル化された操作がサポートされます。 RPC スタイルの操作では、シリアル化可能な任意の型を使用できます。複数のパラメーター、ref パラメーターと out パラメーターなど、ローカル呼び出しで使用できる機能を利用できます。このスタイルでは、選択したシリアル化の形式によって基になるメッセージのデータ構造が制御されます。また、操作をサポートするために、メッセージは WCF ランタイムによって作成されます。これにより、SOAP や SOAP メッセージに不慣れな開発者でも、サービスアプリケーションを迅速かつ容易に作成し、使用できます。

RPC スタイルでモデル化されたサービス操作のコード例を次に示します。

[OperationContract]
public BankingTransactionResponse PostBankingTransaction(BankingTransaction bt);

通常は、データコントラクトだけでメッセージのスキーマを定義することができます。たとえば、前の例では、BankingTransaction と BankingTransactionResponse にデータコントラクトがあれば、ほとんどのアプリケーションで基になる SOAP メッセージの内容を定義できます。データコントラクトの詳細については、「データコントラクトの使用」を参照してください。

ただし、場合によっては、SOAP メッセージの構造がネットワーク経由でどのように転送されるかを厳密に制御する必要があります。最も一般的なシナリオは、カスタム SOAP ヘッダーの挿入です。もう 1 つの一般的なシナリオは、メッセージのヘッダーと本文のセキュリティプロパティを定義すること、つまり、これらの要素にデジタル署名し、要素を暗号化するかどうかを決定することです。最後に、一部のサードパーティの SOAP スタックでは、メッセージが特定の形式である必要があります。この制御は、メッセージングスタイルの操作によって行うことができます。

メッセージングスタイルの操作には、最大で 1 つのパラメーターと 1 つの戻り値があります。これらはいずれもメッセージ型です。つまり、パラメーターと戻り値は、指定された SOAP メッセージ構造に直接シリアル化されます。これは、MessageContractAttribute 型、または Message 型としてマークされた任意の型を使用できます。次のコード例は前の RPC スタイルと同様の操作を示していますが、この例ではメッセージングスタイルを使用しています。

たとえば、BankingTransaction と BankingTransactionResponse がいずれもメッセージコントラクト型である場合、次の操作のコードは有効です。

[OperationContract]
BankingTransactionResponse Process(BankingTransaction bt);
[OperationContract]
void Store(BankingTransaction bt);
[OperationContract]
BankingTransactionResponse GetResponse();

ただし、次のコードは無効です。

[OperationContract]
bool Validate(BankingTransaction bt);
// Invalid, the return type is not a message contract.
[OperationContract]
void Reconcile(BankingTransaction bt1, BankingTransaction bt2);
// Invalid, there is more than one parameter.

メッセージコントラクト型を含む操作で、有効なパターン (模式) に従わないすべての場合に例外がスローされます。もちろん、メッセージコントラクト型を含まない処理にはこのような制限はありません。

1 つの型にメッセージコントラクトとデータコントラクトの両方が含まれる場合は、処理でその型が使用されたときにはメッセージコントラクトだけが考慮されます。

メッセージコントラクトの定義

型のメッセージコントラクトを定義する (つまり、型と SOAP エンベロープ間のマッピングを定義する) には、MessageContractAttribute を型に適用します。次に、SOAP ヘッダーにする型のメンバーに MessageHeaderAttribute を適用し、メッセージの SOAP 本文の一部にするメンバーに MessageBodyMemberAttribute を適用します。

メッセージコントラクトの使用例を次のコードに示します。

[MessageContract]
public class BankingTransaction
{
  [MessageHeader] public Operation operation;
  [MessageHeader] public DateTime transactionDate;
  [MessageBodyMember] private Account sourceAccount;
  [MessageBodyMember] private Account targetAccount;
  [MessageBodyMember] public int amount;
}

この型を操作パラメーターとして使用すると、次の SOAP エンベロープが生成されます。

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <h:operation xmlns:h="http://tempuri.org/" xmlns="http://tempuri.org/">Deposit</h:operation>
    <h:transactionDate xmlns:h="http://tempuri.org/" xmlns="http://tempuri.org/">2012-02-16T16:10:00</h:transactionDate>
  </s:Header>
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <BankingTransaction xmlns="http://tempuri.org/">
      <amount>0</amount>
      <sourceAccount xsi:nil="true"/>
      <targetAccount xsi:nil="true"/>
    </BankingTransaction>
  </s:Body>
</s:Envelope>

operationとtransactionDateは SOAP ヘッダーとして表示され、SOAP 本文は、BankingTransaction、sourceAccount、およびtargetAccountを含むラッパー要素amountで構成されていることに注意してください。

パブリック、プライベート、保護、または内部のいずれであるかに関係なく、MessageHeaderAttribute と MessageBodyMemberAttribute は、すべてのフィールド、プロパティ、およびイベントに適用できます。

MessageContractAttribute を使用すると、SOAP メッセージの本文のラッパー要素の名前を制御する WrapperName および WrapperNamespace 属性を指定できます。既定では、メッセージコントラクト型の名前はラッパー用に使用され、メッセージコントラクトが定義されている名前空間 (http://tempuri.org/) は既定の名前空間として使用されます。

注

KnownTypeAttribute 属性は、メッセージコントラクトでは無視されます。 KnownTypeAttribute が必要な場合は、対象のメッセージコントラクトを使用している処理でそれを設定します。

ヘッダー名、本文名、および名前空間の制御

メッセージコントラクトの SOAP 表現では、各ヘッダーと本文の各部分が名前と名前空間を持つ XML 要素にマップされます。

既定では、名前空間はメッセージが参加しているサービスコントラクトの名前空間と同じであり、その名前は MessageHeaderAttribute 属性または MessageBodyMemberAttribute 属性が割り当てられたメンバー名によって決定されます。

(MessageContractMemberAttribute.Name 属性と MessageContractMemberAttribute.Namespace 属性の親クラスの) MessageHeaderAttribute および MessageBodyMemberAttribute を操作することによって、これらの既定値を変更できます。

次のコード例のクラスについて考えてみます。

[MessageContract]
public class BankingTransaction
{
  [MessageHeader] public Operation operation;
  [MessageHeader(Namespace="http://schemas.contoso.com/auditing/2005")] public bool IsAudited;
  [MessageBodyMember(Name="transactionData")] public BankingTransactionData theData;
}

この例では、IsAudited ヘッダーがコードで指定された名前空間に存在し、theData メンバーを表す本文が transactionData という名前の XML 要素によって表現されます。次に、このメッセージコントラクト用に生成された XML を示します。

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <h:IsAudited xmlns:h="http://schemas.contoso.com/auditing/2005" xmlns="http://schemas.contoso.com/auditing/2005">false</h:IsAudited>
    <h:operation xmlns:h="http://tempuri.org/" xmlns="http://tempuri.org/">Deposit</h:operation>
  </s:Header>
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <AuditedBankingTransaction xmlns="http://tempuri.org/">
      <transactionData/>
    </AuditedBankingTransaction>
  </s:Body>
</s:Envelope>

SOAP 本文のパーツをラップするかどうかの制御

SOAP 本文は、デフォルトでラップ要素内にシリアル化されます。たとえば、HelloGreetingMessage メッセージのメッセージコントラクトに含まれる MessageContractAttribute 型の名前から生成される HelloGreetingMessage ラッパー要素を次のコードに示します。

[MessageContract]
public class HelloGreetingMessage
{
  private string localGreeting;

  [MessageBodyMember(
    Name = "Salutations",
    Namespace = "http://www.examples.com"
  )]
  public string Greeting
  {
    get { return localGreeting; }
    set { localGreeting = value; }
  }
}

/*
 The following is the request message, edited for clarity.

  <s:Envelope>
    <s:Header>
      <!-- Note: Some header content has been removed for clarity.
      <a:Action>http://GreetingMessage/Action</a:Action>
      <a:To s:mustUnderstand="1"></a:To>
    </s:Header>
    <s:Body u:Id="_0" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
      <HelloGreetingMessage xmlns="Microsoft.WCF.Documentation">
        <Salutations xmlns="http://www.examples.com">Hello.</Salutations>
      </HelloGreetingMessage>
    </s:Body>
 </s:Envelope>
 */

<MessageContract> _
Public Class HelloGreetingMessage
    Private localGreeting As String

    <MessageBodyMember(Name:="Salutations", Namespace:="http://www.examples.com")> _
    Public Property Greeting() As String
        Get
            Return localGreeting
        End Get
        Set(ByVal value As String)
            localGreeting = value
        End Set
    End Property
End Class

'  
'   The following is the request message, edited for clarity.
'    
'    <s:Envelope>
'      <s:Header>
'        <!-- Note: Some header content has been removed for clarity.
'        <a:Action>http://GreetingMessage/Action</a:Action> 
'        <a:To s:mustUnderstand="1"></a:To>
'      </s:Header>
'      <s:Body u:Id="_0" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
'        <HelloGreetingMessage xmlns="Microsoft.WCF.Documentation">
'          <Salutations xmlns="http://www.examples.com">Hello.</Salutations>
'      </s:Body>
'   </s:Envelope>
'

ラッパー要素を抑制するには、IsWrapped プロパティを false に設定します。ラッパー要素の名前と名前空間を制御するには、WrapperName プロパティと WrapperNamespace プロパティを使用します。

注

ラップされていないメッセージにメッセージ本文の複数の部分を含めることは、WS-I Basic Profile 1.1 規格に反するため、新しいメッセージコントラクトを設計する場合はお勧めできません。ただし、特定の相互運用シナリオでは、複数のラップされていないメッセージ本文が必要な場合もあります。 1 つのメッセージ本文で複数のデータを転送する場合は、既定の (ラップされた) モードを使用することをお勧めします。ラップされていないメッセージで複数のメッセージヘッダーを使用しても、何の問題もありません。

メッセージコントラクト内部でのカスタム型の使用

メッセージが使用されるサービスコントラクト用に選択されたシリアル化エンジンを使用して、個々のメッセージヘッダーとメッセージ本文がシリアル化されます (XML に変換されます)。既定のシリアル化エンジンである XmlFormatter は、データコントラクトを持つ任意の型を (System.Runtime.Serialization.DataContractAttribute を持つことによって) 明示的に処理することも、(プリミティブ型にしたり、System.SerializableAttribute を持ったりすることなどによって) 暗黙的に処理することもできます。詳細については、「データコントラクトの使用」を参照してください。

前の例では、Operation 型と BankingTransactionData 型は、データコントラクトを持つ必要があります。また、transactionDate がプリミティブである (したがって、暗黙のデータコントラクトを持つ) ため、DateTime はシリアル化可能です。

ただし、別のシリアル化エンジンである XmlSerializer に切り替えることができます。このような切り替えを行う場合は、メッセージヘッダーと本文の各部分に使用されているすべての型が XmlSerializer を使用してシリアル化可能であることを確認する必要があります。

メッセージコントラクト内部での配列の使用

メッセージコントラクトでは、反復要素の配列を 2 とおりの方法で使用できます。

最初の方法は、配列上で MessageHeaderAttribute または MessageBodyMemberAttribute を直接使用する方法です。この場合は、配列全体が複数の子要素を含む 1 つの要素 (つまり、1 つのヘッダーまたは 1 つの本文) としてシリアル化されます。次の例のクラスについて考えてみます。

[MessageContract]
public class BankingDepositLog
{
  [MessageHeader] public int numRecords;
  [MessageHeader] public DepositRecord[] records;
  [MessageHeader] public int branchID;
}

これにより、次のような SOAP ヘッダーが結果として生成されます。

<BankingDepositLog>
<numRecords>3</numRecords>
<records>
  <DepositRecord>Record1</DepositRecord>
  <DepositRecord>Record2</DepositRecord>
  <DepositRecord>Record3</DepositRecord>
</records>
<branchID>20643</branchID>
</BankingDepositLog>

もう 1 つの方法は、MessageHeaderArrayAttribute を使用する方法です。この場合、各配列要素が個別にシリアル化されるため、次のように配列要素ごとに 1 つのヘッダーが付加されます。

<numRecords>3</numRecords>
<records>Record1</records>
<records>Record2</records>
<records>Record3</records>
<branchID>20643</branchID>

配列エントリの既定の名前は、MessageHeaderArrayAttribute 属性が適用されたメンバーの名前になります。

MessageHeaderArrayAttribute 属性は、MessageHeaderAttribute から継承されます。この属性は、非配列属性と同じ機能セットを持ちます。たとえば、単一のヘッダーに設定するのと同様に、ヘッダーの配列に順序、名前、および名前空間を設定できます。配列で Order プロパティを使用すると、その配列全体に適用されます。

MessageHeaderArrayAttribute を適用できるのは配列だけであり、コレクションには適用できません。

メッセージコントラクトでのバイト配列の使用

バイト配列を非配列属性 (MessageBodyMemberAttribute と MessageHeaderAttribute) で使用した場合は、配列としてではなく、生成された XML 内で Base64 でエンコードされたデータとして表現される特殊なプリミティブ型として扱われます。

MessageHeaderArrayAttribute 配列属性でバイト配列を使用した場合、結果は使用しているシリアライザーによって異なります。既定のシリアライザーでは、配列が個々のバイトエントリとして表されます。ただし、(サービスコントラクトの XmlSerializer を使用して) XmlSerializerFormatAttribute を選択した場合は、配列属性と非配列属性のどちらを使用しているかに関係なく、バイト配列は Base64 データとして扱われます。

メッセージの一部の署名と暗号化

メッセージコントラクトでは、メッセージのヘッダーまたは本文にデジタル署名し、暗号化するかどうかを示すことができます。

この操作は、MessageContractMemberAttribute.ProtectionLevel 属性と MessageHeaderAttribute 属性の MessageBodyMemberAttribute プロパティを設定することによって実行されます。このプロパティは、System.Net.Security.ProtectionLevel 型の列挙体であり、None (暗号化と署名を行わない)、Sign (デジタル署名だけを行う)、または EncryptAndSign (暗号化とデジタル署名の両方を行う) に設定できます。既定では、 EncryptAndSignです。

これらのセキュリティ機能を使用するには、バインディングと動作を適切に構成する必要があります。適切な構成を行わずにこれらのセキュリティ機能を使用した場合 (資格情報を指定せずにメッセージに署名しようとした場合など)、検証時に例外がスローされます。

メッセージヘッダーの場合、ヘッダーごとに保護レベルが設定されます。

メッセージ本文の各部分については、保護レベルを「最小の保護レベル」として考えることができます。本文は、部分の数にかかわらず、1つの保護レベルしか持ちません。全体の保護レベルは、身体の各部位の中で最も高いProtectionLevelプロパティ設定によって決定されます。各部分の保護レベルは、実際に必要とされる最小限の保護レベルに設定するべきです。

次のコード例のクラスについて考えてみます。

[MessageContract]
public class PatientRecord
{
   [MessageHeader(ProtectionLevel=None)] public int recordID;
   [MessageHeader(ProtectionLevel=Sign)] public string patientName;
   [MessageHeader(ProtectionLevel=EncryptAndSign)] public string SSN;
   [MessageBodyMember(ProtectionLevel=None)] public string comments;
   [MessageBodyMember(ProtectionLevel=Sign)] public string diagnosis;
   [MessageBodyMember(ProtectionLevel=EncryptAndSign)] public string medicalHistory;
}

この例では、recordID ヘッダーは保護されず、patientName はsignedであり、SSN は暗号化および署名されます。本文の comments と diagnosis の各部分では低い保護レベルを指定していても、本文の少なくとも 1 つの部分 (medicalHistory) に EncryptAndSign が適用されているため、メッセージ本文全体が暗号化され、署名されます。

SOAP アクション

SOAP 標準と関連する Web サービス標準では、送信されるすべての SOAP メッセージに設定可能な Action という名前のプロパティが定義されます。このプロパティの値は、操作の OperationContractAttribute.Action プロパティと OperationContractAttribute.ReplyAction プロパティによって制御されます。

SOAP ヘッダーの属性

SOAP 標準では、ヘッダーに設定可能な次の属性が定義されます。

Actor/Role (SOAP 1.1 では Actor、SOAP 1.2 では Role)
MustUnderstand
Relay

Actor 属性または Role 属性は、指定のヘッダーが対象とするノードの URI (Uniform Resource Identifier) を指定します。 MustUnderstand 属性は、ヘッダー処理ノードがヘッダーを認識する必要があるかどうかを指定します。 Relay 属性は、ダウンストリームノードにヘッダーを中継する必要があるかどうかを指定します。 WCF では、(このトピックの後半の「メッセージコントラクトのバージョン管理」セクションで示されているように) MustUnderstand 属性を除いて、受信メッセージに対してこれらの属性の処理は実行されません。ただし、後述するように、必要に応じてこれらの属性を読み書きすることができます。

既定では、メッセージの送信時にこれらの属性は出力されません。これは、2 とおりの方法で変更できます。 1 つ目の方法として、次のコード例に示すように、MessageHeaderAttribute.Actor、MessageHeaderAttribute.MustUnderstand、および MessageHeaderAttribute.Relay の各プロパティを変更することによって、属性を必要な値に静的に設定できます (Role プロパティが存在しないことに注意してください。SOAP 1.2 を使用している場合は、Actor プロパティを設定すると Role 属性が出力されます)。

[MessageContract]
public class BankingTransaction
{
  [MessageHeader(Actor="http://auditingservice.contoso.com", MustUnderstand=true)] public bool IsAudited;
  [MessageHeader] public Operation operation;
  [MessageBodyMember] public BankingTransactionData theData;
}

これらの属性を制御する 2 番目の方法は、コードを通して動的に行う方法です。これを行うには、必要なヘッダーの型を MessageHeader<T> 型にラップし (この型と非ジェネリックバージョンを混同しないようにしてください)、その型を MessageHeaderAttribute と共に使用します。これで、次のコード例に示すように、MessageHeader<T> のプロパティを使用して SOAP 属性を設定できるようになります。

[MessageContract]
public class BankingTransaction
{
  [MessageHeader] public MessageHeader<bool> IsAudited;
  [MessageHeader] public Operation operation;
  [MessageBodyMember] public BankingTransactionData theData;
}
// application code:
BankingTransaction bt = new BankingTransaction();
bt.IsAudited = new MessageHeader<bool>();
bt.IsAudited.Content = false; // Set IsAudited header value to "false"
bt.IsAudited.Actor="http://auditingservice.contoso.com";
bt.IsAudited.MustUnderstand=true;

動的制御機構と静的制御機構の両方を使用する場合、静的な設定が既定で使用されますが、次のコードに示すように、後で動的機構を使用して静的な設定をオーバーライドできます。

[MessageHeader(MustUnderstand=true)] public MessageHeader<Person> documentApprover;
// later on in the code:
BankingTransaction bt = new BankingTransaction();
bt.documentApprover = new MessageHeader<Person>();
bt.documentApprover.MustUnderstand = false; // override the static default of 'true'

次のコードに示すように、属性を動的に制御して繰り返すヘッダーを作成できます。

[MessageHeaderArray] public MessageHeader<Person> documentApprovers[];

受信側で、MessageHeader<T> クラスがこの型のヘッダーで使用されている場合にのみ、これらの SOAP 属性の読み取りを実行できます。受信メッセージの属性設定を明らかにするために、Actor 型のヘッダーの Relay、MustUnderstand、または MessageHeader<T> の各プロパティを調べます。

メッセージを受信した後に返信すると、SOAP の属性設定は MessageHeader<T> 型のヘッダーでのみ往復します。

SOAP ボディパーツの順序

状況によっては、ボディ部の各部分の順序を管理する必要があります。本文要素の既定の順序はアルファベット順ですが、MessageBodyMemberAttribute.Order プロパティで制御できます。このプロパティのセマンティクスは、継承シナリオにおける動作を除き、DataMemberAttribute.Order プロパティのセマンティクスと同じです (メッセージコントラクトでは、派生型の本文メンバーの前に基本型の本文メンバーが並べ替えられることはありません)。詳細については、「データメンバーの順序」を参照してください。

次の例では、通常はアルファベット順で最初である amount が先頭にきますが、 Order プロパティによって 3 番目の位置に挿入されます。

[MessageContract]
public class BankingTransaction
{
  [MessageHeader] public Operation operation;
  [MessageBodyMember(Order=1)] public Account sourceAccount;
  [MessageBodyMember(Order=2)] public Account targetAccount;
  [MessageBodyMember(Order=3)] public int amount;
}

メッセージコントラクトのバージョン管理

場合によっては、メッセージコントラクトを変更する必要があります。たとえば、新しいバージョンのアプリケーションによってメッセージに余分なヘッダーが追加された場合です。この場合、新しいバージョンから古いバージョンに送信するときは、システムは余分なヘッダーを処理し、逆方向に送信するときは不足しているヘッダーを処理する必要があります。

ヘッダーのバージョン管理には、次のルールが適用されます。

WCF では、不足しているヘッダーは問題にされません。対応するメンバーは既定値で残されます。
WCF では、予期しない余分なヘッダーも無視されます。このルールの 1 つの例外は、入力 SOAP メッセージ内の余分なヘッダーの MustUnderstand 属性が true に設定されている場合です。この場合、認識する必要のあるヘッダーを処理できないため、例外がスローされます。

メッセージ本文にも同様のバージョン管理ルールがあります。メッセージ本文の不足している部分と追加された部分はいずれも無視されます。

継承に関する留意点

メッセージコントラクト型は、基本型がメッセージコントラクトを持っている限り、他の型から継承することができます。

他のメッセージコントラクト型から継承したメッセージコントラクト型を使用して、メッセージを作成したり、メッセージにアクセスしたりする場合、次のルールが適用されます。

継承階層内のすべてのメッセージヘッダーが収集され、そのメッセージの完全なヘッダーセットが形成されます。
継承階層内のすべてのメッセージ本文が収集され、完全なメッセージ本文が形成されます。本文の各部分は、継承階層内での位置に関係なく、通常の順序ルール (MessageBodyMemberAttribute.Order プロパティ順、続いてアルファベット順) に従って並べられます。メッセージ本文が継承ツリーの複数レベルに存在するメッセージコントラクト継承の使用は、あまりお勧めできません。基本クラスと派生クラスでヘッダーまたは本文に同じ名前が定義されている場合は、base-most クラスからのメンバーがそのヘッダーまたは本文の値を保存するために使用されます。

次のコード例のクラスについて考えてみます。

[MessageContract]
public class PersonRecord
{
  [MessageHeader(Name="ID")] public int personID;
  [MessageBodyMember] public string patientName;
}

[MessageContract]
public class PatientRecord : PersonRecord
{
  [MessageHeader(Name="ID")] public int patientID;
  [MessageBodyMember] public string diagnosis;
}

PatientRecord クラスは、ID という名前の 1 つのヘッダーを持つメッセージを記述します。このヘッダーは、base-most メンバーが選択されたことによって、personID メンバーには対応しますが、patientID メンバーには対応しません。そのため、この場合は patientID フィールドは使用されません。メッセージ本文には、アルファベット順で、diagnosis 要素の次に patientName 要素が含まれます。この例は、基本メッセージコントラクトと派生メッセージコントラクトの両方にメッセージ本文が含まれ、あまりお勧めできないパターンを示していることに注意してください。

WSDL に関する留意点

メッセージコントラクトを使用するサービスから Web サービス記述言語 (WSDL: Web Services Description Language) コントラクトを生成するときには、メッセージコントラクトのすべての機能が結果の WSDL に反映されるわけではないことに留意してください。次の点を考慮します。

WSDL では、ヘッダー配列の概念を表現することができません。 MessageHeaderArrayAttribute を使用してヘッダー配列を含むメッセージを作成した場合、結果の WSDL は配列ではなく 1 つのヘッダーだけに反映されます。
結果の WSDL ドキュメントに一部の保護レベル情報が反映されない場合があります。
WSDL で生成されたメッセージ型が、メッセージコントラクト型のクラスと同じ名前になります。
複数の処理で同じメッセージコントラクトを使用すると、WSDL ドキュメント内に複数のメッセージ型が生成されます。以降も使用できるように、"2"、"3" などの番号を付加することで名前を一意にします。 WSDL をインポートし直すと、名前以外は同一の複数のメッセージコントラクト型が作成されます。

SOAP エンコードに関する留意点

WCF では、XML のレガシ SOAP エンコードスタイルを使用できますが、これを使用することはお勧めしません。 (サービスコントラクトに適用されている Use で、Encoded プロパティを System.ServiceModel.XmlSerializerFormatAttribute に設定して) このスタイルを使用する場合、次の追加の考慮事項が適用されます。

メッセージヘッダーはサポートされません。つまり、MessageHeaderAttribute 属性と MessageHeaderArrayAttribute 配列属性は、SOAP エンコーディングと互換性がありません。
メッセージコントラクトがラップされていない場合、つまり、IsWrapped プロパティが false に設定されている場合は、メッセージコントラクトが持つことのできる本文の部分は 1 つに限られます。
要求メッセージコントラクトのラッパー要素の名前は、操作の名前と一致する必要があります。この場合、メッセージコントラクトの WrapperName プロパティを使用します。
応答メッセージコントラクトのラッパー要素の名前は、操作の名前にサフィックスとして "Response" を付けたものと同じである必要があります。この場合、メッセージコントラクトの WrapperName プロパティを使用します。

SOAP エンコードはオブジェクト参照を保存します。例えば、次のコードを考えてください。

[MessageContract(WrapperName="updateChangeRecord")]
public class ChangeRecordRequest
{
  [MessageBodyMember] Person changedBy;
  [MessageBodyMember] Person changedFrom;
  [MessageBodyMember] Person changedTo;
}

[MessageContract(WrapperName="updateChangeRecordResponse")]
public class ChangeRecordResponse
{
  [MessageBodyMember] Person changedBy;
  [MessageBodyMember] Person changedFrom;
  [MessageBodyMember] Person changedTo;
}

// application code:
ChangeRecordRequest cr = new ChangeRecordRequest();
Person p = new Person("John Doe");
cr.changedBy=p;
cr.changedFrom=p;
cr.changedTo=p;

SOAP エンコーディングを使用してメッセージをシリアル化した後、changedFrom と changedTo には p のコピーは保存されませんが、代わりに、changedBy 要素内部のコピーがポイントされます。

パフォーマンスに関する考慮事項

すべてのメッセージヘッダーとメッセージ本文が個別にシリアル化されます。したがって、ヘッダーおよび本文ごとに同じ名前空間が繰り返し宣言される可能性があります。メッセージの回線上のサイズを特に考慮してパフォーマンスを改善するには、複数のヘッダーと本体部分を単一のヘッダーまたは本体部分に統合します。たとえば、次のコードの代わりに

[MessageContract]
public class BankingTransaction
{
  [MessageHeader] public Operation operation;
  [MessageBodyMember] public Account sourceAccount;
  [MessageBodyMember] public Account targetAccount;
  [MessageBodyMember] public int amount;
}

次のコードを使用します。

[MessageContract]
public class BankingTransaction
{
  [MessageHeader] public Operation operation;
  [MessageBodyMember] public OperationDetails details;
}

[DataContract]
public class OperationDetails
{
  [DataMember] public Account sourceAccount;
  [DataMember] public Account targetAccount;
  [DataMember] public int amount;
}

イベントベースの非同期とメッセージコントラクト

イベントベースの非同期モデルのデザインガイドラインには、複数の値を返す場合に、1 つの値を Result プロパティとして返し、残りの値を EventArgs オブジェクトのプロパティとして返すことが記載されています。この 1 つの結果として、クライアントがイベントベースの非同期コマンドオプションを使用してメタデータをインポートし、操作から複数の値が返される場合、既定の EventArgs オブジェクトは 1 つの値を Result プロパティとして返し、残りの値は EventArgs オブジェクトのプロパティになります。

メッセージオブジェクトを Result プロパティとして受け取り、返された値をそのオブジェクトのプロパティとして取得する場合は、/messageContract コマンドオプションを使用します。これにより、Result オブジェクトの EventArgs プロパティとして応答メッセージを返すシグネチャが生成されます。すべての内部戻り値は、応答メッセージオブジェクトのプロパティになります。

メッセージ コントラクトの使用

処理におけるメッセージ コントラクトの使用

メッセージ コントラクトの定義

ヘッダー名、本文名、および名前空間の制御

SOAP 本文のパーツをラップするかどうかの制御

メッセージ コントラクト内部でのカスタム型の使用

メッセージ コントラクト内部での配列の使用

メッセージ コントラクトでのバイト配列の使用

メッセージの一部の署名と暗号化

SOAP アクション

SOAP ヘッダーの属性

SOAP ボディパーツの順序

メッセージ コントラクトのバージョン管理

継承に関する留意点

WSDL に関する留意点

SOAP エンコードに関する留意点

パフォーマンスに関する考慮事項

イベント ベースの非同期とメッセージ コントラクト

関連項目

その他のリソース

メッセージコントラクトの使用

処理におけるメッセージコントラクトの使用

メッセージコントラクトの定義

メッセージコントラクト内部でのカスタム型の使用

メッセージコントラクト内部での配列の使用

メッセージコントラクトでのバイト配列の使用

メッセージコントラクトのバージョン管理

イベントベースの非同期とメッセージコントラクト