データ コントラクト サロゲート

  • [アーティクル]

データ コントラクト サロゲートは、データ コントラクト モデルを基盤に構築された高度な機能です。この機能は、型をシリアル化または逆シリアル化する方法や、型をメタデータに投影する方法をユーザーが変更する場合に、型のカスタマイズと置換に使用することを目的としています。サロゲートを使用できるのは、型のデータ コントラクトが指定されていない場合、フィールドやプロパティが DataMemberAttribute 属性でマークされていない場合、またはユーザーがスキーマのバリエーションを動的に作成することを希望している場合などです。

DataContractSerializer を使用して .NET Framework から XML などの適切な形式に変換するときに、データ コントラクト サロゲートを使用してシリアル化と逆シリアル化を行います。また、XML スキーマ ドキュメント (XSD) などのメタデータ表現を生成するときに、データ コントラクト サロゲートを使用して、型のエクスポートするメタデータを変更できます。インポート時には、メタデータからコードが作成されますが、この場合にサロゲートを使用すると、生成されるコードもカスタマイズできます。

サロゲートのしくみ

サロゲートは、ある型 ("元の" 型) を別の型 ("サロゲートされた" 型) に割り当てることによって機能します。元の型 Inventory と新しいサロゲート型 InventorySurrogated の例を以下に示します。Inventory 型はシリアル化できませんが、InventorySurrogated 型は以下のようになります。

このクラスにはデータ コントラクトが定義されていないため、このクラスをデータ コントラクトを持つサロゲート クラスに変換します。サロゲートされたクラスの例を次に示します。

IDataContractSurrogate の実装

データ コントラクト サロゲートを使用するには、IDataContractSurrogate インターフェイスを実装します。

考えられる実装での IDataContractSurrogate の各メソッドの概要を以下に示します。

GetDataContractType

GetDataContractType メソッドは、ある型を別の型に割り当てます。これは、シリアル化、逆シリアル化、インポート、およびエクスポートに必須のメソッドです。

最初の作業として、他の型に割り当てる型を定義します。次に例を示します。

  • シリアル化では、後で GetObjectToSerialize メソッドを呼び出して、元のインスタンスをサロゲートされたインスタンスに変換する際に、このメソッドによって返されたマッピングが使用されます。
  • 逆シリアル化では、サロゲート型のインスタンスに逆シリアル化する際に、シリアライザはこのメソッドによって返されたマッピングを使用します。その後、GetDeserializedObject が呼び出されて、サロゲートされたインスタンスが元の型のインスタンスに変換されます。
  • エクスポートでは、メタデータの生成に使用するデータ コントラクトを取得する際に、このメソッドによって返されたサロゲート型が反映されます。
  • インポートでは、最初の型がサロゲート型に変更されます。このサロゲート型は、参照のサポートなどの目的で使用するデータ コントラクトを取得する際に反映されます。

Type パラメータは、シリアル化、逆シリアル化、インポート、またはエクスポートするオブジェクトの型です。サロゲートが型を処理しない場合、GetDataContractType メソッドは入力の型を返す必要があります。それ以外の場合は、サロゲートされた適切な型を返します。複数のサロゲート型が存在する場合は、このメソッドで多数のマッピングを定義できます。

GetDataContractType メソッドは、組み込みのデータ コントラクト プリミティブ (Int32 や String など) に対しては呼び出されません。その他の型 (配列、ユーザー定義型、その他のデータ構造体など) については、このメソッドは各型に対して呼び出されます。

前の例では、このメソッドは type パラメータと Inventory が比較可能かどうかをチェックします。比較可能な場合は、InventorySurrogated に割り当てます。シリアル化、逆シリアル化、インポート スキーマ、またはエクスポート スキーマを呼び出すときは、常にこの関数が最初に呼び出されて、型間のマッピングが確認されます。

GetObjectToSerialize Method

GetObjectToSerialize メソッドは、元の型のインスタンスをサロゲートされた型のインスタンスに変換します。これは、シリアル化に必須のメソッドです。

次の手順では、GetObjectToSerialize メソッドを実装して、物理データを元のインスタンスからサロゲートに割り当てる方法を定義します。次に例を示します。

GetObjectToSerialize メソッドは、オブジェクトをシリアル化するときに呼び出されます。このメソッドでは、元の型からサロゲートされた型のフィールドにデータを転送します。フィールドは、サロゲート フィールドに直接割り当てることができます。また、元のデータの操作をサロゲートに格納することもできます。このメソッドは、フィールドを直接割り当てる場合、サロゲートされたフィールドに格納されたデータに対して操作を実行する場合、サロゲートされたフィールドに元の型の XML を格納する場合などに使用できます。

targetType パラメータは、メンバの宣言された型を指します。このパラメータは、GetDataContractType メソッドによって返されたサロゲートされた型です。シリアライザは、返されるオブジェクトがこの型に割り当て可能であることを強制するわけではありません。obj パラメータはシリアル化するオブジェクトであり、必要に応じてサロゲートに変換されます。サロゲートがオブジェクトを処理しない場合、このメソッドは入力オブジェクトを返す必要があります。それ以外の場合は、新しいサロゲート オブジェクトが返されます。オブジェクトが null の場合、サロゲートは呼び出されません。さまざまなインスタンスの多数のサロゲートのマッピングをこのメソッドで定義できます。

DataContractSerializer の作成時に、オブジェクト参照を保持するように指定できます (詳細な情報については、次のページを参照してください。 「シリアル化と逆シリアル化」を参照してください)。これを行うには、コンストラクタの preserveObjectReferences パラメータを true に設定します。この場合、サロゲートはオブジェクトに対して 1 回だけ呼び出されます。これは、以降のシリアル化では参照をストリームに書き込むだけだからです。preserveObjectReferences を false に設定すると、インスタンスが発生するたびにサロゲートが呼び出されます。

シリアル化されたインスタンスの型が宣言された型と異なる場合、インスタンスをもう一方の側で逆シリアル化できるように、型情報 (xsi:type など) がストリームに書き込まれます。このプロセスは、オブジェクトがサロゲートされているかどうかに関係なく発生します。

前述の例では、Inventory インスタンスのデータが InventorySurrogated のデータに変換されます。オブジェクトの型がチェックされ、サロゲートされた型に変換するために必要な処理が実行されます。この場合、Inventory クラスの各フィールドは、InventorySurrogated クラスのフィールドに直接コピーされます。

GetDeserializedObject Method

GetDeserializedObject メソッドは、サロゲートされた型のインスタンスを元の型のインスタンスに変換します。これは、逆シリアル化に必須のメソッドです。

次の作業として、サロゲート インスタンスから元のインスタンスに物理データを割り当てる方法を定義します。次に例を示します。

このメソッドが呼び出されるのは、オブジェクトの逆シリアル化中だけです。このメソッドは、サロゲート型から元の型に戻す逆シリアル化に必要な逆方向のデータ マッピングを行います。GetObjectToSerialize メソッドと同様に、フィールド データを直接交換する場合、データに対して操作を実行する場合、XML データを格納する場合などに使用できます。逆シリアル化するときには、データ変換時の操作の結果として、元のデータから正確なデータ値を必ずしも取得できるとは限りません。

targetType パラメータは、メンバの宣言された型を指します。このパラメータは、GetDataContractType メソッドによって返されたサロゲートされた型です。obj パラメータは、逆シリアル化されたオブジェクトを参照します。オブジェクトがサロゲートされている場合、オブジェクトを変換して元の型に戻すことができます。サロゲートがオブジェクトを処理しない場合、このメソッドは入力オブジェクトを返します。それ以外の場合は、変換が完了すると、逆シリアル化されたオブジェクトが返されます。複数のサロゲート型が存在する場合、各型とその変換を示すことにより、サロゲートからそれぞれのプライマリ型へのデータ変換を提供できます。

オブジェクトを返す場合、このサロゲートによって返されたオブジェクトで内部オブジェクト テーブルが更新されます。インスタンスへの以降の参照では、このオブジェクト テーブルからサロゲートされたインスタンスが取得されます。

前の例では、InventorySurrogated 型のオブジェクトが最初の Inventory 型に変換されます。この場合、データは InventorySurrogated から Inventory の対応するフィールドに直接転送されます。データ操作は発生しないため、各メンバ フィールドにはシリアル化前と同じ値が格納されます。

GetCustomDataToExport Method

スキーマをエクスポートする場合、GetCustomDataToExport メソッドは省略可能です。このメソッドは、エクスポートするスキーマに追加データやヒントを挿入するために使用します。追加データは、メンバ レベルまたは型レベルで挿入できます。次に例を示します。

このメソッド (2 つのオーバーロードを持ちます) を使用すると、メンバ レベルまたは型レベルで、追加情報をメタデータに含めることができます。メンバが public と private のどちらであるかに関するヒントや、スキーマのエクスポートとインポート全体を通じて保持されるコメントを含めることができます。このメソッドを使用しない場合、このような情報は失われます。このメソッドは、メンバまたは型の挿入や削除を行うのではなく、メンバ レベルまたは型レベルでスキーマに付加的なデータを追加します。

このメソッドのオーバーロードでは、Type (clrtype パラメータ) または MemberInfo (memberInfo パラメータ) を取得できます。2 番目のパラメータは、常に Type (dataContractType パラメータ) です。このメソッドは、サロゲートされた dataContractType 型のすべてのメンバと型に対して呼び出されます。

どちらのオーバーロードでも、null またはシリアル化可能なオブジェクトを返す必要があります。null 以外のオブジェクトは、エクスポートするスキーマに注釈としてシリアル化されます。Type オーバーロードでは、スキーマにエクスポートされる各型は、dataContractType パラメータのサロゲートされた型と共に、最初のパラメータでこのメソッドに送信されます。MemberInfo オーバーロードでは、スキーマにエクスポートされる各メンバが、2 番目のパラメータのサロゲートされた型と共に memberInfo パラメータとして情報を送信します。

GetCustomDataToExport Method (Type, Type)

System.Runtime.Serialization.IDataContractSurrogate.GetCustomDataToExport(System.Type,System.Type) メソッドは、すべての型定義のスキーマのエクスポート中に呼び出されます。このメソッドは、エクスポート時にスキーマ内の型に情報を追加します。スキーマに含める必要のある追加データがあるかどうかを確認するために、定義済みの各型がこのメソッドに送信されます。

GetCustomDataToExport Method (MemberInfo, Type)

System.Runtime.Serialization.IDataContractSurrogate.GetCustomDataToExport(System.Reflection.MemberInfo,System.Type) は、エクスポートする型のすべてのメンバのエクスポート中に呼び出されます。この関数を使用すると、エクスポート時にスキーマに含めるメンバに関するコメントをカスタマイズできます。スキーマに付加的なデータを追加する必要があるかどうかをチェックするために、クラスの各メンバの情報がこのメソッドに送信されます。

前述の例では、サロゲートの各メンバの dataContractType が検索されます。検索後、各フィールドの適切なアクセス修飾子が返されます。このカスタマイズを行わない場合、アクセス修飾子の既定値は public です。したがって、実際のアクセス制限には関係なく、エクスポートされたスキーマを使用して生成されるコードでは、すべてのメンバが public として定義されます。この実装を使用しない場合、numpens メンバは、サロゲートで private として定義されている場合でも、エクスポートされたスキーマでは public になります。このメソッドを使用することにより、エクスポートされるスキーマで、アクセス修飾子を private として生成できます。

GetReferencedTypeOnImport Method

このメソッドは、サロゲートの Type を元の型に割り当てます。スキーマのインポートでは、このメソッドは省略可能です。

スキーマをインポートし、そのコードを生成するサロゲートを作成したら、次の作業として、元の型に対してサロゲート インスタンスの型を定義します。

生成されるコードで既存のユーザー型を参照する必要がある場合は、GetReferencedTypeOnImport メソッドを実装してこれを行います。

スキーマをインポートするときに、サロゲートされたデータ コントラクトを型に割り当てるために、すべての型宣言に対してこのメソッドが呼び出されます。typeName および typeNamespace の各文字列パラメータでは、サロゲートされた型の名前と名前空間が定義されます。GetReferencedTypeOnImport の戻り値は、新しい型を生成する必要があるかどうかを判断するために使用されます。このメソッドは、有効な型または null のいずれかを返す必要があります。有効な型を返す場合、返される型は生成されるコード内で参照される型として使用されます。null を返す場合は、型が参照されることはないため、新しい型を作成する必要があります。複数のサロゲートが存在する場合は、各サロゲート型から最初の型へのマッピングを実行できます。

customData パラメータは、GetCustomDataToExport から最初に返されたオブジェクトです。この customData は、サロゲート作成者が、コードを生成するためにインポート時に使用するメタデータに追加情報やヒントを挿入する場合に使用します。

ProcessImportedType メソッド

ProcessImportedType メソッドは、スキーマのインポートから作成された型をカスタマイズします。このメソッドは省略可能です。

スキーマをインポートするときに、このメソッドを使用すると、インポートする型とコンパイルの情報をカスタマイズできます。次に例を示します。

インポート中に、このメソッドは生成されるすべての型に対して呼び出されます。指定した CodeTypeDeclaration を変更するか、CodeCompileUnit を変更します。これには、CodeTypeDeclaration の名前、メンバ、属性、および他のさまざまなプロパティの変更が含まれます。CodeCompileUnit を処理することにより、ディレクティブ、名前空間、参照アセンブリ、および他のいくつかの側面を変更できます。

CodeTypeDeclaration パラメータには、DOM コードの型宣言が含まれます。CodeCompileUnit パラメータでは、コードの処理に関する変更を行うことができます。null を返すと、型宣言が破棄されます。CodeTypeDeclaration を返すと、変更が保持されます。

メタデータのエクスポート時にカスタム データを挿入した場合は、インポート時にこのデータをユーザーに提供して、データを使用できるようにする必要があります。このカスタム データは、プログラミング モデルのヒントやその他のコメントに使用できます。各 CodeTypeDeclaration と CodeTypeMember インスタンスには、IDataContractSurrogate 型にキャストされる UserData プロパティとしてカスタム データが含まれます。

前述の例では、インポートするスキーマに対して変更が行われています。コードでは、サロゲートを使用して元の型の private メンバを保持しています。スキーマをインポートするときの既定のアクセス修飾子は public です。したがって、この例のように変更しない限り、サロゲート スキーマのすべてのメンバは public になります。エクスポート中に、どのメンバが private であるかに関するカスタム データがメタデータに挿入されます。この例では、カスタム データを調べ、アクセス修飾子が private かどうかをチェックした後、属性を設定することで適切なメンバを private に変更しています。このカスタマイズを行わない場合、numpens メンバは、private ではなく public として定義されます。

GetKnownCustomDataTypes メソッド

このメソッドは、スキーマから定義済みのカスタム データ型を取得します。スキーマのインポートでは、このメソッドは省略可能です。

このメソッドは、スキーマのエクスポートとインポートの開始時に呼び出されます。このメソッドは、エクスポートまたはインポートするスキーマで使用されるカスタム データ型を返します。メソッドには、型のコレクションである Collection (customDataTypes パラメータ) が渡されます。このメソッドでは、既知の型をこのコレクションに追加する必要があります。既知のカスタム データ型は、DataContractSerializer を使用したカスタム データのシリアル化と逆シリアル化を可能にするために必要となります。詳細な情報については、次のページを参照してください。 「既知のデータ コントラクト型」を参照してください。

サロゲートの実装

WCF でデータ コントラクト サロゲートを使用するには、いくつかの特別な手順に従う必要があります。

シリアル化と逆シリアル化にサロゲートを使用するには

サロゲートを使用してデータのシリアル化と逆シリアル化を実行するには、DataContractSerializer を使用します。DataContractSerializer は、DataContractSerializerOperationBehavior によって作成されます。サロゲートも指定する必要があります。

シリアル化と逆シリアル化を実装するには

  1. サービスの ServiceHost のインスタンスを作成します。この手順の詳細については、「基本的な WCF プログラミング」を参照してください。

  2. 指定したサービス ホストの各 ServiceEndpoint について、OperationDescription を検索します。

  3. 操作の動作を検索して、DataContractSerializerOperationBehavior のインスタンスが見つかるかどうかを確認します。

  4. DataContractSerializerOperationBehavior が見つかった場合、DataContractSurrogate プロパティをサロゲートの新しいインスタンスに設定します。DataContractSerializerOperationBehavior が見つからなかった場合は、新しいインスタンスを作成し、新しい動作の DataContractSurrogate メンバをサロゲートの新しいインスタンスに設定します。

  5. 最後に、次の例に示すように、この新しい動作を現在の操作の動作に追加します。

メタデータのインポートにサロゲートを使用するには

WSDL や XSD などのメタデータをインポートしてクライアント側のコードを生成する場合、XSD スキーマからコードを生成するコンポーネント (XsdDataContractImporter) にサロゲートを追加する必要があります。これを行うには、メタデータをインポートする際に使用する WsdlImporter を直接変更します。

メタデータのインポートに使用するサロゲートを実装するには

  1. WsdlImporter クラスを使用して、メタデータをインポートします。

  2. TryGetValue メソッドを使用して、XsdDataContractImporter が定義されているかどうかをチェックします。

  3. TryGetValue メソッドが false を返した場合、新しい XsdDataContractImporter を作成し、Options プロパティを ImportOptions クラスの新しいインスタンスに設定します。それ以外の場合は、TryGetValue メソッドの out パラメータによって返されたインポータを使用します。

  4. XsdDataContractImporter に ImportOptions が定義されていない場合は、このプロパティを ImportOptions クラスの新しいインスタンスとして設定します。

  5. XsdDataContractImporter の ImportOptions の DataContractSurrogate プロパティを、サロゲートの新しいインスタンスに設定します。

  6. MetadataExporter クラスから継承した WsdlImporter の State プロパティによって返されたコレクションに、XsdDataContractImporter を追加します。

  7. WsdlImporter の ImportAllContracts メソッドを使用して、スキーマ内のすべてのデータ コントラクトをインポートします。この最後の手順で、サロゲートを呼び出すことによって読み込まれたスキーマからコードが生成されます。

メタデータのエクスポートにサロゲートを使用するには

WCF からサービスのメタデータをエクスポートする場合、既定では WSDL と XSD スキーマを生成する必要があります。データ コントラクト型の XSD スキーマを生成するコンポーネント (XsdDataContractExporter) に、サロゲートを追加する必要があります。これを行うには、IWsdlExportExtension を実装する動作を使用して WsdlExporter を変更するか、メタデータをエクスポートする際に使用する WsdlExporter を直接変更します。

メタデータのエクスポートにサロゲートを使用するには

  1. 新しい WsdlExporter を作成するか、ExportContract メソッドに渡された wsdlExporter パラメータを使用します。

  2. TryGetValue 関数を使用して、XsdDataContractExporter が定義されているかどうかをチェックします。

  3. TryGetValue が false を返した場合、WsdlExporter から生成された XML スキーマを使用して新しい XsdDataContractExporter を作成し、WsdlExporter の State プロパティによって返されたコレクションに追加します。それ以外の場合は、TryGetValue メソッドの out パラメータによって返されたエクスポータを使用します。

  4. XsdDataContractExporter に ExportOptions が定義されていない場合は、Options プロパティを ExportOptions クラスの新しいインスタンスに設定します。

  5. XsdDataContractExporter の ExportOptions の DataContractSurrogate プロパティを、サロゲートの新しいインスタンスに設定します。メタデータをエクスポートするための以降の手順を変更する必要はありません。

関連項目

リファレンス

DataContractSerializer
IDataContractSurrogate
DataContractSerializerOperationBehavior
ImportOptions
ExportOptions

概念

データ コントラクトの使用