Feedanpassung (WCF Data Services)

Artikel
02/27/2011

WCF Data Services macht Daten mithilfe von Open Data Protocol (OData) als Feed verfügbar. OData unterstützt sowohl Atom- als auch JSON (JavaScript Object Notation)-Formate für Datenfeeds. Bei Verwendung eines Atom-Feeds stellt OData eine Standardmethode bereit, um Daten wie Entitäten und Beziehungen in ein XML-Format zu serialisieren, das in den Text der HTTP-Nachricht aufgenommen werden kann. OData definiert eine standardmäßige Entitätseigenschaftszuordnung zwischen den Daten, die in Entitäten und Atom-Elementen enthalten sind. Weitere Informationen finden Sie unter OData: AtomPub-Format.

In Ihrem Anwendungsszenario ist es möglicherweise erforderlich, dass die vom Datendienst zurückgegebenen Eigenschaftendaten benutzerdefiniert serialisiert werden anstatt im Standardfeedformat. Mit OData können Sie die Serialisierung in einem Datenfeed anpassen, damit Eigenschaften einer Entität nicht verwendeten Elementen und Attributen eines Eintrags oder benutzerdefinierten Elementen eines Eintrags im Feed zugeordnet werden können.

Hinweis:
Die Feedanpassung wird nur für Atom-Feeds unterstützt. Benutzerdefinierte Feeds werden nicht zurückgegeben, wenn das JSON (JavaScript Object Notation)-Format für den zurückgegebenen Feed angefordert wird.

Mit WCF Data Services können Sie eine alternative Entitätseigenschaftszuordnung für eine Atom-Nutzlast definieren, indem Sie Attribute manuell auf Entitätstypen im Datenmodell anwenden. Der Datenquellenanbieter des Datendiensts bestimmt, wie diese Attribute angewendet werden.

Hinweis:
Wenn Sie benutzerdefinierte Feeds definieren, müssen Sie gewährleisten, dass alle Entitätseigenschaften, für die benutzerdefinierte Zuordnungen definiert wurden, in der Projektion enthalten sind. Wenn eine zugeordnete Entitätseigenschaft nicht in der Projektion enthalten ist, könnten Datenverluste auftreten. Weitere Informationen finden Sie unter Abfrageprojektionen (WCF Data Services).

Anpassen von Feeds mit dem Entity Framework-Anbieter

Das mit dem Entity Framework -Anbieter verwendete Datenmodell wird in der EDMX-Datei als XML dargestellt. In diesem Fall werden dem EntityType-Element und dem Property-Element, die Entitätstypen und Eigenschaften im Datenmodell darstellen, die Attribute hinzugefügt, die benutzerdefinierte Feeds definieren. Diese Feedanpassungsattribute werden nicht im [MC-CSDL]: Conceptual Schema Definition File Format formatiert, dem Format, das der Entity Framework -Anbieter zum Definieren des Datenmodells verwendet. Daher müssen Sie Feedanpassungsattribute in einem bestimmten Schemanamespace deklarieren, der als m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata" definiert wird. Das folgende XML-Fragment zeigt auf die Property-Elemente des Products-Entitätstyps angewendete Feedanpassungsattribute, die die Eigenschaften ProductName, ReorderLevel und UnitsInStock definieren.

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

Diese Attribute erzeugen den folgenden benutzerdefinierten Datenfeed für die Products-Entitätenmenge. Im benutzerdefinierten Datenfeed wird der ProductName-Eigenschaftswert im author-Element und als ProductName-Eigenschaftselement angezeigt, und die UnitsInStock-Eigenschaft wird in einem benutzerdefinierten Element mit einem eigenen eindeutigen Namespace und mit der ReorderLevel-Eigenschaft als Attribut angezeigt:

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

Weitere Informationen finden Sie unter Gewusst wie: Anpassen von Feeds mit dem Entity Framework-Anbieter (WCF Data Services).

Hinweis:
Da Erweiterungen des Datenmodells nicht vom Entity Designer unterstützt werden, müssen Sie die XML-Datei, die das Datenmodell enthält, manuell ändern. Weitere Informationen über die von den Entity Data Model -Tools generierte EDMX-Datei finden Sie unter .edmx File Overview (Entity Framework).

Benutzerdefinierte Feedattribute

In der folgenden Tabelle werden die XML-Attribute angezeigt, die Feeds anpassen, die Sie der konzeptionellen Schemadefinitionssprache (CSDL) hinzufügen können, die das Datenmodell definiert. Diese Attribute entsprechen den Eigenschaften des mit dem Reflektionsanbieter verwendeten EntityPropertyMappingAttribute.

Attributname	Beschreibung
FC_ContentKind	Gibt den Inhaltstyp an. Die folgenden Schlüsselwörter definieren Syndication-Inhaltstypen. Schlüsselwort Beschreibung text Der Eigenschaftswert wird im Feed als Text angezeigt. html Der Eigenschaftswert wird im Feed als HTML angezeigt. xhtml Der Eigenschaftswert wird im Feed als XML-formatierte HTML angezeigt. Diese Schlüsselwörter entsprechen den Werten der mit dem Reflektionsanbieter verwendeten SyndicationTextContentKind-Enumeration. Dieses Attribut wird nicht unterstützt, wenn das FC_NsPrefix-Attribut und das FC_NsUri-Attribut verwendet werden. Wenn Sie den Wert xhtml für das FC_ContentKind-Attribut angeben, müssen Sie sicherstellen, dass der Eigenschaftswert ordnungsgemäß formatiertes XML enthält. Der Datendienst gibt den Wert zurück, ohne irgendwelche Transformationen auszuführen. Sie müssen auch sicherstellen, dass alle XML-Elementpräfixe im zurückgegebenen XML einen Namespace-URI und ein Präfix haben, die im zugeordneten Feed definiert sind.
FC_KeepInContent	Gibt an, dass der Eigenschaftswert, auf den verwiesen wird, sowohl im Inhaltsabschnitt des Feeds als auch im zugeordneten Speicherort enthalten sein soll. Gültige Werte sind true und false. Um den resultierenden Feed abwärtskompatibel mit früheren Versionen von WCF Data Services zu machen, geben Sie den Wert true an. Damit wird sichergestellt, dass der Wert in den Inhaltsabschnitt des Feeds aufgenommen wird.
FC_NsPrefix	Das Namespacepräfix des XML-Elements in einer Nicht-Syndication-Zuordnung. Dieses Attribut muss zusammen mit dem FC_NsUri-Attribut und kann nicht zusammen mit dem FC_ContentKind-Attribut verwendet werden.
FC_NsUri	Der Namespace-URI des XML-Elements in einer Nicht-Syndication-Zuordnung. Dieses Attribut muss zusammen mit dem FC_NsPrefix-Attribut und kann nicht zusammen mit dem FC_ContentKind-Attribut verwendet werden.
FC_SourcePath	Der Pfad der Eigenschaft der Entität, für die diese Feedzuordnungsregel gilt. Dieses Attribut wird nur unterstützt, wenn es in einem EntityType-Element verwendet wird. Die SourcePath-Eigenschaft kann nicht direkt auf einen komplexen Typ verweisen. Für komplexe Typen müssen Sie einen Pfadausdruck verwenden, in dem Eigenschaftennamen durch einen umgekehrten Schrägstrich (/) getrennt werden. Beispielsweise sind die folgenden Werte mit der Integer-Eigenschaft `Age` und der komplexen Eigenschaft `Address` für den Entitätstyp `Person` zugelassen: `Age` `Address/Street` Die SourcePath-Eigenschaft kann nicht auf einen Wert festgelegt werden, der ein Leerzeichen oder ein anderes Zeichen enthält, das in einem Eigenschaftennamen ungültig ist.
FC_TargetPath	Der Name des Zielelements des resultierenden Feeds zum Zuordnen der Eigenschaft. Dieses Element kann ein von der Atom-Spezifikation definiertes Element oder ein benutzerdefiniertes Element sein. Die folgenden Schlüsselwörter sind vordefinierte Syndication Zielpfad-Werte, die auf bestimmte Positionen in einem OData -Feed zeigen. Schlüsselwort Beschreibung SyndicationAuthorEmail Das untergeordnete `atom:email`-Element des `atom:author`-Elements. SyndicationAuthorName Das untergeordnete `atom:name`-Element des `atom:author`-Elements. SyndicationAuthorUri Das untergeordnete `atom:uri`-Element des `atom:author`-Elements. SyndicationContributorEmail Das untergeordnete `atom:email`-Element des `atom:contributor`-Elements. SyndicationContributorName Das untergeordnete `atom:name`-Element des `atom:contributor`-Elements. SyndicationContributorUri Das untergeordnete `atom:uri`-Element des `atom:contributor`-Elements. SyndicationCustomProperty Ein benutzerdefiniertes Eigenschaftenelement. Bei der Zuordnung zu einem benutzerdefinierten Element muss das Ziel ein Pfadausdruck sein, in dem geschachtelte Elemente durch einen umgekehrten Schrägstrich (/) getrennt und Attribute durch ein kaufmännisches Und-Zeichen (@) angegeben werden. Im folgenden Beispiel ordnet die Zeichenfolge `UnitsInStock/@ReorderLevel` einen Eigenschaftswert dem Attribut `ReorderLevel` auf dem untergeordneten Element `UnitsInStock` des Stammeintragselements zu. `<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" />` Wenn das Ziel ein benutzerdefinierter Elementname ist, müssen das FC_NsPrefix-Attribut und das FC_NsUri-Attribut ebenfalls angegeben werden. SyndicationPublished Das `atom:published`-Element. SyndicationRights Das `atom:rights`-Element. SyndicationSummary Das `atom:summary`-Element. SyndicationTitle Das `atom:title`-Element. SyndicationUpdated Das `atom:updated`-Element. Diese Schlüsselwörter entsprechen den Werten der mit dem Reflektionsanbieter verwendeten SyndicationItemProperty-Enumeration.

Hinweis:
Bei Attributnamen und -werten muss die Groß-/Kleinschreibung beachtet werden. Attribute können entweder nur auf das EntityType-Element oder auf ein oder mehrere Property-Elemente angewendet werden.

Anpassen von Feeds mit dem Reflektionsanbieter

Zum Anpassen von Feeds für ein mit dem Reflektionsanbieter implementiertes Datenmodell fügen Sie den Klassen, die Entitätstypen im Datenmodell darstellen, eine oder mehrere Instanzen des EntityPropertyMappingAttribute-Attributs hinzu. Die Eigenschaften der EntityPropertyMappingAttribute-Klasse entsprechen den Feedanpassungsattributen, die im vorherigen Abschnitt beschrieben werden. Nachfolgend ein Beispiel für die Deklaration des Order-Typs, wobei die benutzerdefinierte Feedzuordnung für beide Eigenschaften definiert ist.

Hinweis:
Das Datenmodell für dieses Beispiel wird im Thema Gewusst wie: Erstellen eines Datendiensts mithilfe des Reflektionsanbieters (WCF Data Services) definiert.

<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

Diese Attribute erzeugen den folgenden benutzerdefinierten Datenfeed für die Orders-Entitätenmenge. In diesem benutzerdefinierten Feed wird der OrderId -Eigenschaftswert nur im title-Element des entry-Eigenschaftswerts angezeigt, und der Customer-Eigenschaftswert wird im author-Element und als Customer-Eigenschaftselement angezeigt:

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

Weitere Informationen finden Sie unter Gewusst wie: Anpassen von Feeds mit dem Reflektionsanbieter (WCF Data Services).

Anpassen von Feeds mithilfe eines benutzerdefinierten Datendienstanbieters

Die Feedanpassung für ein Datenmodell, das durch die Verwendung eines benutzerdefinierten Datendienstanbieters definiert ist, wird für einen Ressourcentyp definiert, indem das AddEntityPropertyMappingAttribute auf dem ResourceType aufgerufen wird, der einen Entitätstyp im Datenmodell darstellt. Weitere Informationen finden Sie unter Benutzerdefinierte Datendienstanbieter (WCF Data Services).

Verwenden von benutzerdefinierten Feeds

Wenn die Anwendung einen OData -Feed direkt verwendet, muss sie alle benutzerdefinierten Elemente und Attribute im zurückgegebenen Feed verarbeiten können. Wenn Sie benutzerdefinierte Feeds im Datenmodell unabhängig vom Datendienstanbieter implementiert haben, gibt der $metadata-Endpunkt benutzerdefinierte Feedinformationen als benutzerdefinierte Feedattribute in der vom Datendienst zurückgegebenen CSDL zurück. Wenn Sie das Dialogfeld Dienstverweis hinzufügen oder das Tool datasvcutil.exe zum Generieren von Clientdatendienstklassen verwenden, wird mit den benutzerdefinierten Feedattributen gewährleistet, dass Anforderungen und Antworten an den Datendienst richtig behandelt werden.

Überlegungen zur Feedanpassung

Beim Definieren von benutzerdefinierten Feedzuordnungen sollten Sie Folgendes betrachten.

Der WCF Data Services -Client behandelt zugeordnete Elemente in einem Feed als leer, wenn sie nur Leerstellen enthalten. Deswegen werden zugeordnete Elemente, die nur Leerstellen enthalten, nicht auf dem Client mit den gleichen Leerstellen materialisiert. Um diese Leerstellen auf dem Client beizubehalten, müssen Sie den Wert von KeepInContext im Feedzuordnungsattribut auf true festlegen.

Versionsanforderungen

Die Feedanpassung hat die folgenden Anforderungen an die OData -Protokollversion:

Die Feedanpassung erfordert, dass der Client und der Datendienst Version 2.0 des OData -Protokolls und höhere Versionen unterstützt.

Weitere Informationen finden Sie unter Verwenden mehrerer Versionen von WCF Data Services.

Siehe auch

Konzepte

Reflektionsanbieter (WCF Data Services)
Entity Framework-Anbieter (WCF Data Services)