フィードのカスタマイズ (WCF Data Services)

WCF Data Services は、Open Data Protocol (OData) を使用してデータをフィードとして公開します。OData は、データ フィード用に Atom 形式と JavaScript Object Notation (JSON) 形式の両方をサポートしています。Atom フィードを使用する場合、OData は、エンティティやリレーションシップなどのデータを XML 形式にシリアル化する標準の方法を提供します。この XML 形式は、HTTP メッセージの本文に含めることができます。OData は、エンティティに含まれるデータと Atom 要素間のエンティティとプロパティの既定のマッピングを定義します。詳細については、OData: Atom 形式に関する Web ページを参照してください。

場合によっては、データ サービスから返されるプロパティのデータを、標準のフィードの形式ではなくカスタマイズした方法でシリアル化する必要があります。OData を使用すると、データ フィードのシリアル化をカスタマイズして、エントリの未使用の要素と属性、またはフィードのエントリのカスタム要素にエンティティのプロパティをマップできます。

注 :
フィードのカスタマイズは、Atom フィードでのみサポートされます。返されたフィードに対して JSON 形式が要求されたときは、カスタム フィードが返されません。

WCF Data Services を使用すると、Atom ペイロードに対するエンティティとプロパティの代替マッピングは、属性をデータ モデルのエンティティ型に手動で適用することによって定義できます。これらの属性の適用方法は、データ サービスのデータ ソース プロバイダーによって決定されます。

注 :
カスタム フィードを定義する場合、カスタム マッピングが定義されているすべてのエンティティ プロパティが投影に含まれることを保証する必要があります。マップされているエンティティ プロパティが投影に含まれていない場合、データの損失が発生することがあります。詳細については、「クエリ射影 (WCF Data Services)」を参照してください。

Entity Framework プロバイダーを使用したフィードのカスタマイズ

Entity Framework プロバイダーで使用されるデータ モデルは、.edmx ファイルの XML として表現されます。この場合、カスタム フィードを定義する属性が、データ モデルのエンティティ型とプロパティを表現する EntityType および Property 要素に追加されます。これらのフィードのカスタマイズ属性は、データ モデルを定義するために Entity Framework プロバイダーで使用される形式である [MC-CSDL]: 概念スキーマ定義ファイル形式で定義されていません。したがって、フィードのカスタマイズ属性を特定のスキーマ名前空間で宣言する必要があります。これは、m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata" として定義されます。次の XML フラグメントは、ProductName、ReorderLevel、および UnitsInStock プロパティを定義する Products エンティティ型の Property 要素に適用されたフィードのカスタマイズ属性を示します。

<Property Name="ProductName" Type="String" Nullable="false"
          MaxLength="40" Unicode="true" FixedLength="false"
          m:FC_TargetPath="SyndicationAuthorName"
          m:FC_ContentKind="text"
          m:FC_KeepInContent="true"
    />
<Property Name="UnitsInStock" Type="Int16"
          m:FC_TargetPath="UnitsInStock"
          m:FC_NsPrefix="Northwind"
          m:FC_NsUri="http://schemas.examples.microsoft.com/dataservices"
          m:FC_KeepInContent="true"
    />
<Property Name="ReorderLevel" Type="Int16"
          m:FC_TargetPath="UnitsInStock/@ReorderLevel"
          m:FC_NsPrefix="Northwind"
          m:FC_NsUri="http://schemas.examples.microsoft.com/dataservices"
          m:FC_KeepInContent="false"
    />

これらの属性によって Products エンティティ セットに対して次のカスタム データ フィードが生成されます。このカスタム データ フィードでは、ProductName プロパティ値が author 要素内に加えて、ProductName プロパティ要素としても表示されます。UnitsInStock プロパティは、一意の名前空間、および属性としての ReorderLevel プロパティと共にカスタム要素に表示されます。

<entry xml:base="https://localhost:12345/Northwind.svc/" 
         xmlns:d="https://schemas.microsoft.com/ado/2007/08/dataservices" 
         xmlns:m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata" 
         xmlns="http://www.w3.org/2005/Atom">
  <id>https://localhost:12345/Northwind.svc/Products(1)</id>
  <title type="text" />
  <updated>2009-10-02T05:09:44Z</updated>
  <author>
    <name>Chai</name>
  </author>
  <link rel="edit" title="Products" href="Products(1)" />
  <link rel="https://schemas.microsoft.com/ado/2007/08/dataservices/related/Order_Details" 
        type="application/atom+xml;type=feed" title="Order_Details" 
        href="Products(1)/Order_Details" />
  <category term="NorthwindModel.Products" 
            scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
  <content type="application/xml">
    <m:properties>
      <d:ProductID m:type="Edm.Int32">1</d:ProductID>
      <d:ProductName>Chai</d:ProductName>
      <d:UnitsInStock m:type="Edm.Int16">39</d:UnitsInStock>
      <d:SupplierID m:type="Edm.Int32">1</d:SupplierID>
      <d:CategoryID m:type="Edm.Int32">1</d:CategoryID>
      <d:QuantityPerUnit>10 boxes x 20 bags</d:QuantityPerUnit>
      <d:UnitPrice m:type="Edm.Decimal">18.0000</d:UnitPrice>
      <d:UnitsOnOrder m:type="Edm.Int16">0</d:UnitsOnOrder>
      <d:Discontinued m:type="Edm.Boolean">false</d:Discontinued>
    </m:properties>
  </content>
  <Northwind:UnitsInStock 
    Northwind:ReorderLevel="10" 
    xmlns:Northwind="http://schemas.examples.microsoft.com/dataservices">39</Northwind:UnitsInStock>
</entry>

詳細については、「方法: Entity Framework プロバイダーでフィードをカスタマイズする (WCF Data Services)」を参照してください。

注 :
データ モデルへの拡張はエンティティ デザイナーでサポートされていないので、データ モデルを含む XML ファイルを手動で変更する必要があります。Entity Data Model ツールによって生成される .edmx ファイル詳細情報、「.edmx File Overview (Entity Framework)」を参照してください。

カスタム フィード属性

次の表に、データ モデルを定義する概念スキーマ定義言語 (CSDL) に追加できるフィードをカスタマイズする XML 属性を示します。これらの属性は、EntityPropertyMappingAttribute のプロパティと同等です。

<Property Name="ReorderLevel" Type="Int16"
          m:FC_TargetPath="UnitsInStock/@ReorderLevel"
          m:FC_NsPrefix="Northwind"
          m:FC_NsUri="http://schemas.examples.microsoft.com/dataservices"
          m:FC_KeepInContent="false"
    />

注 :
属性名および値では、大文字と小文字が区別されます。属性は、EntityType 要素または 1 つ以上の Property 要素に適用されます (両方には適用されません)。

リフレクション プロバイダーを使用したフィードのカスタマイズ

リフレクション プロバイダーを使用して実装されたデータ モデル用にフィードをカスタマイズするには、EntityPropertyMappingAttribute 属性の 1 つ以上のインスタンスをデータ モデル内でエンティティ型を表現するクラスに追加します。EntityPropertyMappingAttribute クラスのプロパティは、前のセクションで説明したフィードのカスタマイズ属性に対応します。両方のプロパティに対して定義されたカスタム フィード マッピングと共に Order 型の宣言の例を次に示します。

注 :
次の例のデータ モデルは、トピック「方法: リフレクション プロバイダーを使用してデータ サービスを作成する (WCF Data Services)」で定義されています。

<EntityPropertyMappingAttribute("Customer", _
    SyndicationItemProperty.AuthorName, _
    SyndicationTextContentKind.Plaintext, True)> _
<EntityPropertyMapping("OrderId", _
    SyndicationItemProperty.Title, _
    SyndicationTextContentKind.Plaintext, False)> _
<DataServiceKeyAttribute("OrderId")> _
Public Class Order

[EntityPropertyMappingAttribute("Customer", 
    SyndicationItemProperty.AuthorName,
    SyndicationTextContentKind.Plaintext, true)]
[EntityPropertyMapping("OrderId", 
    SyndicationItemProperty.Title, 
    SyndicationTextContentKind.Plaintext, false)]
[DataServiceKeyAttribute("OrderId")]
public class Order

これらの属性によって Orders エンティティ セットに対して次のカスタム データ フィードが生成されます。このカスタム フィードでは、OrderId プロパティ値は entry の title 要素内にのみ表示されます。Customer プロパティ値は author 要素内だけでなく、Customer プロパティ要素としても表示されます。

<entry xml:base="https://localhost:12345/OrderItems.svc/" 
       xmlns:d="https://schemas.microsoft.com/ado/2007/08/dataservices" 
       xmlns:m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata" 
       xmlns="http://www.w3.org/2005/Atom">
  <id>https://localhost:12345/OrderItems.svc/Orders(0)</id>
  <title type="text">0</title>
  <updated>2009-07-25T21:11:11Z</updated>
  <author>
    <name>Peter Franken</name>
  </author>
  <link rel="edit" title="Order" href="Orders(0)" />
  <link rel="https://schemas.microsoft.com/ado/2007/08/dataservices/related/Items" 
        type="application/atom+xml;type=feed" title="Items" href="Orders(0)/Items" />
  <category term="CustomDataService.Order" 
            scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
  <content type="application/xml">
    <m:properties>
      <d:Customer>Peter Franken</d:Customer>
    </m:properties>
  </content>
</entry>

詳細については、「方法: リフレクション プロバイダーでフィードをカスタマイズする (WCF Data Services)」を参照してください。

カスタム データ サービス プロバイダーを使用したフィードのカスタマイズ

カスタム データ サービス プロバイダーを使用して定義されたデータ モデル用のフィードのカスタマイズは、データ モデル内でエンティティ型を表現する ResourceType で AddEntityPropertyMappingAttribute を呼び出すことによってリソース型に対して定義されます。詳細については、「カスタム データ サービス プロバイダー (WCF Data Services)」を参照してください。

カスタム フィードの処理

OData フィードをアプリケーションが直接処理する場合、アプリケーションは、返されたフィード内のカスタム要素および属性を処理できる必要があります。データ サービス プロバイダーに関係なく、データ モデルにカスタム フィードを実装した場合、$metadata エンドポイントは、データ サービスによって返される CSDL のカスタム フィード属性としてカスタム フィード情報を返します。[サービス参照の追加] ダイアログまたは datasvcutil.exe ツールを使用してクライアント データ サービス クラスを生成する場合、データ サービスへの要求および応答を正しく処理するためにカスタム フィード属性が使用されます。

フィードのカスタマイズに関する考慮事項

カスタム フィードのマッピングを定義する場合は、以下を検討してください。

• WCF Data Services クライアントは、フィード内のマップされた要素に含まれているのが空白のみの場合、その要素を空であると見なします。そのため、空白のみを含むマップされた要素は、同じ空白を使用するクライアントで具体化されません。この空白をクライアントで維持するには、フィード マッピング属性で KeepInContext の値を true に設定する必要があります。

バージョン管理の要件

フィードのカスタマイズには、次に示す OData プロトコルのバージョン管理の要件があります。

• フィードのカスタマイズを行う場合は、クライアントとデータ サービスの両方でバージョン 2.0 以降の OData プロトコルがサポートされている必要があります。

詳細については、「WCF Data Services の複数のバージョンの使用」を参照してください。

参照

概念

リフレクション プロバイダー (WCF Data Services)
Entity Framework プロバイダー (WCF Data Services)