{"id":1073,"date":"2010-11-12T12:21:09","date_gmt":"2010-11-12T12:21:09","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/odatateam\/2010\/11\/12\/named-resource-streams\/"},"modified":"2010-11-12T12:21:09","modified_gmt":"2010-11-12T12:21:09","slug":"named-resource-streams","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/odata\/named-resource-streams\/","title":{"rendered":"Named Resource Streams"},"content":{"rendered":"<\/p>\n

One of the new WCF Data Services features in the October 2010 CTP<\/font><\/a> is something called Named Resource Streams. <\/p>\n<\/p>\n

Background<\/h4>\n

\n<\/h2>\n

Data Services already supports Media Link Entries which allows you to associate a single streamed blob with an entry.  <\/span>For example, you could have a Photo entry that lists the metadata about the photo and links directly to the photo itself. <\/p>\n<\/p>\n

But what happens though if you have multiple versions of the Photo? <\/p>\n<\/p>\n

Today you could model this with multiple MLEs, but doing so requires you to have multiple copies of the metadata for each version of the stream.  <\/span>Clearly this is not desirable when you have multiple versions of essentially the photo.  <\/span> <\/p>\n<\/p>\n

It turns out that this is a very common scenario, common enough that we thought it needed to be supported without forcing people to use multiple MLEs.  <\/span>So, with this release we\u2019ve allowed an entry to have multiple streams associated with it such that you can now create services that do things such as expose a Photo entry with links to its print, web and thumbnail versions. <\/p>\n<\/p>\n

Let\u2019s explore how to use this feature. <\/p>\n<\/p>\n

Client-Side <\/h4>\n

\n<\/h2>\n

Once a producer exposes Named Resource Streams you have two ways to manipulate them on the client, the first is via new overloads of GetReadStream(..)<\/strong><\/span> and SetSaveStream(..)<\/strong><\/span> that take a stream name: <\/p>\n<\/p>\n

\/\/ retrieve a person
Person fred = (from p in context.People
               <\/span>where p.Name == "Fred"
               <\/span>select p).Single(); <\/p>\n

\/\/ set custom headers etc via args if needed.
var args = new DataServiceRequestArgs();
args.Headers.Add(\u2026); <\/p>\n

\/\/ make the request to get the stream \u2018Photo\u2019 stream on the Fred entity.
var response = context.GetReadStream(fred, "Photo", args);
Stream stream = response.Stream; <\/strong><\/p>\n<\/p>\n

If you want to update the stream you use SetWriteStream(..)<\/strong><\/span> something like this: <\/p>\n

var fileStream = new FileStream("C:\\\\fred.jpeg", FileMode.Open);
context.SetSaveStream(person, "Photo", fileStream, true, args);
context.SaveChanges();<\/span> <\/strong><\/p>\n<\/p>\n

The other option is to use the StreamDescriptor<\/strong><\/span> which hangs off the entity\u2019s EntityDescriptor<\/strong><\/span>, and carries information about the SelfLink<\/strong><\/span>, EditLink<\/strong><\/span> (often they are the same, but you can sometimes get and update the stream via different urls), ETag<\/strong><\/span> and ContentType<\/strong><\/span> of the Stream: <\/p>\n<\/p>\n

\/\/ Get the entity descriptor for Fred
var dscptor = context.GetEntityDescriptor(fred); <\/strong><\/p>\n

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

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

\/\/ Get the \u2018Photo\u2019 StreamDescriptor
var photoDscptor = dscptor.StreamDescriptors.Single(s => s.Name == "Photo");
Uri uriOfFredsPhoto = photoDscptor.SelfLink; <\/strong><\/p>\n<\/p>\n

With the StreamDescriptor you can do low level network activities or perhaps use this Uri when rendering a webpage in the \u2018src\u2019 of an <img> tag. <\/p>\n<\/p>\n

Server-Side <\/h4>\n

\n<\/h2>\n

Adding Named Resource Streams to your Model <\/h5>\n

\n<\/h3>\n

The first step to using Named Resource Streams is to add them into your model. Because data services supports 3 different types of data sources (Entity Framework, Reflection, Custom) there are three ways to add Named Resource Streams into your model. <\/p>\n<\/p>\n

Entity Framework <\/em><\/h5>\n

\n<\/h4>\n

When using the Entity Framework adding a Named Resource Stream to an EntityType is pretty straight forward, you simply add a structural annotation into your Entity Framework EDMX file something like this: <\/p>\n<\/p>\n

<EntityType Name="Person">
   <\/span><Key>
     <\/span><PropertyRef Name="ID" \/>
   <\/span><\/Key>
   <\/span><Property Name="ID" Type="Edm.Int32" Nullable="false" \/>
   <\/span><Property Name="Name" Type="Edm.String" Nullable="true" \/>
   <\/span><m:NamedStreams>
       <\/span><m:NamedStream Name="PhotoThumbnail" \/>
       <\/span><m:NamedStream Name="Photo" \/>
   <\/span><\/m:NamedStreams>
<\/EntityType> <\/strong><\/p>\n<\/p>\n

Here the the m:NamedStreams<\/strong><\/span> element (xmlns:m="http:\/\/schemas.microsoft.com\/ado\/2007\/08\/dataservices\/metadata") indicates Person has two Named Resource Streams, Photo and PhotoThumbnail. <\/p>\n<\/p>\n

Reflection Provider <\/em><\/h5>\n

\n<\/h4>\n

To add a Named Resource Streams to an EntityType using the Reflection Provider<\/font><\/a> we added a new attribute called NamedStreamAttribute<\/strong><\/span>: <\/p>\n<\/p>\n

[NamedStream(\u201cPhotoThumbnail\u201d)]
[NamedStream(\u201cPhoto\u201d)]
public class Person
{
  <\/span>public int ID {get;set;}
  <\/span>public string Name {get;set}
} <\/strong><\/p>\n<\/p>\n

This example is the Reflection provider equivalent of the Entity Framework example above. <\/p>\n<\/p>\n

Custom Provider<\/em><\/h5>\n

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

<\/span><\/h4>\n

When you write a custom provider (see this series for more<\/font><\/a>) you add the Named Resource Streams via your implementation of IDataServiceMetadataProvider<\/font><\/a>. <\/p>\n<\/p>\n

To support this we added a new ResourceStreamInfo class which you can add to your ResourceType definitions something like this: <\/p>\n<\/p>\n

ResourceType person = \u2026
person.AddNamedStream(new ResourceStreamInfo("PhotoThumbnail"));
person.AddNamedStream(new ResourceStreamInfo("Photo")); <\/strong><\/p>\n<\/p>\n

$metadata<\/span> <\/em><\/h5>\n

<\/span>No matter how you tell Data Services about your Named Resource Streams consumers always learn about Named Streams via $metadata, which is an EDMX file, so as you might guess we simply tell consumers about named streams using the same structured annotations we used in the Entity Framework provider example above. <\/p>\n<\/p>\n

Implementing Named Resource Streams <\/h5>\n

\n<\/h3>\n

Next you have to implement a new interface called IDataServiceStreamProvider2<\/strong><\/span> <\/p>\n<\/p>\n

Implementing this interface is very similar to implementing IDataServiceStreamProvider<\/strong><\/span> which Glenn explains well in his two part series (Part1<\/font><\/a> & Part2<\/font><\/a>). <\/p>\n<\/p>\n

IDataServiceStreamProvider2<\/strong><\/span> extends IDataServiceStreamProvider<\/strong><\/span> by adding some overloads to work with Named Resource Streams. <\/p>\n<\/p>\n

The overloads always take a ResourceStreamInfo<\/strong><\/span> from which you can learn which Named Resource Streams is targeted. When reading from or writing to the stream you also get the eTag for the stream and a flag indicating whether the eTag should be checked. <\/p>\n<\/p>\n

Summary<\/h4>\n

\n<\/h2>\n

As you can see Named Resource Streams add a significant new feature to Data Services, which is very useful if you have any entities that contain metadata for anything that has multiple representations, like for example Photos or Videos. <\/p>\n<\/p>\n

Named Resource Streams are very easy to use client-side and build upon our existing Stream capabilities on the server side. <\/p>\n<\/p>\n

As always we are keen to hear your thoughts and feedback. <\/p>\n

Alex James<\/font><\/a>
<\/font>Program Manager
Microsoft <\/p>\n","protected":false},"excerpt":{"rendered":"

One of the new WCF Data Services features in the October 2010 CTP is something called Named Resource Streams. Background Data Services already supports Media Link Entries which allows you to associate a single streamed blob with an entry.  For example, you could have a Photo entry that lists the metadata about the photo and […]<\/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-1073","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-odata"],"acf":[],"blog_post_summary":"

One of the new WCF Data Services features in the October 2010 CTP is something called Named Resource Streams. Background Data Services already supports Media Link Entries which allows you to associate a single streamed blob with an entry.  For example, you could have a Photo entry that lists the metadata about the photo and […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/posts\/1073","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=1073"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/posts\/1073\/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=1073"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/categories?post=1073"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/tags?post=1073"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}