Personalización de fuentes (WCF Data Services)
Servicios de datos de Microsoft WCF utiliza Open Data Protocol (OData) para exponer los datos como fuente. OData admite los formatos Atom y JSON (JavaScript Object Notation) para las fuentes de distribución de datos. Cuando usa una fuente Atom, OData proporciona un método estándar para serializar los datos, como entidades y relaciones, en un formato XML que se puede incluir en el cuerpo de mensaje HTTP. OData define una asignación de entidad-propiedad predeterminada entre los datos contenidos en entidades y en elementos Atom. Para obtener más información, vea OData: Atom Format.
Quizá tenga un escenario de aplicación que requiera que los datos de la propiedad devueltos por el servicio de datos se serialicen de forma personalizada en vez de hacerlo con el formato de fuente estándar. Con OData, puede personalizar la serialización de una fuente de distribución de datos de forma que las propiedades de una entidad se puedan asignar a elementos de fuente y atributos no usados de una entrada o a elementos de una entrada en la fuente.
Nota
La personalización de fuentes solo se admite en las fuentes Atom.No se devuelven fuentes personalizadas cuando se solicita el formato JSON para la fuente devuelta.
Con Servicios de datos de Microsoft WCF, puede definir una asignación de entidad-propiedad alternativa para una carga Atom aplicando manualmente los atributos a los tipos de entidad del modelo de datos. El proveedor del origen de datos del servicio de datos determina cómo debería aplicar estos atributos.
Importante
Cuando defina las fuentes personalizadas, debe asegurarse de que se incluyan todas las propiedades de entidad con asignaciones personalizadas en la proyección.Cuando no se incluya ninguna propiedad de entidad asignada en la proyección, se puede producir la pérdida de datos.Para obtener más información, vea Proyecciones de consultas (WCF Data Services).
Personalizar fuentes con el proveedor de Entity Framework
El modelo de datos usado con el proveedor de Entity Framework se representa como XML en el archivo .edmx. En este caso, los atributos que definen las fuentes personalizadas se agregan a los elementos EntityType y Property, que representan tipos de entidad y propiedades en el modelo de datos. Estos atributos de personalización de fuentes no se definen en el formato de archivo de definición de esquemas conceptuales [MC-CSDL], que es el formato que usa el proveedor de Entity Framework para definir el modelo de datos. Por consiguiente, debe declarar los atributos de personalización de fuentes en un espacio de nombres de esquema concreto, que se define como m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata". El fragmento XML siguiente muestra los atributos de personalización de la fuente aplicados a los elementos Property del tipo de entidad Products que definen las propiedades ProductName, ReorderLevel y 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"
/>
Estos atributos generan la fuente de distribución de datos personalizada siguiente para el conjunto de entidades Products. En la fuente de distribución de datos personalizada, el valor de propiedad ProductName se muestra tanto en el elemento author como en el elemento de propiedad ProductName y la propiedad UnitsInStock se muestra en un elemento personalizado que tiene su propio espacio de nombres único y con la propiedad ReorderLevel como atributo:
<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>
Para obtener más información, vea Cómo: Personalizar fuentes con el proveedor de Entity Framework (WCF Data Services).
Nota
Dado que Entity Designer no admite las extensiones al modelo de datos, debe modificar manualmente el archivo XML que contiene el modelo de datos.Para obtener más información sobre el archivo .edmx que es generado por las herramientas de Entity Data Model, vea .edmx File Overview (Entity Framework).
Atributos de fuentes personalizadas
En la tabla siguiente se muestran los atributos XML que personalizan fuentes y que puede agregar al lenguaje de definición de esquemas conceptuales (CSDL) que define el modelo de datos. Estos atributos son equivalentes a las propiedades de la clase EntityPropertyMappingAttribute usada con el proveedor de reflexión.
Nombre de atributo |
Descripción |
||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
FC_ContentKind |
Indica el tipo de contenido. Las palabras clave siguientes definen los tipos de contenido de distribución:
Estas palabras clave son equivalentes a los valores de la enumeración SyndicationTextContentKind usada con el proveedor de reflexión. No se admite este atributo cuando se usan los atributos FC_NsPrefix y FC_NsUri. Cuando especifique un valor de xhtml para el atributo FC_ContentKind, debe asegurarse de que el valor de propiedad contenga XML con el formato correcto. El servicio de datos devuelve el valor sin realizar transformaciones. Además, debe asegurarse de que cualquier prefijo de elemento XML del XML devuelto tenga un URI de espacio de nombres definido en la fuente asignada. |
||||||||||||||||||||||||||
FC_KeepInContent |
Indica que el valor de propiedad a la que se hace referencia debe incluirse tanto en la sección de contenido de la fuente como en la ubicación asignada. Los valores válidos son true y false. Para hacer que la fuente resultante sea compatible con versiones anteriores de Servicios de datos de Microsoft WCF, especifique el valor true para asegurarse de que el valor se incluye en la sección de contenido de la fuente. |
||||||||||||||||||||||||||
FC_NsPrefix |
El prefijo del espacio de nombres del elemento XML de una asignación sin distribución. Este atributo debe usarse con el atributo FC_NsUri y no se puede usar con el atributo FC_ContentKind. |
||||||||||||||||||||||||||
FC_NsUri |
El URI del espacio de nombres del elemento XML de una asignación sin distribución. Este atributo debe usarse con el atributo FC_NsPrefix y no se puede usar con el atributo FC_ContentKind. |
||||||||||||||||||||||||||
FC_SourcePath |
La ruta de acceso de la propiedad de la entidad a la que se aplica esta regla de asignación de fuentes. Este atributo solo se admite cuando se usa en un elemento EntityType. La propiedad SourcePath no puede hacer referencia directamente a un tipo complejo. Para los tipos complejos, debe usar una expresión de ruta cuyos nombres de propiedad estén separados por un carácter de barra diagonal (/). Por ejemplo, se permiten los valores siguientes para un tipo de entidad Person con una propiedad entera Age y una propiedad compleja Address:
La propiedad SourcePath no puede establecerse en un valor que contenga un espacio ni en ningún otro carácter que no sea válido para un nombre de propiedad. |
||||||||||||||||||||||||||
FC_TargetPath |
El nombre del elemento de destino de la fuente resultante que debe asignarse a la propiedad. Este elemento puede ser un elemento definido por la especificación Atom o un elemento personalizado. Las siguientes palabras clave son los valores predefinidos de la ruta de acceso de destino de distribución que señalan a una ubicación concreta de una fuente OData.
Estas palabras clave son equivalentes a los valores de la enumeración SyndicationItemProperty usada con el proveedor de reflexión. |
Nota
Los nombres y los valores de los atributos distinguen mayúsculas de minúsculas.Los atributos se pueden aplicar al elemento EntityType o a uno o varios elementos Property, pero no a ambos.
Personalizar fuentes con el proveedor de reflexión
Para personalizar fuentes para un modelo de datos que se implementó usando el proveedor de reflexión, agregue una o varias instancias del atributo EntityPropertyMappingAttribute a las clases que representan los tipos de entidad del modelo de datos. Las propiedades de la clase EntityPropertyMappingAttribute corresponden a los atributos de personalización de fuentes que se describen en la sección anterior. A continuación se muestra un ejemplo de la declaración del tipo Order, con asignación de la fuente personalizada definida para ambas propiedades.
Nota
El modelo de datos para este ejemplo se define en el tema Cómo: Crear un servicio de datos mediante el proveedor de reflexión (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
Estos atributos generan la fuente de distribución de datos personalizada siguiente para el conjunto de entidades Orders. En esta fuente personalizada, el valor de propiedad OrderId solo se muestra en el elemento title de entry y el valor de propiedad Customer se muestra en el elemento author y como elemento de la propiedad 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>
Para obtener más información, vea Cómo: Personalizar fuentes con el proveedor de reflexión (WCF Data Services).
Personalizar fuentes con un proveedor de servicios de datos personalizado
La personalización de fuentes para un modelo de datos definido utilizando un proveedor de servicios de datos personalizado se define para un tipo de recurso llamando al método AddEntityPropertyMappingAttribute en el objeto ResourceType que representa un tipo de entidad en el modelo de datos. Para obtener más información, vea Proveedores de servicios de datos personalizados (WCF Data Services).
Asignar propiedades de colección
En la versión 3 y las versiones posteriores, el protocolo OData admite entidades con propiedades de colección. Estas propiedades devuelven una colección no ordenada de tipos primitivos o complejos. El proveedor Entity Framework no admite entidades que contienen propiedades de colección. Puede asignar datos de fuente a propiedades de colección con varios valores de una entidad de la misma manera en que los asigna a propiedades primitivas o complejas de una entidad. Sin embargo, puesto que dicha propiedad contiene una colección, el elemento de fuente al que está asignada la propiedad se repite una vez en la fuente para cada elemento de la colección.
Usar fuentes personalizadas
Cuando una aplicación usa directamente una fuente de OData, debe ser capaz de procesar cualquiera de los elementos y atributos personalizados existentes en la fuente devuelta. Cuando se han implementado fuentes personalizadas en un modelo de datos, sea cual sea el proveedor del servicio de datos, el extremo $metadata devuelve la información de la fuente personalizada como atributos de fuente personalizados en el CSDL devuelto por el servicio de datos. Si se usa el cuadro de diálogo Agregar referencia de servicio o la herramienta datasvcutil.exe para generar las clases del servicio de datos del cliente, se usan los atributos de fuente personalizados para garantizar que las solicitudes y las respuestas del servicio de datos se controlen correctamente.
Consideraciones sobre personalización de fuentes
Debe considerar lo siguiente cuando defina asignaciones de fuentes personalizadas.
- El cliente de Servicios de datos de Microsoft WCF trata los elementos asignados en una fuente como vacíos cuando contengan solo espacio en blanco. Es por ello que los elementos asignados que contengan solo espacio en blanco no se materializan en el cliente con el mismo espacio en blanco. Para conservar este espacio en blanco en el cliente, debe establecer el valor de KeepInContext en true en el atributo de asignación de fuente.
Requisitos de control de versiones
La personalización de fuentes tiene los siguientes requisitos de control de versiones de OData:
La personalización de fuente requiere que tanto el cliente como el servicio de datos admitan la versión 2.0 del protocolo de OData y versiones posteriores.
La asignación a una propiedad de colección requiere que tanto el cliente como el servicio de datos admitan la versión 3.0 del protocolo de OData y versiones posteriores.
Para obtener más información, vea Control de versiones del servicio de datos (Servicios de datos de Microsoft WCF).