通过

源自定义（WCF 数据服务）

  • 项目

WCF 数据服务 使用开放式数据协议 (OData) 将数据作为源公开。OData 支持数据源采用 Atom 和 JavaScript 对象表示法 (JSON) 格式。当使用 Atom 源时，OData 会提供一种标准方法来将数据（如实体和关系）序列化为可包含在 HTTP 消息正文中的 XML 格式。OData 定义实体中包含的数据与 Atom 元素之间的默认实体-属性映射。有关更多信息，请参见 OData：Atom 格式。

您的应用程序方案可能要求以自定义方式而非标准源格式序列化数据服务返回的属性数据。通过 OData ，您可以在数据源中自定义序列化，以便可以将实体属性映射到源中某项的未使用元素和特性或自定义元素。

Ee373839.note(zh-cn,VS.100).gif注意：
只有 Atom 源才支持源自定义。当为返回的源请求 JSON 格式时，不会返回自定义源。

利用 WCF 数据服务 ，您可以通过向数据模型中的实体类型手动应用特性，为 Atom 负载定义替代实体-属性映射。数据服务的数据源提供程序确定应当如何应用这些特性。

Ee373839.Important(zh-cn,VS.100).gif 注意：
定义自定义源时，必须保证已定义自定义映射的所有实体属性都包含在投影中。如果投影中不包含某个已映射的实体属性，则可能会丢失数据。有关更多信息，请参见查询投影（WCF 数据服务）。

使用实体框架提供程序自定义源

在 .edmx 文件中，用于实体框架 提供程序的数据模型以 XML 格式表示。在这种情况下，用于定义自定义源的特性将会添加到表示数据模型中的实体类型和属性的 EntityType 和 Property 元素中。这些源自定义特性不是以实体框架 提供程序用于定义数据模型的 [MC-CSDL]：概念架构定义文件格式定义的。因此，必须在某个特定的架构命名空间中声明源自定义特性，此架构命名空间应按 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 属性值同时显示在 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>

有关更多信息，请参见如何：使用实体框架提供程序自定义源（WCF 数据服务）。

Ee373839.note(zh-cn,VS.100).gif注意：
由于实体设计器不支持数据模型扩展，因此必须手动修改包含数据模型的 XML 文件。有关由实体数据模型 工具生成的 .edmx 文件的更多信息，请参见 .edmx File Overview (Entity Framework)。

自定义源特性

下表列出了一些 XML 特性，这些特性自定义可添加到用于定义数据模型的概念架构定义语言 (CSDL) 的源。这些特性等效于用于反射提供程序的 EntityPropertyMappingAttribute 的属性。

特性名 说明

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 数据服务 的早期版本向后兼容，请指定值 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

属性将映射到的结果源中的目标元素的名称。此元素可以是按 Atom 规范定义的元素，也可以是自定义元素。

以下关键字是指向 OData 源中特定位置的预定义联合目标路径值。

关键字 说明
SyndicationAuthorEmailatom:author 元素的 atom:email 子元素。
SyndicationAuthorNameatom:author 元素的 atom:name 子元素。
SyndicationAuthorUriatom:author 元素的 atom:uri 子元素。
SyndicationContributorEmailatom:contributor 元素的 atom:email 子元素。
SyndicationContributorNameatom:contributor 元素的 atom:name 子元素。
SyndicationContributorUriatom:contributor 元素的 atom:uri 子元素。
SyndicationCustomProperty
自定义属性元素。 映射到自定义元素时，目标必须是路径表达式，在此路径表达式中，使用反斜杠 (/) 分隔嵌套元素，并使用 @ 指定特性。在以下示例中，字符串 UnitsInStock/@ReorderLevel 将属性值映射到根项元素的 UnitsInStock 子元素上的 ReorderLevel 特性。 
<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 特性。
SyndicationPublishedatom:published 元素。
SyndicationRightsatom:rights 元素。
SyndicationSummaryatom:summary 元素。
SyndicationTitleatom:title 元素。
SyndicationUpdatedatom:updated 元素。

这些关键字等效于用于反射提供程序的 SyndicationItemProperty 枚举的值。
Ee373839.note(zh-cn,VS.100).gif注意：
特性名称和值是区分大小写的。特性可以应用于 EntityType 元素，也可以应用于一个或多个 Property 元素，但不能同时应用于二者。

使用反射提供程序自定义源

若要为使用反射提供程序实现的数据模型自定义源，请将 EntityPropertyMappingAttribute 特性的一个或多个实例添加到表示数据模型中的实体类型的类中。EntityPropertyMappingAttribute 类的属性对应于在上一节中介绍的源自定义特性。以下是 Order 类型的声明示例，该示例为两个属性定义了自定义源映射。

Ee373839.note(zh-cn,VS.100).gif注意：
如何：使用反射提供程序创建数据服务（WCF 数据服务） 主题中定义了此示例的数据模型。 

<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 数据服务）。

使用自定义数据服务提供程序自定义源

通过对表示数据模型中实体类型的 ResourceType 调用 AddEntityPropertyMappingAttribute，可以为资源类型定义通过使用自定义数据服务提供程序定义的数据模型的源自定义。有关更多信息，请参见自定义数据服务提供程序（WCF 数据服务）。

使用自定义源

如果应用程序直接使用 OData 源，则它必须能够处理返回的源中的所有自定义元素和特性。如果已在数据模型中实现自定义源，不管数据服务提供程序如何，$metadata 终结点都会返回自定义源信息，并作为数据服务返回的 CSDL 中的自定义源特性。当使用**“添加服务引用”**对话框或 datasvcutil.exe 工具生成客户端数据服务类时，使用自定义源特性可以保证以正确方式处理对数据服务的请求和响应。

源自定义注意事项

定义自定义源映射时，应考虑下列事项。

  • 当源中的映射元素只包含空白时，WCF 数据服务 客户端将这些元素视为空。因此，在具有相同空白的客户端上不会具体化只包含空白的映射元素。为了防止客户端上包含这种空白，在源映射特性中，必须将 KeepInContext 的值设置为 true。

版本控制要求

源自定义具有以下 OData 协议版本控制要求：

  • 源自定义要求客户端和数据服务都支持 OData 协议的 2.0 版本以及更高版本。

有关更多信息，请参见使用 WCF 数据服务的多个版本。

另请参见

概念

反射提供程序（WCF 数据服务）
实体框架提供程序（WCF 数据服务）