Personnalisation de flux (WCF Data Services)

Article
02/27/2011

Services de données WCF utilise le Protocole OData (Open Data) pour exposer des données sous forme de flux. OData prend en charge les formats Atom et JSON (JavaScript Object Notation) pour les flux de données. Lorsque vous utilisez un flux de données Atom, OData fournit une méthode standard pour sérialiser les données, telles que les entités et les relations, dans un format XML qui peut être inclus dans le corps du message HTTP. OData définit un mappage de propriété d'entité par défaut entre les données contenues dans les entités et les éléments Atom. Pour plus d'informations, consultez OData: Atom Format (en anglais).

Vous pouvez avoir un scénario d'application qui requiert que les données de propriété retournées par le service des données soient sérialisées de façon personnalisée plutôt qu'au format de flux standard. Avec OData , vous pouvez personnaliser la sérialisation dans un flux de données afin que les propriétés d'une entité puissent être mappées aux éléments inutilisés et aux attributs d'une entrée ou aux éléments personnalisés d'une entrée du flux.

Remarque :
La personnalisation de flux est prise en charge uniquement pour les flux Atom. Les flux personnalisés ne sont pas retournés lorsque le format JSON est demandé pour le flux retourné.

Avec Services de données WCF , vous pouvez définir un autre mappage de propriété pour les charges utiles Atom en appliquant manuellement des attributs aux types d'entité dans le modèle de données. Le fournisseur de sources de données du service de données détermine le mode d'application de ces attributs.

Remarque :
Lorsque vous définissez des flux personnalisés, vous devez vérifier que toutes les propriétés de l'entité qui ont des mappages personnalisés définis sont incluses dans la projection. Lorsqu'une propriété d'entité mappée n'est pas incluse dans la projection, une perte de données peut se produire. Pour plus d'informations, consultez Projections de requête (WCF Data Services).

Personnalisation de flux avec le fournisseur Entity Framework

Le modèle de données utilisé avec le fournisseur Entity Framework est représenté sous la forme de code XML dans le fichier .edmx. Dans ce cas, les attributs qui définissent des flux personnalisés sont ajoutés aux éléments Property et EntityType qui représentent des types et des propriétés d'entité dans le modèle de données. Ces attributs de personnalisation de flux ne sont pas définis dans [MC-CSDL]: Conceptual Schema Definition File Format (en anglais) qui est le format que le fournisseur Entity Framework utilise pour définir le modèle de données. Par conséquent, vous devez déclarer les attributs de personnalisation de flux dans un espace de noms de schéma spécifique défini sous la forme m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata". Le fragment XML suivant affiche des attributs de personnalisation de flux appliqués aux éléments Property du type d'entité Products qui définissent les propriétés ProductName, ReorderLevel et 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"
    />

Ces attributs produisent le flux de données personnalisé suivant pour le jeu d'entités Products. Dans le flux de données personnalisé, la valeur de la propriété ProductName s'affiche à la fois dans l'élément author et comme élément de propriété ProductName, et la propriété UnitsInStock s'affiche dans un élément personnalisé possédant son propre espace de noms unique et avec la propriété ReorderLevel comme attribut :

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

Pour plus d'informations, consultez Procédure : personnaliser des flux avec le fournisseur Entity Framework (WCF Data Services).

Remarque :
Étant donné que les extensions au modèle de données ne sont pas prises en charge par le Concepteur d'entités, vous devez modifier manuellement le fichier XML qui contient le modèle de données. Pour plus d'informations sur le sujet suivant le fichier .edmx généré par les outils Entity Data Model , consultez .edmx File Overview (Entity Framework).

Attributs de flux personnalisés

La table suivante affiche les attributs XML qui personnalisent les flux que vous pouvez ajouter au CSDL (Conceptual Schema Definition Language) qui définit le modèle de données. Ces attributs sont équivalents aux propriétés de EntityPropertyMappingAttribute utilisées avec le fournisseur de réflexion.

Nom de l'attribut	Description
FC_ContentKind	Indique le type de contenu. Les mots clés suivants définissent des types de contenu de syndication. Mot clé Description text La valeur de propriété est affichée dans le flux comme texte. html La valeur de propriété est affichée dans le flux comme code HTML. xhtml La valeur de propriété est affichée dans le flux comme code HTML au format XML. Ces mots clés sont équivalents aux valeurs de l'énumération SyndicationTextContentKind utilisées avec le fournisseur de réflexion. Cet attribut n'est pas pris en charge lorsque les attributs FC_NsPrefix et FC_NsUri sont utilisés. Lorsque vous spécifiez une valeur de xhtml pour l'attribut FC_ContentKind, vous devez vérifier que la valeur de propriété contient le formatage XML approprié. Le service de données retourne la valeur sans effectuer de transformations. Vous devez également vérifier que tous les préfixes d'élément XML dans le XML retourné ont un URI d'espace de noms et le préfixe défini dans le flux mappé.
FC_KeepInContent	Indique que la valeur de propriété référencée doit être incluse à la fois dans la section de contenu du flux et dans l'emplacement mappé. Les valeurs valides sont true et false. Pour assurer la compatibilité en amont du flux résultant avec les versions antérieures d'Services de données WCF , spécifiez une valeur true pour être certain que la valeur est incluse dans la section de contenu du flux.
FC_NsPrefix	Préfixe d'espace de noms de l'élément XML dans un mappage de non-syndication. Cet attribut doit être utilisé avec l'attribut FC_NsUri et ne peut pas être utilisé avec l'attribut FC_ContentKind.
FC_NsUri	URI d'espace de noms de l'élément XML dans un mappage de non-syndication. Cet attribut doit être utilisé avec l'attribut FC_NsPrefix et ne peut pas être utilisé avec l'attribut FC_ContentKind.
FC_SourcePath	Chemin d'accès de la propriété de l'entité à laquelle s'applique cette règle de mappage de flux. Cet attribut est pris en charge uniquement lorsqu'il est utilisé dans un élément EntityType. La propriété SourcePath ne peut pas référencer directement de type complexe. Pour les types complexes, vous devez utiliser une expression de chemin d'accès où les noms de propriété sont séparés par une barre oblique inverse (/). Par exemple, les valeurs suivantes sont autorisées pour un type d'entité `Person` avec une propriété entière `Age` et une propriété complexe `Address`: `Age` `Address/Street` La propriété SourcePath ne peut pas avoir une valeur qui contient un espace ou un autre caractère qui n'est pas valide dans un nom de propriété.
FC_TargetPath	Nom de l'élément cible du flux résultant pour mapper la propriété. Cet élément peut être un élément défini par la spécification Atom ou un élément personnalisé. Les mots clés suivants sont des valeurs cible-chemin d'accès de syndication prédéfinies qui pointent vers un emplacement spécifique dans un flux OData . Mot clé Description SyndicationAuthorEmail L'élément enfant `atom:email` de l'élément `atom:author`. SyndicationAuthorName L'élément enfant `atom:name` de l'élément `atom:author`. SyndicationAuthorUri L'élément enfant `atom:uri` de l'élément `atom:author`. SyndicationContributorEmail L'élément enfant `atom:email` de l'élément `atom:contributor`. SyndicationContributorName L'élément enfant `atom:name` de l'élément `atom:contributor`. SyndicationContributorUri L'élément enfant `atom:uri` de l'élément `atom:contributor`. SyndicationCustomProperty Élément de propriété personnalisé. Lors du mappage à un élément personnalisé, la cible doit être une expression de chemin d'accès où les éléments imbriqués sont séparés par une barre oblique inverse (/) et les attributs sont spécifiés par une esperluette (@). Dans l'exemple suivant, la chaîne `UnitsInStock/@ReorderLevel` mappe une valeur de propriété à un attribut nommé `ReorderLevel` sur un élément enfant nommé `UnitsInStock` de l'élément d'entrée racine. `<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" />` Lorsque la cible est un nom d'élément personnalisé, les attributs FC_NsPrefix et FC_NsUri doivent également être spécifiés. SyndicationPublished Élément `atom:published`. SyndicationRights Élément `atom:rights`. SyndicationSummary Élément `atom:summary`. SyndicationTitle Élément `atom:title`. SyndicationUpdated Élément `atom:updated`. Ces mots clés sont équivalents aux valeurs de l'énumération SyndicationItemProperty utilisées avec le fournisseur de réflexion.

Remarque :
Les noms et valeurs d'attributs respectent la casse. Les attributs peuvent être appliqués à l'élément EntityType ou à un ou plusieurs éléments Property, mais pas aux deux.

Personnalisation des flux avec le fournisseur de réflexion

Pour personnaliser des flux pour un modèle de données ayant été implémenté à l'aide du fournisseur de réflexion, ajoutez une ou plusieurs instances de l'attribut EntityPropertyMappingAttribute aux classes qui représentent des types d'entité dans le modèle de données. Les propriétés de la classe EntityPropertyMappingAttribute correspondent aux attributs de personnalisation du flux décrits dans la section précédente. Voici un exemple de la déclaration du type Order avec le mappage de flux personnalisé défini pour les deux propriétés.

Remarque :
Le modèle de données de cet exemple est défini dans la rubrique Procédure : créer un service de données à l'aide du fournisseur de réflexion (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

Ces attributs produisent le flux de données personnalisé suivant pour le jeu d'entités Orders. Dans ce flux personnalisé, la valeur de propriété OrderId s'affiche uniquement dans l'élément title de entry et la valeur de propriété Customer s'affiche à la fois dans l'élément author et comme l'élément de propriété 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>

Pour plus d'informations, consultez Procédure : personnaliser des flux avec le fournisseur de réflexion (WCF Data Services).

Personnalisation de flux avec un fournisseur de services de données personnalisé

La personnalisation de flux pour un modèle de données défini à l'aide d'un fournisseur de services de données personnalisé est définie pour un type de ressource en appelant le AddEntityPropertyMappingAttribute sur l'objet ResourceType qui représente un type d'entité dans le modèle de données. Pour plus d'informations, consultez Fournisseurs de services de données personnalisés (WCF Data Services).

Consommation de flux personnalisés

Lorsque votre application consomme directement un flux OData , elle doit pouvoir traiter les éléments et les attributs personnalisés dans le flux de données retourné. Lorsque vous avez implémenté des flux personnalisés dans votre modèle de données, indépendamment du fournisseur de services de données, le point de terminaison $metadata retourne des informations de flux personnalisées sous la forme d'attributs de flux personnalisés dans le CSDL retourné par le service de données. Lorsque vous utilisez la boîte de dialogue Ajouter une référence de service ou l'outil datasvcutil.exe pour générer des classes de service de données client, les attributs de flux personnalisés sont utilisés pour garantir que les demandes et les réponses au service de données sont correctement gérées.

Considérations de personnalisation de flux

Tenez compte des considérations suivantes lorsque vous définissez des mappages de flux personnalisés.

Le client Services de données WCF traite les éléments mappés dans un flux comme s'ils étaient vides lorsqu'ils contiennent seulement un espace blanc. De ce fait, les éléments mappés qui contiennent seulement un espace blanc ne sont pas matérialisés sur le client avec le même espace blanc. Pour conserver cet espace blanc sur le client, vous devez définir la valeur de KeepInContext sur true dans l'attribut de mappage de flux.

Conditions requises pour le contrôle de version

La personnalisation de flux a les conditions requises pour le contrôle de version de protocole OData suivantes :

La personnalisation de flux requiert que le client et le service de données prennent en charge les versions 2.0 et ultérieures du protocole OData .

Pour plus d'informations, consultez Utilisation de plusieurs versions de WCF Data Services.

Voir aussi

Concepts

Fournisseur de réflexion (WCF Data Services)
Fournisseur Entity Framework (WCF Data Services)

Partager via