摘要自訂 (WCF Data Services)

發行項
02/28/2011

WCF Data Services 會使用 Open Data Protocol (OData) 將資料公開為摘要。OData 支援資料摘要使用 Atom 和「JavaScript 物件標記法」(JavaScript Object Notation，JSON) 格式。當您使用 Atom 摘要時，OData 會提供標準的方法，將資料 (例如實體和關聯性) 序列化成為 XML 格式，該格式可包含在 HTTP 訊息本文之中。OData 會定義實體內的資料與 Atom 項目之間的預設實體屬性對應。如需詳細資訊，請參閱 OData：Atom 格式。

您可能有一個應用程式案例，該案例要求資料服務所傳回的屬性資料是以自訂方式序列化，而不是以標準摘要格式序列化。透過 OData ，您可以自訂資料摘要的序列化作業，好讓實體的屬性可以對應至項目 (Entry) 的未使用項目 (Element) 或屬性，或是對應至摘要中項目 (Entry) 的自訂項目 (Element)。

注意：
僅支援對 Atom 摘要進行摘要自訂。當要求傳回的摘要使用 JSON 格式時，不會傳回自訂摘要。

透過 WCF Data Services ，您可以手動將屬性套用至資料模型中的實體類型，藉以定義 Atom 裝載的替代實體屬性對應。資料服務的資料來源提供者會判斷您應如何套用這些屬性。

注意：
當您定義自訂摘要時，您必須確保所有已定義自訂對應的實體屬性都包含在投影中。若投影中未包含對應的實體屬性，則可能會發生資料遺失。如需詳細資訊，請參閱查詢投影 (WCF 資料服務)。

使用 Entity Framework 提供者自訂摘要

搭配 Entity Framework 提供者使用的資料模型在 .edmx 檔案中以 XML 表示。在這種情況下，定義自訂摘要的屬性會新增至 EntityType 和Property 項目，表示資料模型中的實體類型和屬性。這些摘要自訂屬性不會在 [MC-CSDL]：概念結構定義檔案格式中定義，這是 Entity Framework 提供者用於定義資料模型的格式。因此，您必須在特定的結構描述命名空間中宣告摘要自訂屬性，定義為 m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata"。下列 XML 片段會顯示套用至 Products 實體類型之 Property 項目的摘要自訂屬性，定義 ProductName、ReorderLevel 和 UnitsInStock 屬性。

<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 屬性 (property) 值會同時顯示在 author 項目中並做為 ProductName 屬性 (property) 項目，而 UnitsInStock 屬性 (property) 則會顯示在自訂項目中，它具有其唯一的命名空間和做為屬性 (attribute) 的 ReorderLevel 屬性 (property)：

<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>

如需詳細資訊，請參閱 HOW TO：透過 Entity Framework 提供者自訂摘要 (WCF Data Services)。

注意：
由於 Entity Designer 不支援資料模型的副檔名，您必須手動修改包含資料模型的 XML 檔案。如需詳細資訊實體資料模型工具所產生之 .edmx 檔案的詳細資訊，請參閱 .edmx File Overview (Entity Framework)。

自訂摘要屬性

下表顯示可自訂摘要的 XML 屬性，您可以將它們加入至定義資料模型的概念結構定義語言 (CSDL) 中。這些屬性 (Attribute) 相當於搭配反映提供者使用之 EntityPropertyMappingAttribute 的屬性 (Property)。

屬性名稱	說明
FC_ContentKind	指示內容的類型。以下關鍵字可定義新聞訂閱方式內容類型。關鍵字說明 text 屬性值在摘要中會顯示為文字。 html 屬性值在摘要中會顯示為 HTML。 xhtml 屬性值在摘要中會顯示為 XML 格式的 HTML。這些關鍵字相當於搭配反映提供者使用之 SyndicationTextContentKind 列舉的值。使用 FC_NsPrefix 和 FC_NsUri 屬性時，將不支援此屬性。在您指定 FC_ContentKind 屬性的xhtml 值時，必須先確保屬性值會包含格式正確的 XML。資料服務會傳回未執行任何轉換的值。您還必須確保傳回之 XML 中的任何 XML 項目前置詞具備命名空間 URI 以及對應之摘要中所定義的前置詞。
FC_KeepInContent	指出參考的屬性值應包含在摘要的內容區段以及所對應的位置中。有效值為 true 和 false。若要使結果摘要與 WCF Data Services 的先前版本回溯相容，請指定 true 值，確保該值已包含在摘要的內容區段中。
FC_NsPrefix	非新聞訂閱方式對應中 XML 項目的命名空間前置詞。這個屬性必須搭配 FC_NsUri 屬性使用，不能搭配 FC_ContentKind 屬性使用。
FC_NsUri	非新聞訂閱方式對應中 XML 項目的命名空間 URI。這個屬性必須搭配 FC_NsPrefix 屬性使用，不能搭配 FC_ContentKind 屬性使用。
FC_SourcePath	此摘要對應規則套用的實體屬性路徑。僅支援用於 EntityType 項目中的屬性。 SourcePath 屬性不能直接參考複雜型別。針對複雜型別，您必須使用路徑運算式，其中的屬性名稱以反斜線 (/) 字元隔開。例如，下列值允許用於包含整數屬性 `Age` 和複雜屬性 `Address` 的實體類型 `Person`： `Age` `Address/Street` SourcePath 屬性不能設為包含空格或其他字元的值，這些在屬性名稱中不是有效字元。
FC_TargetPath	對應屬性之結果摘要的目標項目名稱。這個項目可以是元素規格定義的項目或自訂項目。以下關鍵字是預先定義的新聞訂閱目標路徑值，指向 OData 摘要中的特定位置。關鍵字說明 SyndicationAuthorEmail`atom:author` 項目的 `atom:email` 子項目。 SyndicationAuthorName`atom:author` 項目的 `atom:name` 子項目。 SyndicationAuthorUri`atom:author` 項目的 `atom:uri` 子項目。 SyndicationContributorEmail`atom:contributor` 項目的 `atom:email` 子項目。 SyndicationContributorName`atom:contributor` 項目的 `atom:name` 子項目。 SyndicationContributorUri`atom:contributor` 項目的 `atom:uri` 子項目。 SyndicationCustomProperty 自訂屬性項目。對應至自訂項目時，目標必須是路徑運算式，其中巢狀項目以反斜線 (/) 隔開，而且屬性以連字號 (@) 指定。下列範例中，字串 `UnitsInStock/@ReorderLevel` 將屬性值對應至名為 `ReorderLevel` 的屬性，位於根項目中名為 `UnitsInStock` 的子項目之上。 `<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" />` 當目標是自訂項目名稱時，也必須指定 FC_NsPrefix 和 FC_NsUri 屬性。 SyndicationPublished`atom:published` 項目。 SyndicationRights`atom:rights` 項目。 SyndicationSummary`atom:summary` 項目。 SyndicationTitle`atom:title` 項目。 SyndicationUpdated`atom:updated` 項目。這些關鍵字相當於搭配反映提供者使用之 SyndicationItemProperty 列舉的值。

注意：
屬性名稱和值需區分大小寫。屬性可套用至 EntityType 項目或一個或多個 Property 項目，但不能同時套用至兩者。

使用反映提供者自訂摘要

若要自訂使用反映提供者所實作之資料模型的摘要，請將一個或多個 EntityPropertyMappingAttribute 屬性執行個體新增至類別中，該類別表示資料模型中的實體類型。對應至摘要自訂屬性之 EntityPropertyMappingAttribute 類別的屬性已在上一節中說明。以下範例是 Order 型別的宣告，包含針對兩個屬性定義的自訂摘要對應。

注意：
此範例的資料模型定義於 HOW TO：使用反映提供者建立資料服務 (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>

如需詳細資訊，請參閱 HOW TO：透過反映提供者自訂摘要 (WCF Data Services)。

使用自訂資料服務提供者自訂摘要

如果要針對某個資源類型定義使用自訂資料服務提供者所定義之資料模型的摘要自訂，請在表示資料模型中實體類型的 ResourceType 上呼叫 AddEntityPropertyMappingAttribute。如需詳細資訊，請參閱自訂資料服務提供者 (WCF 資料服務)。

使用自訂摘要

當您的應用程式直接使用 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)

共用方式為