Поделиться через

Настройка канала (службы WCF Data Services)

  • Статья

Службы Службы WCF Data Services используют Протокол Open Data Protocol (OData) для предоставления данных в виде канала. OData поддерживает форматы Atom и нотации объектов JavaScript (JSON) для каналов данных. При использовании канала Atom OData предоставляет стандартный метод сериализации данных, таких как сущности и связи, в формате XML, после чего они могут быть включены в текст HTTP-сообщения. Службы OData  определяют сопоставление «сущность-свойство» по умолчанию между данными, содержащимися в сущностях, и элементами Atom. Дополнительные сведения см. в разделе OData: формат Atom.

Возможна ситуация, когда требуется сериализация данных свойства, возвращаемых службой данных, в настраиваемом виде, а не в стандартном формате канала. С помощью OData можно настроить сериализацию в канале данных так, чтобы свойства сущности сопоставлялись с неиспользуемыми элементами и атрибутами сущности или с пользовательскими элементами записи в канале.

Ee373839.note(ru-ru,VS.100).gifПримечание
Настройка канала поддерживается только для каналов Atom. Специализированные каналы не возвращаются при запросе в формате JSON.

С помощью Службы WCF Data Services можно определить альтернативное сопоставление «сущность-свойство» для полезных данных канала Atom путем применения атрибутов к типам сущностей в модели данных вручную. Поставщик источника данных службы данных определяет метод применения этих атрибутов.

Ee373839.Important(ru-ru,VS.100).gif Примечание
При определении специализированных каналов необходимо убедиться, что все свойства сущности, которые имеют определенные пользовательские сопоставления, включены в проекцию. Если сопоставленное свойство сущности не включено в проекцию, может произойти потеря данных. Дополнительные сведения см. в разделе Проекции запросов (службы WCF Data Services).

Настройка каналов с помощью поставщика Entity Framework

Модель данных, используемая с поставщиком Entity Framework , представлена в виде XML в EDMX-файле. В данном случае атрибуты, определяющие специализированные каналы, добавляются к элементам EntityType и Property, представляющим типы сущностей и свойства в модели данных. Эти атрибуты настройки потока не определены в [MC-CSDL]: файловом формате определения концептуальной схемы, который является форматом, используемым поставщиком Entity Framework для определения модели данных. Поэтому атрибуты настройки канала должны быть объявлены в специальном пространстве имен схемы, определенном как m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata". Следующий фрагмент XML иллюстрирует применение атрибутов настройки канала к элементам Property типа сущности Products, определяющего свойства 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>

Дополнительные сведения см. в разделе Как настроить каналы с помощью поставщика Entity Framework (службы WCF Data Services).

Ee373839.note(ru-ru,VS.100).gifПримечание
Поскольку расширения для модели данных не поддерживаются конструктором сущностей, следует вручную изменить XML-файл, содержащий модель данных. Дополнительные сведения EDMX-файле, создаваемом средствами модель EDM (сущностная модель данных) , см. в разделе .edmx File Overview (Entity Framework).

Настраиваемые атрибуты канала

В следующей таблице приведены XML-атрибуты, с помощью которых можно настроить каналы, добавляемые в язык определения концептуальной схемы (CSDL) с определением модели данных. Эти атрибуты эквивалентны свойствам объекта EntityPropertyMappingAttribute, используемым при работе с поставщиком отражения.

Имя атрибута Описание

FC_ContentKind

Указывает тип содержимого. Следующие ключевые слова определяют типы содержимого синдикации.

Ключевое слово Описание
text Значение свойства отображается в канале в виде текста.
html Значение свойства отображается в канале в формате HTML.
xhtml Значение свойства отображается в канале в виде HTML, отформатированного как XML.

Эти ключевые слова эквивалентны значениям перечисления SyndicationTextContentKind, используемым при работе с поставщиком отражения.

Этот атрибут не поддерживается, если используются атрибуты FC_NsPrefix и FC_NsUri.

Если задается значение xhtml для атрибута FC_ContentKind, то необходимо убедиться, что значение свойства содержит XML в правильном формате. Служба данных возвращает значение, не выполняя никаких преобразований. Необходимо также убедиться, что префиксы элементов XML в возвращаемом XML имеют URI-код пространства имен и префикс, определенный в сопоставленном канале.

FC_KeepInContent

Указывает, что значение упомянутого свойства должно быть включено как в раздел содержимого канала, так и в сопоставленное расположение. Допустимые значения: true и false. Чтобы результирующий канал оставался обратно совместимым с более ранними версиями Службы WCF Data Services , укажите значение true, чтобы значение гарантированно включалось в раздел содержимого канала. 

FC_NsPrefix

Префикс пространства имен элемента XML в сопоставлении, не включенном в синдикацию. Этот атрибут должен быть использован с атрибутом FC_NsUri и не может быть использован с атрибутом FC_ContentKind.

FC_NsUri

URI пространства имен элемента XML в сопоставлении, не включенном в синдикацию. Этот атрибут должен быть использован с атрибутом FC_NsPrefix и не может быть использован с атрибутом FC_ContentKind.

FC_SourcePath

Путь свойства сущности, к которой применяется данное правило сопоставления. Этот атрибут поддерживается только при использовании в элементе EntityType.

Свойство SourcePath не может непосредственно ссылаться на сложный тип. Для сложных типов необходимо использовать выражение пути, свойства в котором разделены символом косой черты (/). Например, следующие значения допустимы для типа сущности Person с целым свойством Age и сложным свойством Address:

  • Age

  • Address/Street

Свойству SourcePath нельзя задать значение, содержащее пробел или любой символ, недопустимый в имени свойства.

FC_TargetPath

Имя целевого элемента результирующего канала, с которым сопоставляется данное свойство. Этот элемент может быть элементом, определенным в спецификации Atom, либо специализированным элементом.

Следующие ключевые слова соответствуют заранее заданным значениям целевых путей синдикации, указывающим на конкретные расположения в канале OData .

Ключевое слово Описание
SyndicationAuthorEmail Дочерний элемент atom:email элемента atom:author.
SyndicationAuthorName Дочерний элемент atom:name элемента atom:author.
SyndicationAuthorUri Дочерний элемент atom:uri элемента atom:author.
SyndicationContributorEmail Дочерний элемент atom:email элемента atom:contributor.
SyndicationContributorName Дочерний элемент atom:name элемента atom:contributor.
SyndicationContributorUri Дочерний элемент atom:uri элемента atom:contributor.
SyndicationCustomProperty
Элемент пользовательского свойства. При сопоставлении с пользовательским элементом целевой объект должен быть выражением пути, в котором вложенные элементы разделяются обратной косой чертой (/), а атрибуты определяются амперсандом (@). В следующем примере строка UnitsInStock/@ReorderLevel сопоставляет значение свойства с атрибутом с именем ReorderLevel у обозначенного именем UnitsInStock дочернего элемента корневого элемента entry. 
<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, используемым при работе с поставщиком отражения.
Ee373839.note(ru-ru,VS.100).gifПримечание
В именах и значениях атрибутов учитывается регистр. Атрибуты можно применять либо к элементу EntityType, либо к одному или нескольким элементам Property, но не к тем и другим одновременно.

Настройка каналов с помощью поставщика отражения

Для настройки каналов в модели данных, реализованной с использованием поставщика отражения, добавьте один или несколько экземпляров атрибута EntityPropertyMappingAttribute к классам, представляющим типы сущностей в модели данных. Свойства класса EntityPropertyMappingAttribute соответствуют атрибутам настройки канала, описанным в предыдущем разделе. Следующий пример иллюстрирует объявление типа Order с сопоставлением специализированного канала, определенным для обоих свойств.

Ee373839.note(ru-ru,VS.100).gifПримечание
Модель данных для этого примера определена в разделе Как создать службу данных с помощью поставщика отражения (службы 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 отображается только в элементе title объекта entry, а значение свойства 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).

Настройка каналов с помощью специализированного поставщика служб данных

Настройка каналов для модели данных, определенной с использованием специализированного поставщика служб данных, осуществляется для типа ресурса путем вызова метода AddEntityPropertyMappingAttribute для типа ResourceType, который представляет тип сущности в модели данных. Дополнительные сведения см. в разделе Специализированные поставщики служб данных (службы 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)