{"id":1063,"date":"2010-11-15T17:05:42","date_gmt":"2010-11-15T17:05:42","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/odatateam\/2010\/11\/15\/additional-feed-customization-support\/"},"modified":"2010-11-15T17:05:42","modified_gmt":"2010-11-15T17:05:42","slug":"additional-feed-customization-support","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/odata\/additional-feed-customization-support\/","title":{"rendered":"Additional Feed Customization Support"},"content":{"rendered":"

1.     <\/span><\/span><\/span>Problem: <\/h3>\n

<\/span><\/span> <\/p>\n<\/h2>\n

In the previous version, WCF Data Services introduced the feed customization<\/font><\/a> feature. This feature enabled users to map properties to certain elements in the Atom document. As an example, users could map a name property to the Atom title element. This is especially useful for generic feed readers which may not know how to interpret the properties in the content element but understand other Atom elements. <\/p>\n<\/p>\n

\n

 <\/p>\n<\/p>\n

The OData<\/font><\/a> protocol, and therefore our implementation, did not allow users to map to the repeating Atom link and category elements. In addition, users never had the ability to map properties based on a condition. <\/p>\n<\/p>\n

\n

 <\/p>\n<\/p>\n

2.     <\/span><\/span><\/span>Design: <\/h3>\n

<\/span><\/span> <\/p>\n<\/h2>\n

We have extended the set of Atom elements that can be mapped and introduced a new feature known as Conditional Entity Property Mapping (EPM) to solve the issues discussed above. This new feature includes 2 parts. First, users can specify standard, unconditional mapping to Atom link and category elements. Second is the ability to map to the Atom link and category elements based on a condition. For example, only apply the mapping when the link element\u2019s rel attribute (denoted as link\/@rel) has a value equal to \u201chttp:\/\/MyValue\u201d. We\u2019ll get into some specifics later on in this post but the condition only applies to the link\/@rel and category\/@scheme attributes. Conditional mapping is not supported for other Atom or Custom feed elements at this time. <\/p>\n<\/p>\n

\n

 <\/p>\n<\/p>\n

3.     <\/span><\/span><\/span>Understanding the Feature: <\/h3>\n

<\/span><\/span> <\/p>\n<\/h2>\n

3.1  <\/span><\/span>Extending Feed Customizations (Unconditional Mappings): <\/h4>\n

<\/span><\/span> <\/p>\n<\/h3>\n

\n

 <\/p>\n<\/h3>\n

Let\u2019s first start with unconditional mapping to Atom link and category elements. This is the same process as the feed customization introduced in the previous version. <\/p>\n<\/p>\n

\n

 <\/p>\n<\/p>\n

Mappings are described on classes through the EntityPropertyMappingAttribute. This attribute is present on generated client classes to describe the mapping, and is used to define mappings exposed by the reflection provider: <\/p>\n<\/p>\n

\n

 <\/p>\n<\/p>\n

public<\/span> EntityPropertyMappingAttribute( <\/span><\/p>\n<\/p>\n<\/p>\n

         <\/span><\/span>string<\/span> sourcePath, <\/span><\/p>\n<\/p>\n<\/p>\n

         <\/span>SyndicationItemProperty targetSyndicationItem, <\/span><\/p>\n<\/p>\n<\/p>\n

         <\/span>SyndicationTextContentKind targetTextContentKind, <\/span><\/p>\n<\/p>\n<\/p>\n

         <\/span><\/span>bool<\/span> keepInContent <\/span><\/p>\n<\/p>\n<\/p>\n

) <\/span><\/p>\n<\/p>\n<\/p>\n

We updated the SyndicationItemProperty enum to include the link and category element\u2019s attributes. The full list of updates can be found in the table below. <\/p>\n<\/p>\n

\n

 <\/p>\n<\/p>\n

A service describes mapping through the CSDL exposed by its $metadata endpoint. These same CSDL annotations are used to describe mappings to the  <\/span>Entity Framework (EF) provider. The set of valid values for FC_TargetPath has been extended to include the new link and category attributes: <\/p>\n<\/p>\n

<Property Name="Term" Type="String" Nullable="false" <\/span><\/p>\n<\/p>\n<\/p>\n

          <\/span>MaxLength="40" Unicode="true" FixedLength="false" <\/span><\/p>\n<\/p>\n<\/p>\n

          <\/span>m:FC_TargetPath="SyndicationCategoryTerm"<\/b> <\/span><\/p>\n<\/p>\n<\/p>\n

          <\/span>m:FC_ContentKind="text" <\/span><\/p>\n<\/p>\n<\/p>\n

          <\/span>m:FC_KeepInContent="false" <\/span><\/p>\n<\/p>\n<\/p>\n

    <\/span>\/> <\/span><\/p>\n<\/p>\n<\/p>\n

\n

 <\/p>\n<\/p>\n

The additions to both the SyndicationItemProperty enum and FC_TargetPath attribute can be found in the table below: <\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n
\n

EntityPropertyMapping<\/b><\/p>\n

    SyndicationItemProperty<\/b><\/p>\n<\/td>\n

\n

CSDL<\/b><\/p>\n

    FC_TargetPath<\/b><\/p>\n<\/td>\n<\/tr>\n

\n

    LinkHref<\/p>\n<\/td>\n

\n

    SyndicationLinkHref<\/p>\n<\/td>\n<\/tr>\n

\n

    LinkRel<\/p>\n<\/td>\n

\n

    SyndicationLinkRel<\/p>\n<\/td>\n<\/tr>\n

\n

    LinkType<\/p>\n<\/td>\n

\n

    SyndicationLinkType<\/p>\n<\/td>\n<\/tr>\n

\n

    LinkHrefLang<\/p>\n<\/td>\n

\n

    SyndicationLinkHrefLang<\/p>\n<\/td>\n<\/tr>\n

\n

    LinkTitle<\/p>\n<\/td>\n

\n

    SyndicationLinkTitle<\/p>\n<\/td>\n<\/tr>\n

\n

    LinkLength<\/p>\n<\/td>\n

\n

    SyndicationLinkLength<\/p>\n<\/td>\n<\/tr>\n

\n

    CategoryTerm<\/p>\n<\/td>\n

\n

    SyndicationCategoryTerm<\/p>\n<\/td>\n<\/tr>\n

\n

    CategoryScheme <\/p>\n<\/td>\n

\n

    SyndicationCategoryScheme<\/p>\n<\/td>\n<\/tr>\n

\n

    CategoryLabel<\/p>\n<\/td>\n

\n

    SyndicationCategoryLabel<\/p>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

<\/span><\/p>\n

In the mapping described above, the \u201cTerm\u201d property is mapped to \u201cSyndicationCategoryTerm\u201d and the property is also kept in the content element. Assuming the value of the \u201cTerm\u201d property is \u201cMyTermValue\u201d and no other mappings exist, that section of the entry would look something like: <\/span><\/p>\n<\/p>\n<\/p>\n

<\/span><\/span>\u2026<\/span><\/p>\n

<\/span><<\/span>category<\/span> term<\/span>="<\/span>MyTermValue<\/b>"<\/span> \/><\/span><\/span><\/p>\n

<\/span><\/span><<\/span>content type<\/span>="<\/span>application\/xml<\/b>"<\/span>><\/span><\/span><\/p>\n

<<\/span>m:properties<\/span>><\/span><\/span><\/p>\n

\u2026<\/span><\/p>\n

<\/<\/span>m:properties<\/span>><\/span><\/span><\/p>\n

<\/<\/span>content<\/span>><\/span><\/span><\/p>\n

When mapping to the Atom link element, there is an additional rule to consider. Since an empty link\/@rel value is interpreted as \u201calternate\u201d (<\/span>RFC4287<\/font><\/span><\/a>), and the OData protocol does not allow mapping link\/@rel to simple identifiers (eg. edit, self, alternate, \u2026), when defining unconditional mapping to the link element we must specify a mapping to link\/@rel: <\/span><\/p>\n<\/p>\n<\/p>\n

<\/span><\/p>\n

 <\/p>\n<\/p>\n

[EntityPropertyMappingAttribute<\/span>( <\/span><\/p>\n<\/p>\n<\/p>\n

"MyHref"<\/span>, <\/span><\/p>\n<\/p>\n<\/p>\n

SyndicationItemProperty<\/span>.LinkHref, <\/span><\/p>\n<\/p>\n<\/p>\n

SyndicationTextContentKind<\/span>.Plaintext, <\/span><\/p>\n<\/p>\n<\/p>\n

true<\/span>)] <\/span><\/p>\n<\/p>\n<\/p>\n

[EntityPropertyMappingAttribute<\/span>("MyRel"<\/span>, <\/span><\/p>\n<\/p>\n<\/p>\n

SyndicationItemProperty<\/span>.LinkRel, <\/span><\/p>\n<\/p>\n<\/p>\n

SyndicationTextContentKind<\/span>.Plaintext, <\/span><\/p>\n<\/p>\n<\/p>\n

true<\/span>)] <\/span><\/p>\n<\/p>\n<\/p>\n

[DataServiceKeyAttribute<\/span>("id"<\/span>)] <\/span><\/p>\n<\/p>\n<\/p>\n

public<\/span> class<\/span> Photos<\/span> <\/span><\/p>\n<\/p>\n<\/p>\n

{ <\/span><\/p>\n<\/p>\n<\/p>\n

    <\/span>public<\/span> int<\/span> id { get<\/span>; set<\/span>; } <\/span><\/p>\n<\/p>\n<\/p>\n

    <\/span>public<\/span> string<\/span> MyHref { get<\/span>; set<\/span>; } <\/span><\/p>\n<\/p>\n<\/p>\n

    <\/span>public<\/span> string<\/span> MyRel { get<\/span>; set<\/span>; } <\/span><\/p>\n<\/p>\n<\/p>\n

} <\/span><\/p>\n<\/p>\n<\/p>\n

<\/span><\/p>\n

 <\/p>\n<\/p>\n

3.2  <\/span><\/span><\/span>New Conditional Entity Property Mappings: <\/h4>\n

<\/span><\/span> <\/p>\n<\/h3>\n

<\/span><\/p>\n

 <\/p>\n<\/p>\n

Now that we\u2019ve covered the extensions to feed customization mappings, let\u2019s look at the second part of this feature, conditional mapping. There are situations where a user may only want to map to Atom link and category elements when they satisfy a certain condition. For example, assume we have a model that contains a collection of photos. These photos may differ in their resolution (eg. Hi-res, low-res, thumbnail). It makes sense to map the resolution to a category element since it helps to distinguish the different photos. Conditions are useful here because there may be other category elements we don\u2019t care about. <\/p>\n<\/p>\n

\n

 <\/p>\n<\/p>\n

In order to use conditions in the mappings, we introduced a new EntityPropertyMappingAttribute constructor: <\/p>\n<\/p>\n

\n

 <\/p>\n<\/p>\n

public<\/span> EntityPropertyMappingAttribute( <\/span><\/p>\n<\/p>\n<\/p>\n

         <\/span><\/span>string<\/span> sourcePath, <\/span><\/p>\n<\/p>\n<\/p>\n

         <\/span>SyndicationItemProperty targetSyndicationItem, <\/span><\/p>\n<\/p>\n<\/p>\n

         <\/span><\/span>bool<\/span> keepInContent, <\/span><\/p>\n<\/p>\n<\/p>\n

         <\/span>SyndicationCriteria criteria, <\/span><\/p>\n<\/p>\n<\/p>\n

         <\/span><\/span>string<\/span> criteriaValue <\/span><\/p>\n<\/p>\n<\/p>\n

) <\/span><\/p>\n<\/p>\n<\/p>\n

Notice the addition of the criteria and criteraValue parameters. The SyndicationCriteria parameter is a new enum with values: <\/p>\n<\/p>\n

\u00b7         <\/span><\/span><\/span>LinkRel <\/p>\n<\/p>\n

\u00b7         <\/span><\/span><\/span>CategoryScheme <\/p>\n<\/p>\n

\n

 <\/p>\n<\/p>\n

Similarly, we are introducing new CSDL attributes for FC_Criteria and FC_CriteriaValue. For FC_Criteria, the corresponding values are: <\/p>\n<\/p>\n

\u00b7         <\/span><\/span><\/span>SyndicationLinkRel<\/span> <\/p>\n<\/p>\n

\u00b7         <\/span><\/span><\/span>SyndicationCategoryScheme<\/span> <\/p>\n<\/p>\n

<\/span><\/p>\n

 <\/p>\n<\/p>\n

The criteria indicates the attribute on which the condition exists. For example, if the criteria equals \u201cCategoryScheme\u201d, the condition would depend on the value of the category\/@scheme. <\/span><\/p>\n<\/p>\n<\/p>\n

The criteriaValue parameter specifies the value that must be matched in order for the mapping to apply. To make this clearer, let\u2019s look at the following example: <\/span><\/p>\n<\/p>\n<\/p>\n

<\/span><\/p>\n

 <\/p>\n<\/p>\n

 <\/span>[EntityPropertyMappingAttribute<\/span>( <\/span><\/p>\n<\/p>\n<\/p>\n

       <\/span>"Term"<\/span>,                                      <\/span>\/\/ sourcePath<\/span> <\/span><\/p>\n<\/p>\n<\/p>\n

       <\/span>SyndicationItemProperty<\/span>.CategoryTerm,        <\/span>\/\/ targetPath<\/span> <\/span><\/p>\n<\/p>\n<\/p>\n

       <\/span>false<\/span>,                                       <\/span>\/\/ keepInContent<\/span> <\/span><\/p>\n<\/p>\n<\/p>\n

       <\/span>SyndicationCriteria<\/span>.CategoryScheme,          <\/span>\/\/ criteria<\/span> <\/span><\/p>\n<\/p>\n<\/p>\n

    <\/span>   <\/span>"http:\/\/foo.com\/MyPhotos"<\/span>)]                  <\/span>\/\/ criteriaValue<\/span> <\/span><\/p>\n<\/p>\n<\/p>\n

[DataServiceKeyAttribute<\/span>("id"<\/span>)] <\/span><\/p>\n<\/p>\n<\/p>\n

public<\/span> class<\/span> Category<\/span> <\/span><\/p>\n<\/p>\n<\/p>\n

{ <\/span><\/p>\n<\/p>\n<\/p>\n

    <\/span>public<\/span> int<\/span> id { get<\/span>; set<\/span>; } <\/span><\/p>\n<\/p>\n<\/p>\n

    <\/span>public<\/span> string<\/span> Term { get<\/span>; set<\/span>; } <\/span><\/p>\n<\/p>\n<\/p>\n

} <\/span><\/p>\n<\/p>\n<\/p>\n

<\/span><\/p>\n

 <\/p>\n<\/p>\n

To understand what this mapping describes, we\u2019ll break it down into the serialization and deserialization steps. When serializing to a feed, the \u201cTerm\u201d property will be mapped to category\/@term with category\/@scheme equal to the criteriaValue, \u201chttp:\/\/foo.com\/MyPhotos\u201d.  <\/span>Assuming the \u201cTerm\u201d property has a value of \u201cMyTermValue\u201d, the mapping above would generate a feed like: <\/span><\/p>\n<\/p>\n<\/p>\n

<\/span><\/p>\n

 <\/p>\n<\/p>\n

<<\/span>entry<\/span>> <\/span><\/p>\n<\/p>\n<\/p>\n

\u2026<\/span> <\/span><\/p>\n<\/p>\n<\/p>\n

<<\/span>category<\/span> term<\/span>="<\/span>MyTermValue<\/b>"<\/span> scheme<\/span>="<\/span>http:\/\/foo.com\/MyPhotos<\/b>" \/><\/span> <\/span><\/p>\n<\/p>\n<\/p>\n

<<\/span>content type<\/span>="<\/span>application\/xml<\/b>"<\/span>><\/span><\/span><\/p>\n

<<\/span>m:properties<\/span>><\/span><\/span><\/p>\n

\u2026<\/span><\/p>\n

\n

 <\/p>\n<\/p>\n

For deserialization, if the entry has a category element where category\/@scheme equals \u201chttp:\/\/foo.com\/MyPhotos\u201d, the mapping will occur. All other category elements will be ignored by this mapping. It is important to know that, when the value of the attribute and criteraValue are compared, the comparison is for case insensitive, non-escaped, and equal string values. <\/p>\n<\/p>\n

\n

 <\/p>\n<\/p>\n

To finish off the examples, here is a conditional mapping to the link element: <\/p>\n<\/p>\n

\n

 <\/p>\n<\/p>\n

[EntityPropertyMappingAttribute<\/span>( <\/span><\/p>\n<\/p>\n<\/p>\n

      <\/span>"MyHref"<\/span>,                                     <\/span>\/\/ sourcePath<\/span> <\/span><\/p>\n<\/p>\n<\/p>\n

      <\/span>SyndicationItemProperty<\/span>.LinkHref,        <\/span>     <\/span>\/\/ targetPath<\/span> <\/span><\/p>\n<\/p>\n<\/p>\n

      <\/span>false<\/span>,                                       <\/span> <\/span>\/\/ keepInContent<\/span> <\/span><\/p>\n<\/p>\n<\/p>\n

      <\/span>SyndicationCriteria<\/span>.LinkRel,          <\/span>        <\/span>\/\/ criteria<\/span> <\/span><\/p>\n<\/p>\n<\/p>\n

      <\/span>"http:\/\/MyRelValue"<\/span>)]                 <\/span>       <\/span> <\/span>\/\/ criteriaValue <\/span><\/span><\/p>\n<\/p>\n<\/p>\n

[DataServiceKeyAttribute<\/span>("id"<\/span>)] <\/span><\/p>\n<\/p>\n<\/p>\n

public<\/span> class<\/span> Photos<\/span> <\/span><\/p>\n<\/p>\n<\/p>\n

{ <\/span><\/p>\n<\/p>\n<\/p>\n

    <\/span>public<\/span> int<\/span> id { get<\/span>; set<\/span>; } <\/span><\/p>\n<\/p>\n<\/p>\n

    <\/span>public<\/span> string<\/span> MyHref { get<\/span>; set<\/span>; } <\/span><\/p>\n<\/p>\n<\/p>\n

} <\/p>\n<\/p>\n

\n

 <\/p>\n<\/p>\n

Notice how the condition is on link\/@rel. Since the criteriaValue is not a simple identifier, this mapping automatically satisfies the simple identifier rule described above. When serializing to a feed, this will look like: <\/p>\n<\/p>\n

\u2026 <\/p>\n<\/p>\n

<<\/span>link<\/span> href<\/span>="<\/span>http:\/\/hrefValue.com\/<\/b>"<\/span> rel<\/span>="<\/span>http:\/\/MyRelValue<\/b>" \/><\/span> <\/span><\/p>\n<\/p>\n<\/p>\n

\u2026 <\/p>\n<\/p>\n

\n

 <\/p>\n<\/p>\n

To summarize, this new feature includes 2 parts. The first part extends Feed Customization to the Atom link and category elements. The second part introduces mapping based on conditions.  <\/p>\n<\/p>\n

\n

 <\/p>\n<\/p>\n

Julian Lai <\/p>\n<\/p>\n

WCF Data Services, Program Manager <\/p>\n","protected":false},"excerpt":{"rendered":"

1.     Problem: In the previous version, WCF Data Services introduced the feed customization feature. This feature enabled users to map properties to certain elements in the Atom document. As an example, users could map a name property to the Atom title element. This is especially useful for generic feed readers which may not know how […]<\/p>\n","protected":false},"author":512,"featured_media":3253,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[],"class_list":["post-1063","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-odata"],"acf":[],"blog_post_summary":"

1.     Problem: In the previous version, WCF Data Services introduced the feed customization feature. This feature enabled users to map properties to certain elements in the Atom document. As an example, users could map a name property to the Atom title element. This is especially useful for generic feed readers which may not know how […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/posts\/1063","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/users\/512"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/comments?post=1063"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/posts\/1063\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/media\/3253"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/media?parent=1063"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/categories?post=1063"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/tags?post=1063"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}