Personalizzazione di feed (WCF Data Services)

Articolo
02/27/2011

WCF Data Services utilizza il OData (Open Data Protocol) per esporre i dati come feed. OData supporta sia i formati Atom che JSON (JavaScript Object Notation) per i feed di dati. Quando si utilizza un feed Atom, OData fornisce un metodo standard per la serializzazione di dati, quali entità e relazioni, in un formato XML che può essere incluso nel corpo del messaggio HTTP. OData definisce un mapping predefinito di proprietà di entità tra i dati contenuti nelle entità e gli elementi Atom. Per ulteriori informazioni, vedere la pagina relativa al formato Atom in OData.

È possibile che lo scenario applicativo in uso richieda che i dati delle proprietà restituiti dal servizio dati vengano serializzati in modo personalizzato piuttosto che nel formato dei feed standard. Con OData è possibile personalizzare la serializzazione in un feed di dati in modo che le proprietà di un'entità possano essere mappate agli elementi e agli attributi inutilizzati di un'entità o agli elementi personalizzati di una voce nel feed.

Nota:
La personalizzazione di feed è supportata solo per i feed in formato Atom. I feed personalizzati non vengono restituiti quando per il feed restituito è richiesto il formato JSON.

Con WCF Data Services è possibile definire un mapping alternativo di proprietà di entità per un payload Atom applicando manualmente gli attributi ai tipi di entità nel modello di dati. La modalità di applicazione degli attributi viene determinata dal provider dell'origine dati del servizio dati.

Nota:
Quando si definiscono feed personalizzati, è necessario assicurarsi che tutte le proprietà dell'entità che dispongono di definizioni di mapping personalizzate siano incluse nella proiezione. Se una proprietà di entità mappata non è inclusa nella proiezione, potrebbe verificarsi una perdita di dati. Per ulteriori informazioni, vedere Proiezioni di query (WCF Data Services).

Personalizzazione di feed con il provider di Entity Framework

Il modello di dati utilizzato con il provider di Entity Framework è rappresentato come codice XML nel file con estensione edmx. In questo caso, gli attributi che definiscono i feed personalizzati vengono aggiunti agli elementi EntityType e Property che rappresentano tipi di entità e proprietà nel modello di dati. Questi attributi di personalizzazione dei feed non vengono definiti nel formato di file CSDL (Conceptual Schema Definition Language) [MC-CSDL], ovvero nel formato utilizzato dal provider di Entity Framework per definire il modello di dati. È pertanto necessario dichiarare gli attributi di personalizzazione dei feed in uno spazio dei nomi dello schema specifico, definito come m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata". Nel frammento XML seguente vengono illustrati gli attributi di personalizzazione dei feed applicati agli elementi Property del tipo di entità Products che definiscono le proprietà ProductName, ReorderLevel e 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"
    />

Questi attributi producono il feed di dati personalizzato seguente per il set di entità Products. Nel feed di dati personalizzato il valore della proprietà ProductName viene visualizzato sia nell'elemento author sia come elemento proprietà ProductName e la proprietà UnitsInStock viene visualizzata in un elemento personalizzato con il relativo spazio dei nomi univoco e con la proprietà ReorderLevel come attributo:

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

Per ulteriori informazioni, vedere Procedura: personalizzare feed con il provider di Entity Framework (WCF Data Services).

Nota:
Poiché le estensioni al modello di dati non sono supportate da Entity Designer, è necessario modificare manualmente il file XML contenente il modello di dati. Per ulteriori informazioni su file con estensione edmx generati dagli strumenti di Entity Data Model , vedere .edmx File Overview (Entity Framework).

Attributi di feed personalizzati

Nella tabella seguente vengono elencati gli attributi XML per la personalizzazione di feed che è possibile aggiungere al file CSDL (Conceptual Schema Definition Language) che definisce il modello di dati. Questi attributi equivalgono alle proprietà dell'oggetto EntityPropertyMappingAttribute utilizzato con il provider di reflection.

Nome attributo	Descrizione
FC_ContentKind	Indica il tipo di contenuto. Le parole chiave seguenti definiscono i tipi di contenuto di diffusione. Parola chiave Descrizione text Il valore della proprietà viene visualizzato nel feed come testo. html Il valore della proprietà viene visualizzato nel feed come HTML. xhtml Il valore della proprietà viene visualizzato nel feed come HTML con formattazione XML. Queste parole chiave equivalgono ai valori dell'enumerazione SyndicationTextContentKind utilizzata con il provider di reflection. Questo attributo non è supportato quando si utilizzano gli attributi FC_NsPrefix e FC_NsUri. Quando si specifica un valore xhtml per l'attributo FC_ContentKind, è necessario assicurarsi che il valore della proprietà contenga codice XML formattato correttamente. Il servizio dati restituisce il valore senza eseguire alcuna trasformazione. È inoltre necessario assicurarsi che tutti i prefissi degli elementi XML nel codice XML risultante dispongano di un URI dello spazio dei nomi e di un prefisso definito nel feed mappato.
FC_KeepInContent	Indica che il valore della proprietà a cui viene fatto riferimento deve essere incluso sia nella sezione di contenuto del feed sia nel percorso mappato. I valori validi sono true e false. Per fare in modo che il feed prodotto sia compatibile con le versioni precedenti di WCF Data Services , specificare il valore true per garantire che il valore sia incluso nella sezione di contenuto del feed.
FC_NsPrefix	Prefisso dello spazio dei nomi dell'elemento XML in un mapping non di diffusione. Questo attributo deve essere utilizzato con l'attributo FC_NsUri e non è possibile utilizzarlo con l'attributo FC_ContentKind.
FC_NsUri	URI dello spazio dei nomi dell'elemento XML in un mapping non di diffusione. Questo attributo deve essere utilizzato con l'attributo FC_NsPrefix e non è possibile utilizzarlo con l'attributo FC_ContentKind.
FC_SourcePath	Percorso della proprietà dell'entità a cui si applica la regola di mapping del feed. Questo attributo è supportato solo quando lo si utilizza in un elemento EntityType. La proprietà SourcePath non può fare riferimento direttamente a un tipo complesso. Per i tipi complessi, è necessario utilizzare un'espressione di percorso in cui i nomi delle proprietà sono separati da una barra rovesciata (/). Ad esempio, i valori seguenti sono consentiti per un tipo di entità `Person` con una proprietà integer `Age` e una proprietà complessa `Address`: `Age` `Address/Street` La proprietà SourcePath non può essere impostata su un valore contenente uno spazio o qualsiasi altro carattere non valido in un nome di proprietà.
FC_TargetPath	Nome dell'elemento di destinazione del feed risultante per il mapping della proprietà. Questo elemento può corrispondere a un elemento definito dalla specifica Atom o a un elemento personalizzato. Le parole chiave seguenti rappresentano valori del percorso di destinazione di diffusione predefiniti che puntano a una posizione specifica in un feed OData . Parola chiave Descrizione SyndicationAuthorEmail Elemento `atom:email` figlio dell'elemento `atom:author`. SyndicationAuthorName Elemento `atom:name` figlio dell'elemento `atom:author`. SyndicationAuthorUri Elemento `atom:uri` figlio dell'elemento `atom:author`. SyndicationContributorEmail Elemento `atom:email` figlio dell'elemento `atom:contributor`. SyndicationContributorName Elemento `atom:name` figlio dell'elemento `atom:contributor`. SyndicationContributorUri Elemento `atom:uri` figlio dell'elemento `atom:contributor`. SyndicationCustomProperty Elemento di proprietà personalizzata. Quando si esegue il mapping a un elemento personalizzato, la destinazione deve corrispondere a un'espressione di percorso in cui gli elementi annidati sono separati da una barra rovesciata (/) e gli attributi vengono specificati da una e commerciale (@). Nell'esempio seguente la stringa `UnitsInStock/@ReorderLevel` esegue il mapping di un valore di proprietà a un attributo denominato `ReorderLevel` in un elemento figlio denominato `UnitsInStock` dell'elemento entry radice. `<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" />` Quando la destinazione corrisponde a un nome di elemento personalizzato, è inoltre necessario specificare gli attributi FC_NsPrefix e FC_NsUri. SyndicationPublished Elemento `atom:published`. SyndicationRights Elemento `atom:rights`. SyndicationSummary Elemento `atom:summary`. SyndicationTitle Elemento `atom:title`. SyndicationUpdated Elemento `atom:updated`. Queste parole chiave equivalgono ai valori dell'enumerazione SyndicationItemProperty utilizzata con il provider di reflection.

Nota:
Per i nomi e i valori degli attributi viene effettuata la distinzione tra maiuscole e minuscole. Gli attributi possono essere applicati all'elemento EntityType oppure a uno o più elementi Property, ma non a entrambi.

Personalizzazione di feed con il provider di reflection

Per personalizzare feed per un modello di dati implementato tramite il provider di reflection, aggiungere una o più istanze dell'attributo EntityPropertyMappingAttribute alle classi che rappresentano i tipi di entità nel modello di dati. Le proprietà della classe EntityPropertyMappingAttribute corrispondono agli attributi di personalizzazione dei feed descritti nella sezione precedente. Di seguito viene illustrato un esempio di dichiarazione del tipo Order, con mapping del feed personalizzato definito per entrambe le proprietà.

Nota:
Il modello di dati per questo esempio è definito nell'argomento Procedura: creare un servizio dati utilizzando il provider di reflection (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

Questi attributi producono il feed di dati personalizzato seguente per il set di entità Orders. In questo feed personalizzato il valore della proprietà OrderId viene visualizzato solo nell'elemento title di entry, mentre il valore della proprietà Customer viene visualizzato sia nell'elemento author sia come elemento della proprietà 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>

Per ulteriori informazioni, vedere Procedura: personalizzare feed con il provider di reflection (WCF Data Services).

Personalizzazione di feed con un provider del servizio dati personalizzato

La personalizzazione di feed per un modello di dati specificato mediante un provider del servizio dati personalizzato viene definita per un tipo di risorsa chiamando il metodo AddEntityPropertyMappingAttribute sull'oggetto ResourceType che rappresenta un tipo di entità nel modello di dati. Per ulteriori informazioni, vedere Provider di servizi dati personalizzati (WCF Data Services).

Utilizzo di feed personalizzati

Quando l'applicazione utilizza direttamente un feed OData , è necessario che l'applicazione sia in grado di elaborare gli elementi e gli attributi personalizzati inclusi nel feed restituito. Dopo aver implementato i feed personalizzati nel modello di dati, indipendentemente dal provider del servizio dati, l'endpoint $metadata restituisce le informazioni sui feed personalizzati come attributi dei feed personalizzati nel file CSDL restituito dal servizio dati. Quando si utilizza la finestra di dialogo Aggiungi riferimento al servizio o lo strumento datasvcutil.exe per generare le classi del servizio dati client, gli attributi dei feed personalizzati vengono utilizzati per garantire che le richieste e le risposte al servizio dati vengano gestite correttamente.

Considerazioni sulla personalizzazione dei feed

Quando si definiscono i mapping dei feed personalizzati è opportuno tenere presenti le considerazioni seguenti.

Il client WCF Data Services tratta come vuoti gli elementi mappati in un feed quando contengono solo spazio vuoto. Per questo motivo gli elementi mappati che contengono solo spazio vuoto non vengono materializzati sul client con lo stesso spazio vuoto. Per mantenere tale spazio vuoto sul client, è necessario impostare il valore di KeepInContext su true nell'attributo di mapping del feed.

Requisiti di versione

La personalizzazione dei feed prevede i seguenti requisiti di versione del protocollo OData :

La personalizzazione dei feed richiede che il client e il servizio dati supportino entrambi la versione 2.0 del protocollo OData e versioni successive.

Per ulteriori informazioni, vedere Utilizzo di più versioni di WCF Data Services.

Vedere anche

Concetti

Provider di reflection (WCF Data Services)
Provider di Entity Framework (WCF Data Services)

Condividi tramite