Personalizzazione di feed (WCF Data Services)
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 venga eseguito il mapping delle proprietà di un'entità 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 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.
Importante
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à sottoposta a mapping 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 l file con estensione EDMX generato 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.
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:
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.
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 definito 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).
Mapping alle proprietà di raccolta
Nella versione 3 e nelle versioni successive il protocollo OData supporta le entità con le proprietà di raccolta. Queste proprietà restituiscono una raccolta non ordinata di tipi primitivi o complessi. Il provider Entity Framework non supporta le entità che contengono proprietà di raccolta. È possibile eseguire il mapping dei dati del feed alle proprietà di raccolta di un'entità nello stesso modo utilizzato per eseguire il mapping alle proprietà primitive o complesse di un'entità. Tuttavia, poiché questo tipo di proprietà contiene una raccolta, l'elemento del feed a cui viene eseguito il mapping della proprietà viene ripetuto nel feed una volta per ogni elemento presente nella raccolta.
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 sottoposti a mapping 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.
Il mapping a una proprietà di raccolta richiede che il client e il servizio dati supportino entrambi la versione 3.0 del protocollo OData e versioni successive.
Per ulteriori informazioni, vedere Controllo delle versioni del servizio dati (WCF Data Services).