WCF Data Services Team Blog

WCF Data Services 5.0.1 Released

dpblogs — Fri, 18 May 2012 23:42:50 GMT

We have just pushed the official bits for 5.0.1 to NuGet and should be releasing an updated MSI sometime within the next week. Thanks to feedback from the community we found and fixed several bugs, detailed below.

NuGet Links

Release Notes

Added configuration setting to ODataLib to allow users to intercept the XML reader before ODataLib processes the payload
Fixes bug where DateTime values do not roundtrip properly in JSON verbose
Fixes bug where $metadata requests fail on services with both actions and service operations
Fixes bug where $expand requests fail on Oracle providers
Fixes bug where vocabulary annotations in an external annotations file fail to resolve the target

What does the MSI do?

All of the fixes detailed above are in the NuGet bits. There is one additional fix in the MSI for code generation against services that have multiple overloads for a function import. One important nuance of the MSI is that it removes the WCF Data Services DLLs from the GAC. (The 5.0.1 MSI is an upgrade to the 5.0 MSI, which means that the 5.0 MSI gets uninstalled and its install actions – including the GACing of the DLLs – are reversed.) We have blogged previously about leaving the GAC.

Where should the MSI be installed?

The MSI should only be installed on development machines as it solely contains tooling fixes. If the MSI is installed on a production Web server running a WCF Data Services 5.0.0 service that was not bin deployed, the service may stop functioning.

Feedback Please

As we begin to release more quickly and issue more prereleases, your feedback is critical to the process. Please leave your comments and thoughts below.

WCF Data Services EULAs updated

dpblogs — Fri, 18 May 2012 00:02:00 GMT

Today we are releasing an updated EULA for WCF Data Services. Effective as of WCF Data Services 5.0.1, the DLLs that constitute the runtime components of WCF Data Services are now officially redistributable. Please see the attached EULAs for more details.

Please leave your thoughts and comments below.

NuGet and Bin Deploy

dpblogs — Thu, 17 May 2012 23:06:53 GMT

We recently posted about trying to release WCF Data Services more frequently, and some of the changes we’re making. In this post, we’ll take a slightly deeper look at NuGet,bin deploy, and where WCF Data Services is headed.

Managing dependencies with NuGet

If you’re already familiar with NuGet, you probably understand its value proposition and can skip ahead to bin deploying applications. If you haven’t used NuGet before, this section will provide you with a quick introduction. The NuGet site has a great documentation section that provides significantly more detail.

What is NuGet?

Languages such as Ruby and Python have package management systems that make it trivial to take a dependency on a centrally published package. NuGet provides similar functionality for .NET. With a few clicks or a simple command a developer can take a dependency on Microsoft.Data.Services.Client, the assembly that provides WCF Data Services client functionality. Taking a dependency on that package adds three other packages to your project: Microsoft.Data.OData, Microsoft.Data.Edm and System.Spatial.

Getting a specific version of WCF Data Services is also very easy: issuing the command Install-Package Microsoft.Data.Services.Client –Version 5.0.1 will install version 5.0.1 of the client, even if there is a more recent version of the client published. (Issuing the command Install-Package Microsoft.Data.Services.Client or installing the package with the explorer will always get the most recent version of the client.)

Installation experience with Manage NuGet Packages dialog:

Installation experience with Package Manager Console:

Sample installation commands:

Install-Package Microsoft.Data.Services.Client: Installs the most recent released version of the WCF Data Services client.
Install-Package Microsoft.Data.Services.Client –Pre: Installs the most recent version of the WCF Data Services client (including prereleases).
Install-Package Microsoft.Data.Services.Client –Version 5.0.0.50403: Installs an explicit version of WCF Data Services client, ignoring more recent versions.

Updating Packages with NuGet

In addition to the simple installation process, NuGet makes it easy to update packages.

Update experience with Manage NuGet Packages dialog:

Update experience with Package Manager Console:

Sample update commands:

Update-Package: Updates all packages to their most recently released version.
Update-Package –Pre: Updates all packages to their most recent versions (including prereleases).
Update-Package Microsoft.Data.Services.Client: Updates the Microsoft.Data.Services.Client package to its most recently released version, including any dependency updates required by the Microsoft.Data.Services.Client package.

Simplified Dependency Management

In summary, NuGet greatly simplifies the process of locating, downloading, and adding references to the most recent version of WCF Data Services. Developers no longer need to search the Download Center for a version of WCF Data Services, sort by date, download and install an MSI, manually copy the DLLs and add a reference to them, etc. With NuGet developers simply use the Manage NuGet Packages dialog or the Package Manager Console to easily take a dependency on WCF Data Services.

Bin Deploying Applications

Bin deployment is a term commonly used for a deployment process wherein the contents of the bin folder (potentially with a few other files) are copied to a server using a very simple file copy or similar process. In other words, bin deploy scenarios do not require an MSI to be run on the server that will host the application. This is especially key in scenarios where the server is not controlled by the developer (e.g., Web hosting). However, bin deploy is also beneficial in many other scenarios. Some of the benefits of bin deploy are as follows:

Simple file copy deployment using SMB, FTP, or some similar alternative.
Assemblies can be configured to run in medium trust (GACed assemblies always run in full trust).
No need to have an operations team run an MSI to get the latest version of an assembly.
Easier to automate deployments.

Bin deployment is also a natural companion for NuGet, semantic versioning, and our amended EULA for the imminent 5.0.1 version of WCF Data Services, which will include a redistribution clause.

A Glimpse Into the Future

Down the road, we will be taking a much deeper dependency on NuGet – we are currently revamping our tooling to install NuGet packages when you add a WCF Data Service or a reference to an OData service to your application.

Thoughts? Comments? We’d love to hear from you!

WCF Data Services, now with more releases!

dpblogs — Tue, 08 May 2012 02:01:44 GMT

Like other teams at Microsoft, WCF Data Services has been working toward a goal of more frequent releases. We released 5.0 on April 9 and we pre-released WCF Data Services 5.0.1-rc* on April 20 (we’ll release the final version of 5.0.1 very soon). The rapid release was possible because of three changes we’re making. First up, we’re…

Adopting semantic versioning

Semantic versioning is a growing movement that proposes a solution to confusing version numbers. Let’s see how semantic versioning applies to the pre-release: 5.0.1-rc.

The first digit is the major version. Semantic versioning states that the major version should be bumped only when there are breaking changes in a public API.
The second digit is the minor version. Semantic versioning asserts that the minor version should be bumped when new functionality is introduced to the public API.
The third digit is the patch version. Semantic versioning says that the patch version should be bumped for bug fixes that do not affect the public API.
The hypenated string is the pre-release version. Semantic versioning claims that the pre-release version should be appended to anything that is not a release.

Since 5.0.1 only contains bug fixes, we bumped only the third digit of the version number. The prerelease that went out on April 20 was suffixed with -rc to indicate that the bits are not yet release quality.

* Note: When we initially pushed out the prerelease, we thought we would need the minor version increment. This turned out not to be the case, so we fixed the version number to be the correct value according to semantic versioning. We hid the 5.1.0-rc prerelease today, replaced it with 5.0.1-rc and will release the final bits as 5.0.1. If you have installed 5.1.0-rc, you’ll need to uninstall that package before you can install 5.0.1-rc or 5.0.1.

Moving to semantic versioning facilitates our decision to…

Distribute new releases via NuGet

NuGet is a fantastic binary distribution system for a number of reasons. NuGet enables us to release more frequently without causing additional confusion – the version history on the package page clearly displays the versions that have been released:

NuGet also makes it easy to take a dependency on a particular version of an assembly with commands like Install-Package Microsoft.Data.Services.Client –Version 5.0.1. Furthermore, NuGet makes it very easy to recognize prereleases and even provides a special version of the command line that support prerelease versions:

NuGet also makes it easier for us to achieve a third goal…

Changing to a “bin deploy” model

If you’re not familiar with the term, a bin deploy model is one in which you simply copy the contents of the bin directory to the target location – there are no MSIs involved, no GAC – just DLLs and your preferred file transfer mechanism.

There are many reasons to move to a bin deploy model. Two of the more obvious reasons are:

A bin deploy model simplifies deployment and increases the number of potential deployment targets. You don’t need your Web server to run a particular MSI that puts the appropriate assemblies into the GAC. This opens up a whole host of scenarios, including deploying OData services to hosting providers that won’t run the WCF Data Services MSI. It also increases confidence that when an application is deployed, it has all of its dependencies readily available.
A bin deploy model allows trust levels that are commonly leveraged by hosting providers.

We’ll be writing more about NuGet and bin deploy in the near future, but for now we would love to hear your…

Feedback please!

We’d love to hear what you think about 5.0.0, our more frequent releases, and our changes to distribution/deployment. Feel free to leave a comment below!

Metro OData prerelease bits and app

dpblogs — Thu, 26 Apr 2012 17:45:01 GMT

Phani just published a blog post with directions on how to build OData apps for Windows 8 Metro. The Metro bits are still very much in a prerelease form (e.g., you’ll have to invoke codegen with a command line tool) but it should enable developers to start trying out OData on Metro. For the blog post as well as sample bits and the sample app, check out Phani’s blog: http://blogs.msdn.com/b/phaniraj/archive/2012/04/26/developing-windows-8-metro-style-applications-that-consume-odata.aspx.

Have fun, and please feel free to provide feedback below.

WCF Data Services 5.1.0-rc Prerelease

dpblogs — Fri, 20 Apr 2012 23:25:10 GMT

Less than two weeks ago, we released WCF Data Services 5.0.0. Today, we are releasing 5.1.0-rc as a NuGet prerelease.

What is in the prerelease

This prerelease contains several bug fixes:

WCF Data Services fails to work properly with the $expand query option when using the DevArt Oracle EF provider
Some DateTime values do not round-trip properly in JSON verbose
Incorrect metadata version calculation on a V3 service with both service operations and actions

Getting the prerelease

The prerelease is only available on NuGet and must be installed using the prerelease cmdlet. Prereleases are not displayed in the Manage NuGet Packages dialog. To install this prerelease NuGet package, you can use one of the following commands in the Package Manager Console:

Install-Package <PackageId> –Pre
Update-Package <PackageId> –Pre

Our NuGet package ids are:

Microsoft.Data.Services.Client (WCF Data Services Client)
Microsoft.Data.Services (WCF Data Services Server)
Microsoft.Data.OData (ODataLib)
Microsoft.Data.Edm (EdmLib)
System.Spatial (System.Spatial)

Call to action

If you have experienced one of the bugs mentioned above, we encourage you to try out the prerelease bits in a preproduction environment. As always, we’d love to hear any feedback you have!

JSON Light Sample Payloads

dpblogs — Tue, 17 Apr 2012 23:33:23 GMT

We recently put together a document that contains some of our thinking about JSON light as well as a whole slew of sample payloads. We would love to hear any feedback you have on the format; you can comment in the accompanying OneNote.

We will be accepting public feedback on JSON light until May 4, 2012. We will also provide a preview release of the JSON light bits via NuGet for interested parties.

JSON light at-a-glance: https://skydrive.live.com/redir.aspx?cid=0d23ed2816deea7b&resid=D23ED2816DEEA7B!966&parid=D23ED2816DEEA7B!106&authkey=!AAYCE2RUJccjhHk
Discussion: https://skydrive.live.com/redir.aspx?cid=0d23ed2816deea7b&page=view&resid=D23ED2816DEEA7B!967&parid=D23ED2816DEEA7B!106&authkey=!ABdrv3heWfQFY4Y

How to use WCF DS 5.0 in a Web Site project

dpblogs — Tue, 17 Apr 2012 17:45:42 GMT

The WCF Data Services 5.0 RTM release includes an update to the Add Service Reference behavior in Visual Studio. For most project types that target .NET Framework 4.0, this means that when you add a new service reference, you will automatically get assembly references to the new client assemblies, and your client will be able to communicate with servers that support v3 of the OData protocol.

This does not happen by default for Web Site Projects, but there are some manual steps you can take to update these projects to use the new functionality. This applies to Web Site Projects only, not Web Application Projects or any other type of project with support for WCF Data Services.

Configuring a Web Site Project to work with WCF Data Services 5.0:

Add a Service Reference in the Web Site project.

How to: Add, Update, or Remove a Service Reference

This will add the service reference with assembly references to the WCF Data Services client that is included with .NET Framework 4.0, and not the updated version that is included with the 5.0 RTM release.
Update the project’s assembly references to point to the new client.

There are three ways to do this:
- (Recommended) Use NuGet to install the Microsoft.Data.Services.Client package. Click the Tools menu, then Library Package Manager, then Package Manager Console. In the console, type Install-Package Microsoft.Data.Services.Client. You will still need to remove the reference to System.Data.Services.Client using one of the methods below.
- Right-click the project name in Solution Explorer, select Property Pages, then choose the References tab. Remove the reference to System.Data.Services.Client, then add references to Microsoft.Data.Services.Client, Microsoft.Data.OData, Microsoft.Data.Edm and System.Spatial that were installed with WCF Data Services 5.0.
- Edit the <assemblies> section in the project’s web.config file.
  
  Remove the reference to System.Data.Services.Client:
```
<compilation>
  <assemblies>
    <add assembly="System.Data.Services.Client, Version=4.0.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089" />
  </assemblies>
</compilation>
```
  Add references to the new client assemblies:
```
<compilation>
  <assemblies>
    <add assembly="System.Spatial, Version=5.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
    <add assembly="Microsoft.Data.Services.Client, Version=5.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
    <add assembly="Microsoft.Data.OData, Version=5.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
    <add assembly="Microsoft.Data.Edm, Version=5.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
  </assemblies>
</compilation>
```
Configure the project to use the new build provider for WCF Data Services.

Edit the web.config file to override the default DataServiceBuildProvider that is specified in the root web.config that is installed with the .NET Framework.
```
<compilation>
  <folderLevelBuildProviders>
    <remove name="DataServiceBuildProvider"/>
    <add name="DataServiceBuildProvider" type="System.Data.Services.BuildProvider.DataServiceBuildProvider, Microsoft.Data.Services.Design, Version=5.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
  </folderLevelBuildProviders>
</compilation>
```
This step only needs to be done once per project and does not need to be repeated if additional service references are added. All other steps need to be done for each service reference.
Update the Reference.datasvcmap file for the service reference.

The Reference.datasvcmap file contains parameters that control how the code is generated for the service reference. The following parameters are the default for other project types and will allow your types to be used with data binding and will allow the client to communicate with services that support v3 of the OData protocol.
```
<ReferenceGroup>
  <Parameters>
    <Parameter Name="UseDataServiceCollection" Value="true" />
    <Parameter Name="Version" Value="3.0" />
  </Parameters>
</ReferenceGroup>
```

Actions in WCF Data Services – Part 3: A sample provider for the Entity Framework

dpblogs — Thu, 12 Apr 2012 16:43:00 GMT

This post is the last in a series on Actions in WCF Data Services. The series was started with an example experience for defining actions (Part 1) and how IDataServiceActionProvider works (Part 2). In this post we’ll go ahead and walk through a sample action provider implementation that delivers the experience outlined in part 1 for the Entity Framework.

If you want to walk through the code while reading this you’ll find the code here: http://efactionprovider.codeplex.com.

Implementation Strategy

The center of the implementation is the EntityFrameworkActionProvider class that derives from ActionProvider. The EntityFrameworkActionProvider is specific to EF, whereas the ActionProvider provides a generic starting point for an implementation of IDataServiceActionProvider that enables the experience outlined in Part 1.

There is quite a bit going on in the sample code, so I can’t walk through all of it in a single blog post, instead I’ll focus on the most interesting bits of the code:

Finding Actions

Data Service providers can be completely dynamic, producing a completely different model for each request. However with the built-in Entity Framework provider the model is static, basically because the EF model is static, also the actions are static too, because they are defined in code using methods with attributes on them. This all means one thing – our implementation can do a single reflection pass to establish what actions are in the model and cache that for all requests.

So every time the EntityFrameActionProvider is constructed, it first checks a cache of actions defined on our data source, which in our case is a class derived from EF’s DBContext. If a cache look up it successful great, if not it uses the ActionFactory class to go an construct ServiceActions for every action declared on the DBContext.

The algorithm for the ActionFactory is relatively simple:

It is given the Type of the class that defines all the Actions. For us that is the T passed to DataService<T>, which is a class derived from EF’s DBContext.
It them looks for methods with one of these attributes [Action], [NonBindableAction] or [OccasionallyBindableAction], all of which represent different types of actions.
For each method it finds it then uses the IDataServiceMetadataProvider it was with constructed with to convert the parameters and return types into ResourceTypes.
At this point it can construct a ServiceAction for each.

Parameter Marshaling

When an action is actually invoked we need to convert any parameters from WCF Data Services internal representation into objects that the end users methods can actually handle. It is likely that marshaling will be quite different for different underlying providers (EF, Reflection, Custom etc), so the ActionProvider uses an interface IParameterMarshaller, whenever it needs to convert parameters. The EF’s parameter marshaled looks like this:

public class EntityFrameworkParameterMarshaller: IParameterMarshaller
{
static MethodInfo CastMethodGeneric = typeof(Enumerable).GetMethod("Cast");
static MethodInfo ToListMethodGeneric = typeof(Enumerable).GetMethod("ToList");

    public object[] Marshall(DataServiceOperationContext operationContext, ServiceAction action, object[] parameters)
    {
        var pvalues = action.Parameters.Zip(parameters, (parameter, parameterValue) => new { Parameter = parameter, Value = parameterValue });
        var marshalled = pvalues.Select(pvalue => GetMarshalledParameter(operationContext, pvalue.Parameter, pvalue.Value)).ToArray();

        return marshalled;
    }
    private object GetMarshalledParameter(DataServiceOperationContext operationContext, ServiceActionParameter serviceActionParameter, object value)
    {
        var parameterKind = serviceActionParameter.ParameterType.ResourceTypeKind;

        // Need to Marshall MultiValues i.e. Collection(Primitive) & Collection(ComplexType)
        if (parameterKind == ResourceTypeKind.EntityType)
        {

            // This entity is UNATTACHED. But people are likely to want to edit this...
            IDataServiceUpdateProvider2 updateProvider = operationContext.GetService(typeof(IDataServiceUpdateProvider2)) as IDataServiceUpdateProvider2;
            value = updateProvider.GetResource(value as IQueryable, serviceActionParameter.ParameterType.InstanceType.FullName);
            value = updateProvider.ResolveResource(value); // This will attach the entity.
        }
        else if (parameterKind == ResourceTypeKind.EntityCollection)
        {
            // WCF Data Services constructs an IQueryable that is NoTracking...
            // but that means people can't just edit the entities they pull from the Query.
            var query = value as ObjectQuery;
            query.MergeOption = MergeOption.AppendOnly;
        }
        else if (parameterKind == ResourceTypeKind.Collection)
        {
            // need to coerce into a List<> for dispatch
            var enumerable = value as IEnumerable;
            // the <T> in List<T> is the Instance type of the ItemType
            var elementType = (serviceActionParameter.ParameterType as CollectionResourceType).ItemType.InstanceType;
            // call IEnumerable.Cast<T>();
            var castMethod = CastMethodGeneric.MakeGenericMethod(elementType);
            object marshalledValue = castMethod.Invoke(null, new[] { enumerable });
            // call IEnumerable<T>.ToList();
            var toListMethod = ToListMethodGeneric.MakeGenericMethod(elementType);
            value = toListMethod.Invoke(null, new[] { marshalledValue });
        }
        return value;
    }
}

This is probably the hardest part of the whole sample because it involves understanding what is necessary to make the parameters you pass to the service authors action methods updatable (remembers Actions generally have side-effects).

For example when Data Services see’s something like this: POST http://server/service/Movies(1)/Checkout

It builds a query to represent the Movie parameter to the Checkout action, however when Data Services is building queries, it doesn’t need the Entity Framework to track the results – because all it is doing is serializing the entities and then discarding them. However in this example, we need to take the query and actually retrieve the object in such as way that it is tracked by EF, so that if it gets modified inside the action EF will notice and push changes back to the Database during SaveChanges.

Delaying invocation

As discussed in Part 2, we need to delay actual invocation of the action until SaveChanges(), to do this we return an implementation of an interface called IDataServiceInvokable:

public class ActionInvokable : IDataServiceInvokable
{
    ServiceAction _serviceAction;
    Action _action;
    bool _hasRun = false;
    object _result;

    public ActionInvokable(DataServiceOperationContext operationContext, ServiceAction serviceAction, object site, object[] parameters, IParameterMarshaller marshaller)
    {
        _serviceAction = serviceAction;
        ActionInfo info = serviceAction.CustomState as ActionInfo;
        var marshalled = marshaller.Marshall(operationContext,serviceAction,parameters);

        info.AssertAvailable(site,marshalled[0], true);
        _action = () => CaptureResult(info.ActionMethod.Invoke(site, marshalled));
    }
    public void CaptureResult(object o)
    {
        if (_hasRun) throw new Exception("Invoke not available. This invokable has already been Invoked.");
        _hasRun = true;
        _result = o;
    }
    public object GetResult()
    {
        if (!_hasRun) throw new Exception("Results not available. This invokable hasn't been Invoked.");
        return _result;
    }
    public void Invoke()
    {
        try
        {
            _action();
        }
        catch {
            throw new DataServiceException(
                500,
                string.Format("Exception executing action {0}", _serviceAction.Name)
            );
        }
    }
}

As you can see this does a couple of things, it creates an Action (this time a CLR one - just to confuse the situation i.e. a delegate that returns void), that actually calls the method on your DBContext via reflection passing the marshaled parameters. It also has a few guards, one to insure that Invoke() is only called once, and another to make sure GetResult() is only called after Invoke().

Actions that are bound sometimes

Part 1 and 2 introduce the concept of occasionally bindable actions, but basically an action might not always be available in all states, for example you might not always be able to checkout a movie (perhaps you already have it checked out).

The ActionInfo class has an IsAvailable(…) method which is used by the ActionProvider whenever WCF Data Services need to know if an Action should be advertised or not. The implementation of this will call the method specified in the [OccasionallyBindableAction] attribute. The code is complicated because it supports always return true without actually checking if the actual availability method is too expensive to call repeatedly. This is indicated using the [SkipCheckForFeeds] attribute.

Getting the Sample Code

The sample is on codeplex made up of two projects:

ActionProviderImplementation – the actual implementation of the Entity Framework action provider.
MoviesWebsite – a sample MVC3 website that exposes a simple OData Service

Summary

For most of you downloading the samples and using them to create a OData Service with Actions over the Entity Framework is all you’ll need.

However if you are actually considering tweaking the example or building your own from scratch hopefully you now have enough context!

Happy coding
Alex James
Senior Program Manager, Microsoft.

What happened to application/json in WCF DS 5.0?

dpblogs — Wed, 11 Apr 2012 23:05:59 GMT

The roadmap for serialization formats

We have been talking for a while about a more efficient format for JSON serialization. The new serialization format will be part of the OData v3 protocol, and we believe that the much-improved JSON format should be the default response when requesting application/json.

You may notice that when you upgrade to WCF DS 5.0, requesting the old JSON format is a bit different. To get the old JSON format, you must now explicitly request application/json;odata=verbose or set the MaxDataServiceVersion header to 2.0.

When will I get a 415 response and what can I do about it?

WCF Data Services 5.0 will return a 415 in response to a request for application/json if the service configuration allows a v3 response and if the client does not specify a MaxDataServiceVersion header or specifies a MaxDataServiceVersion header of 3.0. Clients should always send a value for the MaxDataServiceVersion header to ensure forward compatibility.

There are two ways to get a response formatted with JSON verbose:

1. Set the MaxDataServiceVersion header to 2.0 or less. For instance:

GET http://odata.example.org/Items?$top=5 HTTP/1.1

Host: odata.example.org

Connection: keep-alive

User-Agent: Mozilla/5.0 (Windows NT 6.2; WOW64) AppleWebKit/535.19 (KHTML, like Gecko) Chrome/18.0.1025.152 Safari/535.19

Accept: application/json

Accept-Encoding: gzip,deflate,sdch

Accept-Language: en-US,en;q=0.8

Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3

MaxDataServiceVersion: 2.0

2. Request a content type of application/json;odata=verbose. For instance:

GET http://odata.example.org/Items?$top=5 HTTP/1.1

Host: odata.example.org

Connection: keep-alive

User-Agent: Mozilla/5.0 (Windows NT 6.2; WOW64) AppleWebKit/535.19 (KHTML, like Gecko) Chrome/18.0.1025.152 Safari/535.19

Accept: application/json;odata=verbose

Accept-Encoding: gzip,deflate,sdch

Accept-Language: en-US,en;q=0.8

Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3

MaxDataServiceVersion: 3.0

It’s possible to modify the headers with jQuery as follows:

$.ajax(url, {

    dataType: "json", // this tells jquery that you are expcting a json object and so it will parse the data for you.

    beforeSend: function (xhr) {

        xhr.setRequestHeader("Accept", "application/json;odata=verbose");

        xhr.setRequestHeader("MaxDataServiceVersion", "3.0");

    },

    success: function (data) {

       // do something interesting with the data you get back.

    }

});

Why did WCF DS 5.0 ship before JSON light?

We had a set of features that were ready to be released as part of WCF DS 5.0. The more efficient JSON implementation is currently in progress and will be released sometime later this year.

Actions in WCF Data Services – Part 2: How IDataServiceActionProvider works

dpblogs — Wed, 11 Apr 2012 20:17:00 GMT

In this post we will explorer the IDataServiceActionProvider interface, which must be implemented to add Actions to a WCF Data Service.

However if you are simply creating an OData Service and you can find an implementation of IDataServiceActionProvider that works for you (I’ll post sample code with Part 3) then you can probably skip this post.

Now before we continue, to understand this post fully you’ll need to be familiar with Custom Data Service Providers and a good place to start is here.

IDataServiceActionProvider

Okay so lets take a look at the actions interface:

public interface IDataServiceActionProvider
{
    bool AdvertiseServiceAction(
       DataServiceOperationContext operationContext,
       ServiceAction serviceAction,
       object resourceInstance,
       bool resourceInstanceInFeed,
       ref ODataAction actionToSerialize);

    IDataServiceInvokable CreateInvokable(
       DataServiceOperationContext operationContext,
       ServiceAction serviceAction,
       object[] parameterTokens);

   IEnumerable<ServiceAction> GetServiceActions(
       DataServiceOperationContext operationContext);

   IEnumerable<ServiceAction> GetServiceActionsByBindingParameterType(
      DataServiceOperationContext operationContext,
      ResourceType bindingParameterType);

   bool TryResolveServiceAction(
      DataServiceOperationContext operationContext,
      string serviceActionName,
      out ServiceAction serviceAction);
}

You’ll notice that every method either takes or returns a ServiceAction. ServiceAction is the metadata representation of an Action, that includes information like the Action name, its parameters, its ReturnType etc.

When you implement IDataServiceActionProvider you are augmenting the metadata for your service which is defined by your services implementation of IDataServiceMetadataProvider with Actions and handling dispatch to those actions as appropriate.

We added this new interface rather than creating a new version of IDataServiceMetadataProvider because we didn’t have time to add an Action implementation for the built-in Entity Framework and Reflection provider, but we still wanted you be able to add actions when using those providers. This separation of concerns allows you to use the built-in providers and layer in support for Actions on the side.

However one problem remains: to create a new Action you will need access to the ResourceTypes in the your service, so you can create Action parameters and specify Action ReturnTypes. Previously you couldn’t get at the ResourceTypes unless you created a completely custom provider. So to give you access to the ResourceTypes we added an implementation of IServiceProvider to the DataServiceOperationContext class which is passed to every one of the above methods.

Now anywhere you have one of these operationContexts you can get the current implementation of IDataServiceMetadataProvider (and thus the ResourceTypes) like this:

var metadata = operationContext.GetService(typeof(IDataServiceMetadataProvider)) as IDataServiceMetadataProvider;

Exposing ServiceActions

There are 3 methods that the Data Services Server uses to learn about actions:

GetServiceActions(DataServiceOperationContext) – returns every ServiceAction in the service, and is used when we need all the metadata, i.e. if someone goes to $metadata
GetServiceActionsByBindingParameterType(DataServiceOperationContext,ResourceType) – returns every ServiceAction that can be bound to the ResourceType specified. This is used when we are returning an entity and we want to include information about Actions that can be invoked against that entity. The contract here is you should only include Actions that take the specified ResourceType exactly (i.e. no derived types) as the binding parameter to the action. We will call this method once for each ResourceType we encounter during serialization.
TryResolveServiceAction(DataServiceOperationContext,serviceActionName,out serviceAction) – return true if a ServiceAction with the specified name is found.

Now you could clearly implement both GetServiceActionsByBindingParameterType(..) and TryResolveServiceAction(..) by calling GetServiceActions(..), but Data Services tries to avoid loading all the metadata at once wherever possible, so you get the opportunity to provide more efficient targeted implementations.

Basically 99% of the time Data Services doesn’t need every ServiceAction, so it won’t ask for all of them most of the time.

To expose an Action you simply create a ServiceAction and return it from these methods as appropriate. For example to create a ServiceAction that corresponds to this C# signature (where Movie is an entity):

void Rate(Movie movie, int rating)

You would do something like this:

ServiceAction movieRateAction = new ServiceAction(
   “Rate”, // name of the action
   null, // no return type i.e. void
   null, // no return type means we don’t need to know the ResourceSet so use null.
   OperationParameterBindingKind.Always, // i.e this action is always bound to an Movie entities
                                         // other options are Never and Always.
   new [] {
      new ServiceActionParameter(“movie”, movieResourceType),
      new ServiceActionParameter(“rating”, ResourceType.GetPrimitiveType(typeof(int)))
   }
);

As you can see nothing too tricky here.

Advertizing ServiceActions

If you looked at the first post you’ll remember that some Actions are available only in certain states. This is configured when you create your the ServiceAction, something like this:

ServiceAction checkoutMovieAction = new ServiceAction(
   “Checkout”, // name of the action
   ResourceType.GetPrimitiveType(typeof(bool)), // Edm.Boolean is the returnType
   null, // the returnType is a bool, so it doesn’t have a ResourceSet
   OperationParameterBindingKind.Sometimes, // You can’t always checkout a movie
   new [] { new ServiceActionParameter(“Movie”, movieResourceType) }
);

Notice in this example the OperationParameterBindingKind is set to Sometimes which means the Checkout Action is not available for every Movie. So when DataServices returns a Movie it will check with the ActionProvider to see if the Action is currently available. Which it does by calling:

bool AdvertiseServiceAction(
   DataServiceOperationContext operationContext,
   ServiceAction serviceAction, // the action that the server knows MAY be bound.
   object resourceInstance, // the entity which MAY allow the action to be bound.
   bool resourceInstanceInFeed, // whether the server is serializing a single entity or a feed (expect multiple calls).
   ref ODataAction actionToSerialize); // modifying this parameter allows you to do customize things like the URL
                                       // the client will POST to to invoke the action.

For example you might check if the current user (i.e. HttpContext.Current.User) has a Movie checked out already, to decide whether they can Checkout that Movie or not.

The resourceInstanceInFeed parameter needs a special mention. Sometimes working out whether an Action is available is time or resource intensive, for example if you have to do a separate database query. Generally this isn’t a problem if you are returning just one Entity, but if you are returning a whole feed of entities it is clearly undesirable. The OData protocol says that in situations like this you should err by exposing actions that aren’t actually available (and fail later if they are invoked). WCF Data Services doesn’t know if it is expensive to establish action availability, so to help you decide whether to do the check it lets you know whether you are in a feed or not. This way your Action provider can just return true, it if knows it is costly to calculate and it is in a feed.

Invoking ServiceActions

When an action is invoked, your implementation of this is called:

IDataServiceInvokable CreateInvokable(
   DataServiceOperationContext operationContext,
   ServiceAction serviceAction,
   object[] parameterTokens);

Notice you don’t actually invoke the action immediately instead you return an implementation of IDataServiceInvokable, which looks like this:

public interface IDataServiceInvokable
{
object GetResult();
void Invoke();
}

As you can see this is a simple interface, but why do we delay calling the action?

Well actions generally have side-effects so they need to work in conjunction with the UpdateProvider (or IDataServiceUpdateProvider2), to actually save those changes to disk. To support Actions you need an Update Provider like the built-in Entity Framework provider that implements the new IDataServiceUpdateProvider2 interface:

public interface IDataServiceUpdateProvider2 : IDataServiceUpdateProvider, IUpdatable
{
void ScheduleInvokable(IDataServiceInvokable invokable);
}

This allows WCF Data Services to schedule arbitrary work to happen during IDataServiceUpdateProvider.SaveChanges(..), which allows update providers and action providers to be written independently. Which is great because if you are using the Entity Framework you really don’t want to have to write an update provider from scratch.

Now when you implement IDataServiceInvokable you are responsible for 3 things:

Capturing and potentially marshaling the parameters.
Dispatching the parameters to the code that actually implements the Action when Invoke() is called.
Storing any results from Invoke() so they can be retrieved using GetResult()

The parameters themselves are passed as tokens. This is because it is possible to write a Data Service Provider that works with tokens that represent resources, if this is the case you may need to convert these token into actual resources before dispatching to the actual action. What is required depends 100% on the rest of the provider code, so it is impossible to say exactly what you need to do here. However in part 3 well explore doing this for the Entity Framework.

If the first parameter to the action is a binding parameter (i.e. an EntityType or a Collection of EntityTypes) it will be passed as an un-enumerated IQueryable. Most of the time this isn’t too interesting but it does mean you can do nifty tricks like write an action that doesn’t actually retrieve the entities from the database if appropriate.

Summary

This post walked you through the design of IDataServiceActionProvider and the expectations for people implementing this interface. While this is quite a tricky interface to implement, it is low level code and hopefully you will be able to find an existing implementation that works for you. Indeed in Part 3 we will share and walk through an sample implementation for the Entity Framework designed to deliver the Service Author Experience we introduced in Part 1.

If you have any questions let me know.

Alex James
Senior Program Manager, Microsoft

Actions in WCF Data Services – Part 1: Service Author Code

dpblogs — Wed, 11 Apr 2012 00:22:00 GMT

If you read our last post on Actions you’ll know that Actions are now in both OData and WCF Data Services and that they are cool:

“Actions will provide a way to inject behaviors into an otherwise data-centric model without confusing the data aspects of the model, while still staying true to the resource oriented underpinnings of OData."

Our key design goal for RTM was to allow you or third party vendors to create an Action Provider that adds Action support to an existing WCF Data Services Provider. Adding Actions support to the built-in Entity Framework Provider for example.

This post is the first of a series that will in turn introduce:

The Experience we want to enable, i.e. the code the service author writes.
The Action Provider API and why it is structured as it is.
A sample implementation of an Action Provider for the Entity Framework

Remember if you are an OData Service author, happy to use an Action Provider written by someone else, all you need worry about is (1), and that is what this post will cover.

Scenario

Imagine that you have the following Entity Framework model

public class MoviesModel: DbContext
{
        public DbSet<Actor> Actors { get; set; }
        public DbSet<Director> Directors { get; set; }
        public DbSet<Genre> Genres { get; set; }
        public DbSet<Movie> Movies { get; set; }
        public DbSet<UserRental> Rentals { get; set; }
        public DbSet<Tag> Tags { get; set; }
        public DbSet<User> Users { get; set; }
        public DbSet<UserRating> Ratings { get; set; }
}

Which you expose as using WCF Data Services configured like this:

config.SetEntitySetAccessRule("*", EntitySetRights.AllRead);
config.SetEntitySetAccessRule("EdmMetadatas", EntitySetRights.None);
config.SetEntitySetAccessRule("Users", EntitySetRights.None);
config.SetEntitySetAccessRule("Rentals", EntitySetRights.None);
config.SetEntitySetAccessRule("Ratings", EntitySetRights.None);

Notice that some of the Entity Framework data is completely hidden (Users,Rentals,Ratings and of course EdmMetadatas) and the rest is marked as ReadOnly. This means in this service people can see information about Movies, Genres, Actors, Directors and Tags, but they currently can’t edit this data through the service. Essentially some of the database is an implementation detail you don’t want the world to see. With Action for the first time it is easy to create a real distinction between your Data Model and your Service Model.

Now imagine you have a method on your DbContext that looks something like this:

public void Rate(Movie movie, int rating)
{
var userName = GetUsername();
var movieID = movie.ID;

    // Retrieve the existing rating by this user (or null if not found).
    var existingRating = this.Ratings.SingleOrDefault(r =>
        r.UserUsername == userName &&
        r.MovieID == movieID
    );

    if (existingRating == null)
    {
        this.Ratings.Add(new UserRating { MovieID = movieID, Rating = rating, UserUsername = userName });
    }
    else
    {
        existingRating.Rating = rating;
    }
}

This code allows a user to rate a movie, simply by providing a rating and a movie. It uses ambient context to establish who is making the request (i.e. HttpContext.Current.User.Identity.Name), and looks for a rating by that User for that Movie (a user can only rate a movie once), if it finds one it gets modified otherwise a new rating is created.

Target Experience

Now imagine you want to expose this as an action. The first step would be to make your Data Service implement IServiceProvider like this:

public class MoviesService : DataService<MoviesModel>, IServiceProvider
{
   public object GetService(Type serviceType)
   {
       if (typeof(IDataServiceActionProvider) == serviceType)
       {
           return new EntityFrameworkActionProvider(CurrentDataSource);
       }
       return null;
    }
    …
}

Where EntityFrameworkActionProvider is the custom action provider you want to use, in this case a sample provider that we’ll put up on codeplex when Part 3 of this series is released (sorry to tease).

Next configure your service to expose Actions, in the InitializeService method:

config.SetServiceActionAccessRule("*", ServiceActionRights.Invoke);
config.DataServiceBehavior.MaxProtocolVersion = DataServiceProtocolVersion.V3;

As per usual * means all Actions, but you could just as easy expose just the actions you want by name.

Finally with that groundwork done, expose your action by adding the [Action] attribute:

[Action]
public void Rate(Movie movie, int rating)
{

With this done the action will show up in $metadata, like this:

</FunctionImport>

And it will be advertised in Movie entities like this (in JSON format):

{
    "d": {
        "__metadata": {
            …
            "actions": {
                "http://localhost:15238/MoviesService.svc/$metadata#MoviesModel.Rate": [
                    {
                        "title": "Rate",
                        "target": "http://localhost:15238/MoviesService.svc/Movies(1)/Rate"
                    }
                 ]
            }
        },
        …
        "ID": 1,
        "Name": "Avatar"
    }
}

This action can be invoked using the WCF Data Services Client like this:

ctx.Execute(
   new Uri(“http://localhost:15238/MoviesService.svc/Movies(1)/Rate”),
   “POST”,
   new BodyParameter(“rating”,4)
);

or, if you prefer being closer to the metal, more directly like this:

POST http://localhost:15238/MoviesService.svc/Movies(1)/Rate HTTP/1.1
Content-Type: application/json
Content-Length: 20
Host: localhost:15238

{
"rating": 4
}

All very easy don’t you think?

Actions whose availability depends upon Entity State

You may also remember that whether an action is available can depend on the state of the entity or service. For example you can’t Checkout a movie that you already have Checked out. To address this requirement we need a way to support this through attributes too.

Excuse the terrible attribute name (it is only a sample) but perhaps something like this:

[OccasionallyBindableAction("CanCheckout")]
public void Checkout(Movie movie)
{
var userName = GetUsername();
var movieID = movie.ID;

    var alreadyCheckedOut = this.Rentals.Any(r =>
        r.UserUsername == userName &&
        r.MovieID == movieID &&
        r.CheckedIn == null
    );

    if (!alreadyCheckedOut)
    {
        // add a new rental
        this.Rentals.Add(
            new UserRental {
                MovieID = movieID,
                CheckedOut = DateTime.Now,
                UserUsername = userName
            }
        );
    }
}

Notice instead of the [Action] attribute this has an [OccasionallyBindableAction] attribute which takes the name of a method to call to see if this action is available. This method must take one parameter, the same type as the binding parameter of the action (so in this case a Movie) and return a boolean to indicate whether the action should be advertised.

[SkipCheckForFeeds]
public bool CanCheckout(Movie movie)
{
    var username = GetUsername();
    var rental = this.Rentals.SingleOrDefault(
        r => r.UserUsername == username && r.MovieID == movie.ID && r.CheckedIn == null
    );
    if (rental == null) return true;
    else return false;
}

Notice that this method runs a separate query to see if an unreturned rental exists for the current user and movie, if yes then the movie can’t be checked out, if no then the movie can be checked out.

The alert amongst you will have noticed the [SkipCheckForFeeds] attribute. This is here for performance reasons. Why?

Imagine that you retrieve a Feed of Movies, in theory we should call this ‘availability check’ method for every Movie in the feed. Now if the method only needs information in the Movie (i.e. imagine if the Movie has a CanCheckout property) this is not a problem, but in our example we actually issue a separate database query. Clearly running one query to get a feed of items and then a new query for each action in that feed of items is undesirable from a performance perspective.

We foresaw this problem and added some rules to the protocol to address this problem, namely if it is expensive to calculate the availability of an Action, it is okay to advertise the action whether it is available or not. So [SkipCheckForFeed] is used to indicate to our custom Actions Provider that this method is expensive and shouldn’t be called for all the Movies in a feed but should be advertised anyway.

Summary

As you can see our goal is to enable 3rd party Action Provider to provide a highly intuitive way of adding Actions to your OData Service, the above code examples illustrate one possible set of experiences. As you experiment I’m confident that you will find Actions to be a very powerful way to add behaviors to your OData Service.

In Part 2 we will look at the IDataServiceActionProvider interface in detail, and then in Part 3 we’ll walk through an implementation for the Entity Framework (and I’ll post the sample Entity Framework Action Provider sample code).

As always I’m super keen to hear what you think.

Alex James
Senior Program Manager, Microsoft.

WCF Data Services 5.0 RTM Release

dpblogs — Mon, 09 Apr 2012 16:46:00 GMT

I’m very pleased to announce the WCF Data Services 5.0 RTM release. You can download WCF Data Services 5.0 from here. This release includes several client and server features and libraries for .NET 4 and Silverlight 4.

Below is a brief breakdown of the features that are available in this release. Upcoming blog posts will dive into

Vocabularies

By providing the ability to annotate metadata and instance data, vocabularies define a powerful extensibility point for OData. They convey meaning and extra information to enable richer client experiences. Simple vocabulary terms can do things like indicate a property’s acceptable value range. A more complex vocabulary terms could define a mapping between a particular service’s person entity and a vCard schema.

WCF Data Services 5.0 allows data service authors to use vocabularies in $metadata.

Actions

Actions in OData extend the set of operations that can be performed on or with a service or resource. Actions provide a way to inject behaviors into an otherwise data centric model without confusing the data aspects of the model. They stay true to the resource oriented underpinnings of OData. Actions may be used to extend CUD operations, invoke custom operations, etc.

WCF Data Services 5.0 allows setting up a service with Actions as well as invoking actions and service operations with full support for parameters. However, to expose Actions you need to provide or source an implementation of IDataServiceActionProvider that works with the rest of the service. Subsequent blog posts on Actions will dig deeper on this feature. Read more about our actions support here.

Spatial

There has been an explosion of location-aware devices and more demand for location-aware applications. OData supports geospatial data and WCF Data Services 5.0 comes with 16 new spatial primitives and some corresponding operations. This enables data consumers to perform operations on spatial values in filter, select and orderby clauses.

Spatial primitives enable service authors to indicate, for example, that a property is a point, a line, or a polygon. These spatial primitives follow the OGC’s Simple Features standard.

Actions and Functions can be used to extend the operations associated with these primitives. This allows some servers to expose deep algorithms for powerful functionality while other services expose only basic operations. The community can develop vocabularies to describe common categories of advanced operations and indicate which ones a given service supports.

WCF Data Services 5.0 allows addition of spatial type properties to models via Reflection and Custom Service Providers. This enables read/write support in ATOM or JSON formats for all spatial types supported by SQL Server 2008 R2. Moreover, this release supports querying for all entities ordered/filtered by distance to a location (i.e. find all coffee shops near me).

ODataLib:

The ODataLib .NET client and server libraries allow flexible low-level serialization/deserialization according to the OData Protocol Specifications. ODataLib now supports serialization and deserialization of all OData payloads.

EdmLib

ODataLib now ships with EdmLib, a new in-memory metadata system that makes it easy to build an Entity Data Model (EDM) of a service for OData serialization/deserialization. Moreover, EdmLib enables creation and consumption of annotations on any EDM model.

Any/All

WCF Data Services 5.0 increases the expressiveness of WCF Data Services queries to be able to express queries like ‘are there any customers which have no orders’ or ‘are there any customers who only spend more than $100 at our shop’. We support the ‘any’ and ‘all’ canonical functions via the WCF Data Services client LINQ support.

Better Support for Inheritance

WCF Data Services 5.0 supports both exposing and consuming models which have properties (primitive, complex and navigation) defined on subtypes of the base type associated with the set.

Collections

WCF Data Services 5.0 adds support for properties as collections of primitive or complex types. This enables easier modeling of things like lists of alternate email addresses for a Customer.

Named Streams

WCF Data Services 5.0 release allows 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.

Patch Method Support

PATCH is now a standard and is semantically equivalent to the MERGE method. WCF Data Services 5.0 release supports the PATCH method as a synonym to MERGE.

Prefer Header Support

Following the semantics of the Prefer header, WCF Data Services now support returning responses to Insert and Update requests.

We look forward to hearing your thoughts on the release.

Turker Keskinpala

Program Manager

WCF Data Services/OData Team

Announcing OData T4 for C#, Preview 1

dpblogs — Thu, 19 Jan 2012 21:35:52 GMT

I’m very excited to announce the release of OData T4 for C# Preview 1, for the October 2011 CTP of the next version of WCF Data Services libraries, with support for code generation of service operations. The goal of this T4 preview and subsequent ones will be to get community feedback on the templates before having “Add Service Reference” natively generate T4 templates out of the box in a future release.

Note that support for service operations was added to the T4 because many customers already use it and it has been a regularly requested feature by the community. Having said that, some support for actions/functions (which are the way forward for custom operations) will be introduced in an upcoming refresh to the template.

We are looking to refresh the template by first week of February with feedback from the community as well as any bug fixes reported as well as once more by the time WCF Data Services V3 ships

So please give your feedback at our team forum.

How do I Use it?

- Install Nuget package manager

- Install October 2011 CTP

- Add a Service Reference to an OData service

o This downloads the metadata

- Right-click Add reference-> “Manage NuGet packages”

- Search for OdataT4 template

- Install OdataT4-CS package

- This will add a Refrence.tt file in your project

Known Issues, Limitations, and Workarounds

- I get the following error after adding the Nuget package: “Running transformation: System.IO.DirectoryNotFoundException: Could not find a part of the path '<projectDirecotryRoot>\Service References\ServiceReference1\service.edmx'.T4 has incorrect edmx file path“

The current template assumes an ‘$projectRoot\ServiceRefrence1\service.edmx”. If your edmx file is in a custom location change the MetadataFilepath property, in Refrence.tt, to point to the correct path.

- There is no T4 for VB

We are looking to release our first preview of the VB template at the time of next refresh

- There is no support for spatial

Spatial support will be included at end of January refresh

Thanks

Ahmed Moustafa

Program Manager

Using Geospatial Data

dpblogs — Tue, 18 Oct 2011 00:11:21 GMT

This CTP of WCF Data Services adds support for geospatial data. The release allows use of all of the OData geospatial data types and the geo.distance() canonical function. This enables two key scenarios:

Read and write geospatial data (all types supported by Sql Server 2008 R2).
Find all entities (i.e. coffee shops) near a location.

Before I illustrate use of these features, I'd like to mention some limitations of this CTP. First, (and most significantly) WCF Data Services providers only support geospatial data with custom or reflection providers. You can't use Entity Framework at this time. OData will support geospatial data over EF as soon as there is an EF release that supports geospatial data.

Second, this CTP does not allow null values in geospatial properties. Nulls will be added by RTM.

OK, enough on what it doesn't do. Let's interact with some geospatial data!

Adding Geospatial Data to the Model

https://gist.github.com/1293201 is a simple OData service which lets a user find people and businesses near them. I'll describe the key geospatial parts here.

First, the entities each have a property of type GeometricPoint (one of the new geospatial types):

[DataServiceKey("BusinessId")]
public class Business
{
public int BusinessId { get; set; }
public string Name { get; set; }
public string Description { get; set; }
public GeographicPoint Location { get; set; }
}

[DataServiceKey("Username")]
public class User
{
public User()
{
this.Friends = new List<User>();
}

public string Username { get; set; }
public IList<User> Friends { get; set; }
public GeographicPoint LastKnownLocation { get; set; }
}

To create sample data values for geospatial types, I use the GeographyFactory (the data creation API is likely to change before the RTM, but this correct for now):

new User { Username = "Chai", LastKnownLocation = GeographyFactory.Point(47.7035614013672, -122.329437255859) }

Finally, geospatial data is only supported in V3 of the OData protocol:

public static void InitializeService(DataServiceConfiguration config)
{
config.DataServiceBehavior.MaxProtocolVersion = DataServiceProtocolVersion.V3;
}

That's it. Geospatial data values are just primitive data values like any other. It requires as little effort to use them as it does to use a DateTime.

Writing the client

Just use Add Service Reference to codegen a client. Consuming geospatial data is no different than consuming any other V3 OData service.

Reading and writing geospatial values

There's nothing special about geospatial values. For example, to update your last known location, you would query for your User entity, set the value of its LastKnownLocation, and call SaveChanges().

Enabling geo.distance queries

This sample service is interesting because it allows users to find nearby friends and businesses. We want to write queries that filter or orderby geo.distance().

Unfortunately, the October CTP does not include an in-memory implementation for distance. Computing distance on a round earth is complicated. You'll need to find a good implementation for this operation (Sql Server has such an implementation). Once you have it, you can use the following glue code to hook it up.

public static void InitializeService(DataServiceConfiguration config)
{
// ...

// Register my operations
SpatialOperations.Register(2.0, new MyOperations());
}

internal class MyOperations : SpatialOperations
{
public override double Distance(Geometry operand1, Geometry operand2)
{
// TODO: Put your code here.
throw new NotImplementedException();
}

public override double Distance(Geography operand1, Geography operand2)
{
// TODO: Put your code here.
throw new NotImplementedException();
}
}

Making a distance query

Now that you've got a service that supports geo.distance(), we want to query it. Here are a couple of queries we can run:

var localStuff = new LocalStuff(new Uri("http://localhost/LocalStuff.svc", UriKind.Absolute));

var me = localStuff.Users.First(u => u.Username == "Chang");

var myNearbyFriends = me.Friends
.Where(friend => friend.LastKnownLocation.Distance(me.LastKnownLocation) < 1000.0);
var moviesNearMe = localStuff.Businesses
.Where(b => b.Description.Contains("movie"))
.OrderBy(b => b.Location.Distance(me.LastKnownLocation))
.Take(3);

Have fun with the new geospatial data features. Please provide any feedback on the OData.org mailing list.

Actions in WCF Data Services

dpblogs — Mon, 17 Oct 2011 23:03:31 GMT

The October 2011 CTP of WCF Data Services adds powerful, but incomplete support for Actions. The motivation behind Actions stems from wanting to advertise in an OData entry an invocable ‘Action’ that has a side-effect on the OData service.

This statement is broad, but deliberately so; Actions have a lot of power.

Using WCF Data Services to Invoke an Action:

This release’s WCF Data Services client can invoke Actions that have no parameters with any return type (i.e. void, Feed, Entry, ComplexType, Collection of ComplexType, PrimitiveType or Collection of PrimitiveType.

To invoke Actions you call either Execute(..) for void actions or Execute<T>(..) for everything else. For example:

var checkedOut = ctx.Execute<bool>(
   new Uri(“http://server/service.svc/Movies(6)/Checkout”),
   HttpMethod.Post,
   true
).Single();

Here the Execute<T> function takes the Uri of the Action you want to invoke, the HttpMethod to use (which in this case is Post because we are invoking a side-effecting action), and singleResult=true to indicate there is only one result (i.e. it is not a collection). The method returns a QueryOperationResponse<bool>, which implements IEnumerable<bool>, so we call Single() to get the lone boolean that is the result of invoking the action.

NOTE: Needing to specify singleResult=true is a temporary CTP only requirement, because in the CTP our deserialization code can’t automatically detect whether the result is a collection or single result.

A nice side-effect of this new feature is that you can now call ServiceOperations too, so long as you craft the full Uri (including any parameters) yourself. For example, the code below calls a ServiceOperation called GetMoviesByGenre that takes a single parameter called Genre and returns a Collection (or feed) of Movies using a Get:

var movies = ctx.Execute<Movie>(
   new Uri(“http://server/service.svc/GetMoviesByGenre?genre=’Comedy’”),
   HttpMethod.Get,
   true
);

foreach(var movie in movies) {
// do something
}

Coming Soon…

By RTM we plan to add full support for parameters, both for actions and service operations.

The current plan is for a new BodyParameter class that could be used to specify Actions parameters like this:

var checkedOutForAWeek = ctx.Execute<bool>(
   new Uri(“http://server/service.svc/Movies(6)/Checkout”),
   HttpMethod.Post,
   new BodyParameter("noOfDays", 7)
).Single();

And a new UriParameter class that could be used to specify ServiceOperation parameters too:

var movies = ctx.Execute<Movie>(
   new Uri("http://server/service.svc/GetMoviesByGenre"),
   HttpMethod.Get,
   new UriParameter("genre", "Comedy")
);

Setting up a WCF Data Service with Actions:

Unfortunately, creating actions with WCF Data Services in this release is quite tricky because it requires a completely Custom Data Service Provider, but we are striving to make this easy by RTM.

This CTP’s WCF Data Services Server only supports one parameter (i.e. the binding parameter), again this will change by RTM.

To get started with actions, first create a ServiceAction in your IDataServiceMetadataProvider2 implementation; something like this:

ServiceAction checkout = new ServiceAction(
   "Checkout",
   ResourceType.GetPrimitiveResourceType(typeof(bool)),
   null,
   new List<ServiceOperationParameter>{
      new ServiceOperationParameter("movie", movieResourceType)
   },
   true
);
checkout.SetReadOnly();

ServiceAction currently derives from ServiceOperation, so you will need to add any ServiceActions that you create to the collection of ServiceOperations you expose via both IDataServiceMetadataProvider.ServiceOperations and IDataServiceMetadataProvider.TryResolveServiceOperation(..). Also because Data Services are locked down by default you will need to configure your service to expose your actions using SetServiceOperationAccessRule(..).

IDataServiceMetadataProvider2 also adds a new method to find actions possibly bound to a ResourceType instance, (i.e. to an individual Movie). This is so that when the WCF Data Service is serializing Entities it doesn’t need to walk over all the metadata to find Actions that might bind to a particular entity. Here is a naïve implementation, where _sop is a list of all ServiceOperations:

public IEnumerable<ServiceOperation> GetServiceOperationsByResourceType(ResourceType resourceType)
{
return _sops.OfType<ServiceAction>()
.Where(a => a.Parameters.Count > 0 && a.Parameters.First().ParameterType == resourceType);
}

Next implement IDataServiceQueryProvider2.IsServiceOperationAdvertisable(..) to tell Data Services whether an Action should be advertised on a particular entity:

public bool IsServiceOperationAdvertisable(
   object resourceInstance,
   ServiceOperation serviceOperation,
   ref Microsoft.Data.OData.ODataOperation operationToSerialize
){
   Movie m = resourceInstance as Movie;
   if (m == null) return false;
   var checkedOut = GetIsCheckedOut(m, HttpContext.Current.User);

   if (serviceOperation.Name == "Checkout" && !checkedOut) return true;
   else if (serviceOperation.Name == "Checkin" && checkedOut) return true;
   else return false;
}

Here resourceInstance is the instance that is being serialized to the client, serviceOperation is the ServiceAction that the server is considering advertising, and operationToSerialize is an OData-structure representing the action information that’ll be serialized if you return true (note you can change properties on this class if for example you want to override the title or target of the Action in the payload).

As you can see, this code knows that only Movies have actions, and that it has only two actions; Checkin and Checkout. It calls an implementation-specific method to work out whether the current user has the current movie checked out and then uses this information to decide whether to advertise the Action.

Next you need to implement IDataServiceUpdateProvider2.InvokeAction(..) so that when a client invokes the Action you actually do something:

public object InvokeServiceAction(object dataService, ServiceAction action, object[] parameters)
{
   if (action.Name == "Checkin")
   {
      Movie m = (parameters[0] as IQueryable<Movie>).SingleOrDefault();
      return Checkin(m);
   }
   else if (action.Name == "Checkout")
   {
      Movie m = (parameters[0] as IQueryable<Movie>).SingleOrDefault();
      return Checkout(m);
   }
   else
      throw new NotSupportedException();
}

As you can see, this code figures out which action is being invoked and then gets the binding parameter from the parameters collection. The binding parameter will be an unexecuted query (it is unexecuted because this gives a provider the opportunity to invoke an action without actually retrieving the parameter from the datasource, if indeed that is possible), so we extract the Movie by casting parameters[0] to IQueryable<Movie> and calling SingleOrDefault, and then we call the appropriate code for the action directly.

And we are done…

WARNING: This code will need to change by RTM so that Actions actually get invoked during IDataServiceUpdateProvider.SaveChanges(..). This will involve creating delegates and returning something that isn’t the actual results, but rather something from which you can get the results later. See this post on implementing IDataServiceUpdateProvider for more context if you are interested.

Conclusion:

As you can see, Actions is a work in progress, and many things are likely to change. Even though it is a lot of work to implement actions with the CTP (mainly because you have to implement IDataServiceMetadataProvider2, IDataServiceQueryProvider2 and IDataServiceUpdateProvider2 from scratch), it’s worth trying because Actions opens up the world of behaviors to OData.

Come RTM we expect the whole experience to be a lot better.

Let me know if you have any questions.

Alex James
Program Manager
OData Team

Introducing the OData Library

dpblogs — Fri, 14 Oct 2011 17:59:00 GMT

This blog talks about a new feature delivered in the WCF Data Services October CTP that can be downloaded here.

WCF Data Services’ latest CTP includes a new stand-alone library for working directly with OData. The library makes public some underpinnings of WCF Data Services (the server and client library), and we made this library stand-alone to allow its use independent from WCF Data Services. The library provides a low-level implementation of some components needed to build an OData producer/consumer. Specifically, we focused on the core tasks of reading/writing OData from streams in the library’s first version, and in the future we hope to add more fundamental OData functionality (possibly OData Uri reading and writing). However, we haven’t made any final plans on what we will add, and we welcome your feedback.

I want to take a minute to explain this library’s relation to the existing WCF Data Services products; this library doesn’t replace WCF Data Services. If you want a great end-to-end solution for creating and exposing your data via an OData endpoint, then the WCF Data Services server library is (and will continue to be) the way to go. If you want a great OData Feed-consuming client with auxiliary support, like code generation and LINQ translation, then WCF Data Services’ client library is still your best bet. However, we also recognize that people are exploring creative possibilities with OData, and to help them build their own solutions from scratch we made the components we use as part of the WCF Data Services stack available as a stand-alone library.

We have published the OData library’s latest source code for the on codeplex (http://odata.codeplex.com) as shared source for developers on .NET and other platforms

The CodePlex source code includes the samples that I have attached to this blog post, and I’ll walk through a couple of those samples to illustrate reading and writing OData.

Writing a Single Entity

To hide the library’s details of stream-reading/writing the OData Library uses an abstraction called a Message, which consists of stream and header interfaces (IODataRequestMessage, IODataResponseMessage). The example below walks through the basics of single-entry writing using an implementation of the messages that work over HTTPClient (this implementation is available in the samples project).

The library uses a class called the ODataMessageWriter to write the actual body of a single ODataMessage (request or response). The ODataMessageWriter has a bunch of methods on it that can be used for writing small non-streaming payloads, such as single properties or individual complex-type values. For larger payloads (such as entities and collections of entities) the ODataMessageWriter has methods that create streaming writers for each payload type. The example shows how to use the ODataMessageWriter methods to create an ODataEntryWriter that can be used to write a single OData entry.

Finally, the sample goes on to use the ODataEntryWriter to write a single Customer entry along with four primitive properties and two deferred links. The samples project includes a few samples that show how to write an expanded navigation link as well.

Writing Full Sample

 1: HTTPClientRequestMessage message = new HTTPClientRequestMessage(uri);

 2: message.SetHeader("Accept", formatKind == ODataFormat.Json ? 
          "application/json" : "application/atom+xml");

 3: message.Method = HttpMethod.Post;

 4: message.SetHeader("MaxDataServiceVersion", maxVersion.ToHeaderValue());

5:

 6: // create the writer, indent for readability of the examples.

 7: ODataMessageWriterSettings writerSettings = 
          new ODataMessageWriterSettings() {

 8:     Indent = true,             //pretty printing

 9:     CheckCharacters = false,   //sets this flag on the XmlWriter for ATOM

 10:     BaseUri = new Uri(baseUri),//set the base uri to use in relative links

 11:     Version = version //set the Odata version to use when writing the entry

 12: };

 13: writerSettings.SetContentType(formatKind);

14:

 15: //create message writing for the message

 16: using (ODataMessageWriter messageWriter = 
           new ODataMessageWriter(message, writerSettings))

 17: {

 18:     //creates a streaming writer for a single entity

 19:     ODataWriter writer = messageWriter.CreateODataEntryWriter();

20:

 21:     // start the entry

 22:     writer.WriteStart(new ODataEntry()

 23:     {

 24:         // the edit link is relative to the 
 //baseUri set on the writer in the case

 25:         EditLink = new Uri("/Customers('" + 
                       dataSource.Customers.First().CustomerID +
                       "')", UriKind.Relative),

 26:       Id = "Customers('" + dataSource.Customers.First().CustomerID + "')",

 27:         TypeName = "NORTHWNDModel.Customer",

 28:         Properties = new List<ODataProperty>(){

 29:             new ODataProperty(){ Name = "CustomerID", Value = 
                                  dataSource.Customers.First().CustomerID },

 30:             new ODataProperty(){ Name = "CompanyName", Value = 
                                  dataSource.Customers.First().CompanyName },

 31:             new ODataProperty(){ Name = "ContactName", Value = 
                                  dataSource.Customers.First().ContactName },

 32:             new ODataProperty(){ Name = "ContactTitle", Value = 
                                  dataSource.Customers.First().ContactTitle }

 33:         }

 34:     });

35:

 36:     //create a non-expanded link for the orders navigation property

 37:     writer.WriteStart(new ODataNavigationLink()

 38:     {

 39:         IsCollection = true,

 40:         Name = "Orders",

 41:         Url = new Uri("http://microsoft.com/Customer(" + 
                     dataSource.Customers.First().CustomerID + ")/Orders")

 42:     });

 43:     writer.WriteEnd(); //ends the orders link

44:

 45:     //create a non-expanded link for the employees navigation property

 46:     writer.WriteStart(new ODataNavigationLink()

 47:     {

 48:         IsCollection = true,

 49:         Name = "Employees",

 50:         Url = new Uri(

 51:             "http://microsoft.com/Customer(" + 
                  dataSource.Customers.First().CustomerID + ")/Employees")

 52:     });

 53:     writer.WriteEnd(); //ends the Employees link

54:

 55:     writer.WriteEnd(); //tells the writer we are done writing the entity

 56:     writer.Flush(); //always flush at the end

 57: }

Reading a Single Entity

Let’s look at an example that shows OData deserialization via the library. The example method below demonstrates how to issue a request to the Netflix OData feed for the set of Genres and parse the response.

The example below makes use of the same ODataMessage classes as the previous example (the HTTPClientMessage), but first creates an HTTPClientRequestMessage that targets the Genres URL for the OData Netflix feeds, and then executes the request to get an HTTPClientResponseMessage that represents the response returned by the Netflix services. For readability, the example just outputs the data in the response to a text file afterwards.

The example below uses an IEdmModel not used in the writer example above. When the ODataMessageReader is created an IEdmModel is passed in as a parameter – the IEdmModel is essentially an in-memory representation of the metadata about the service that is exposed via the $metadata url. For a client component the easiest way to create the IEdmModel is to use the ReadMetadata method in the OData Library that creates an in-memory IEdmModel by parsing a $metadata document from the server. For a server, you would generally use the APIs included in the Edm Library (Microsoft.Edm.dll) to craft a model. Providing a model for OData parsing provides key benefits:

o The reader will validate that the entities and properties in the documents being parsed conform to the model specified

o Parsing is done with full type fidelity (i.e. that wire types are converted to the model types when parsed); this is especially important when parsing JSON because the JSON format only preserves 4 types and the OData protocol supports many more. There are configuration options to change how this is done, but I won’t discuss them here for space reasons.

o If the service defines feed customizations, the model contains their definitions and the readers (and writers) will only know to apply them correctly if provided a model.

o JSON can only be parsed when a model is provided (this is a limitation of the library and we may add JSON parsing without a model at some point in the future). ATOM parsing without a model is supported.

In the example below an ODataFeedReader is created out of the ResponseMessageReader to read the contents of the response stream. The reader works like the XmlReader in the System.XML library, with which many of you will be familiar. Calling the Read() method moves the reader through the document, and each time Read() is called the reader changes to a specific state that depends on what the reader is currently reading, which is represented by an “Item”. For instance, when the reader reads an entry in the feed, it will go to the StartEntry state, and the Item on the reader will be the ODataEntry being read –there are similar states for Feeds and Links. Importantly, when the reader is in a start state (StartEntry, StartFeed, StartLink, etc) the reader will have an Item it has created to hold the Entry/Feed/Link that it is reading, but the Item will be mostly empty because the reader has not actually read it yet. It’s only when the reader gets to the end states (EndEntry, EndFeed, EndLink) that the Item will be fully populated with data.

 1: public void ExecuteNetflixRequest(IEdmModel model, string fileName)

 2: {

 3:     //we are going to create a GET request to the OData Netflix Catalog

 4:     HTTPClientRequestMessage message = new HTTPClientRequestMessage(
                   "http://odata.netflix.com/v2/Catalog/Genres");

 5:     message.SetHeader("Accept", "application/json");

 6:     message.SetHeader("DataServiceVersion", 
                   ODataUtils.ODataVersionToString(ODataVersion.V2));

 7:     message.SetHeader("MaxDataServiceVersion", 
                   ODataUtils.ODataVersionToString(ODataVersion.V2));

8:

 9:     //create a text file to write the response to and create a textwriter

 10:     string filePath = fileName;

 11:     using (StreamWriter outputWriter = new StreamWriter(filePath))

 12:     {

 13:         //use an indented text writer for readability

 14:         this.writer = new IndentedTextWriter(outputWriter, " ");

15:

 16:         //issue the request and get the response as an ODataMessage. 
 //Create an ODataMessageReader over the response

 17:         //we will use the model when creating the reader 
 //as this will tell the library to validate when parsing

 18:         using (ODataMessageReader messageReader = 
                  new ODataMessageReader(message.GetResponse(),

 19:             new ODataMessageReaderSettings(), model))

 20:         {

 21:             //create a feed reader

 22:             ODataReader reader = messageReader.CreateODataFeedReader();

 23:             while (reader.Read())

 24:             {

 25:                 switch (reader.State)

 26:                 {

 27:                     case ODataReaderState.FeedStart:

 28:                         {

 29:                             //this is just the beginning of the feed, 
 //data will not be parsed yet

 30:                             ODataFeed feed = (ODataFeed)reader.Item;

 31:                             this.writer.WriteLine("ODataFeed:");

 32:                             this.writer.Indent++;

 33:                         }

34:

 35:                         break;

36:

 37:                     case ODataReaderState.FeedEnd:

 38:                         {

39: //this is the end of feed state.
//The entire message
//has been read at this point

 40:                             ODataFeed feed = (ODataFeed)reader.Item;

 41:                             if (feed.Count != null)

 42:                             {

 43:                                 //if there is an inlinecount value
 // write the value out

 44:                                 this.writer.WriteLine("Count: " + 
                                             feed.Count.ToString());

 45:                             }

 46:                             if (feed.NextPageLink != null)

 47:                             {

 48:                                 //if there is a next link 
 //write that link as well

 49:                                 this.writer.WriteLine("NextPageLink: " + 
                                             feed.NextPageLink.AbsoluteUri);

 50:                             }

51:

 52:                             this.writer.Indent--;

 53:                         }

54:

 55:                         break;

56:

 57:                     case ODataReaderState.EntryStart:

 58:                         {

 59:                             //this is just the start of the entry.

 60:                             //Properties of the entity will not be parsed yet

 61:                             ODataEntry entry = (ODataEntry)reader.Item;

 62:                             this.writer.WriteLine("ODataEntry:");

 63:                             this.writer.Indent++;

 64:                         }

65:

 66:                         break;

67:

 68:                     case ODataReaderState.EntryEnd:

 69:                         {

 70:                             //at the point the whole entry has been read

 71:                             //and the properties of the entity are available

 72:                             ODataEntry entry = (ODataEntry)reader.Item;

 73:                             this.writer.WriteLine("TypeName: " 
                                         + (entry.TypeName ?? "<null>"));

 74:                             this.writer.WriteLine("Id: " 
                                         + (entry.Id ?? "<null>"));

 75:                             if (entry.ReadLink != null)

 76:                             {

 77:                                 this.writer.WriteLine("ReadLink: " 
                                            + entry.ReadLink.AbsoluteUri);

 78:                             }

79:

 80:                             if (entry.EditLink != null)

 81:                             {

 82:                                 this.writer.WriteLine("EditLink: " 
                                            + entry.EditLink.AbsoluteUri);

 83:                             }

84:

 85:                             if (entry.MediaResource != null)

 86:                             {

 87:                                 this.writer.Write("MediaResource: ");

 88:                                 this.WriteValue(entry.MediaResource);

 89:                             }

90:

 91:                             this.WriteProperties(entry.Properties);

92:

 93:                             this.writer.Indent--;

 94:                         }

95:

 96:                         break;

97:

 98:                     case ODataReaderState.NavigationLinkStart:

 99:                         {

 100:                             //navigation links have their own states.

 101:                             //This could be an expanded link and include 
 //an entire expanded entry or feed.

 102:                             ODataNavigationLink navigationLink = 
                                       (ODataNavigationLink)reader.Item;

 103:                             this.writer.WriteLine(navigationLink.Name 
                                       + ": ODataNavigationLink: ");

 104:                             this.writer.Indent++;

 105:                         }

 106:

 107:                         break;

 108:

 109:                     case ODataReaderState.NavigationLinkEnd:

 110:                         {

 111:                             ODataNavigationLink navigationLink = 
                                      (ODataNavigationLink)reader.Item;

 112:                             this.writer.WriteLine("Url: " +

 113:                                 (navigationLink.Url == null ? "<null>" 
                                       : navigationLink.Url.AbsoluteUri));

 114:                             this.writer.Indent--;

 115:                         }

 116:

 117:                         break;

 118:                 }

 119:             }

 120:         }

 121:     }

 122: }

This is a quick introduction to the new OData Library included in this CTP. The post’s attached samples walk through the basics of OData feed creation and consumption via the library. We welcome any feedback you have on the library so don’t hesitate to contact us.

Shayne Burgess
Program Manager – OData Team

Vocabularies in WCF Data Services

dpblogs — Fri, 14 Oct 2011 00:42:30 GMT

One new feature in WCF Data Services October 2011 CTP is Vocabularies. You can learn more about vocabularies and how they are supported in OData here. In a nutshell, a vocabulary is a namespace containing terms where each term is a named metadata extension for an OData service. In this post, I’ll explain how to use this feature to produce an OData service extended with vocabularies, give an example of how to consume annotated metadata on the client side, and finally give some examples of annotations supported in the CTP.

Following are a few example uses which might leverage vocabularies:

Validation metadata may be invented, such that a service may describe valid ranges, value lists, expressions, etc. for properties of entity types.
Visualization metadata may be defined to support generic browsing and visualization of data published via OData.
Adaptations of micro formats or RDF vocabularies may be defined in terms of vocabularies to enable bridging and integration between OData Services and other linked data and semantic web technologies

Applying Annotations to Data Service

In the WCF Data Services October CTP it’s possible to apply annotations to a data service and produce a $metadata endpoint which is extended by vocabularies. Let’s look at how to achieve this in this new version of the WCF Data Services.

Applying annotations to a data service is a two-step process:

· Author an annotations file

· Configure the data service to use produce an annotated $metadata endpoint

Let’s take a closer look at these steps through a simple scenario. Imagine the following simple model of a Person entity shown in CSDL:

<Key>

</Key>

</EntityType>

</EntityContainer>

</Schema>

Suppose, as the service owner, you want to extend the service metadata using a term which describes a valid range of values for certain properties(the Age property in this case). The first thing you’d need to do is to author an annotation file targeting your EDM.

Authoring an annotations file

To support vocabularies in EDM, we specified a new CSDL syntax used to apply terms. This makes it possible to apply vocabularies using familiar EDM constructs and existing reference mechanisms. An annotations file is an XML document that specifies how terms from one or more vocabularies are applied to a target model.

The following is an example of how to apply a “Validation” vocabulary’s “Range” term to a “Person.Age” property:

</TypeAnnotation>

</Annotations>

</Schema>

The annotations file is a CSDL which uses the new annotation syntax. The Target attribute of <Annotations> specifies that the annotation is being applied to the Person entity’s Age property.. The Term attribute of the <TypeAnnotation> specifies that the term being applied is called “Range”. <PropertyValue> elements set the values for the two properties of the Range term. The “Validation” identifier used to qualify the term name in the annotations is an alias for the globally unique namespace, specified by NamespaceUri="http://vocabularies.odata.org/Validation".

The next step is to configure the data service to use the annotations and to produce an extended $metadata endpoint.

Configuring the data service

In the October 2011 CTP of WCF Data Services, we added the following property to the DataServiceConfiguration class:

public Func<Microsoft.Data.Edm.IEdmModel, IEnumerable<Microsoft.Data.Edm.IEdmModel>> AnnotationsBuilder

Following is an example of the InitializeServer method that shows how to use the AnnotationsBuilder to configure the service to use the annotations:

public static void InitializeService(DataServiceConfiguration config)

{

string annotationsFile = @"D:\Vocabularies\Annotations\Annotations.xml";

config.SetEntitySetAccessRule("People", EntitySetRights.AllRead);

config.DataServiceBehavior.MaxProtocolVersion = DataServiceProtocolVersion.V3;

config.AnnotationsBuilder = (model) =>

{

IEdmModel annotationsmodel;

IEnumerable<EdmError> errors;

var xmlreaders = new XmlReader[] { XmlReader.Create(annotationsFile) };

bool parsed = CsdlReader.TryParse(xmlreaders, out annotationsmodel, out errors, model);

return parsed ? new IEdmModel[] { annotationsmodel } : null;

};

}

That’s it! Running the service and navigating to the $metadata endpoint will result in the following payload:

<?xml version="1.0" encoding="UTF-8"?>

<edmx:Edmx xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx" Version="1.0">

<edmx:DataServices xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:MaxDataServiceVersion="3.0" m:DataServiceVersion="1.0">

<Key>

</Key>

</EntityType>

</EntityContainer>

</TypeAnnotation>

</Annotations>

</Schema>

</edmx:DataServices>

</edmx:Edmx>

Client Side

On the client side, you can use System.Data.Edm to parse the metadata and extract the annotations. The example below illustrates how to get the vocabulary annotations applied to Person.Age:

//GET service metadata

string metadata = GetMetadata(metadataUri);

//Parse the metadata

IEdmModel annotatedModel;

IEnumerable<EdmError> errors;

XmlReader xmlReader = XmlReader.Create(new StringReader(metadata));

bool parsed = EdmxReader.TryParse(xmlReader, out annotatedModel, out errors);

//Find the Age property of Person EntityType

IEdmProperty age = null;

if (EdmTypeKind.Entity == annotatedModel.FindType("VocabSample.Person").TypeKind)

{

IEdmEntityType person = (IEdmEntityType)annotatedModel. FindType("VocabSample.Person");

age = person.FindProperty("Age");

}

//Find the vocabulary annotations applied to the Age property

IEnumerable<IEdmVocabularyAnnotation> annotations = null;

if (null != age)

{

annotations = age.VocabularyAnnotations(annotatedModel);

}

You can get the name of the terms applied to the Age property as follows:

foreach (IEdmVocabularyAnnotation annotation in annotations)

{

if (annotation.AnnotationKind == EdmAnnotationKind.TermType)

{

IEdmTypeAnnotation typeAnnotation = (IEdmTypeAnnotation)annotation;

Console.WriteLine(typeAnnotation.Term.Name);

}

You can access the properties of a term as follows:

foreach (IEdmVocabularyAnnotation annotation in annotations)

{

if (annotation.AnnotationKind.Equals(EdmAnnotationKind.TermType))

{

IEdmTypeAnnotation typeAnnotation = (IEdmTypeAnnotation)annotation;

if (typeAnnotation.Term.Name == "Range")

{

IEdmPropertyValueBinding min = null;

IEdmPropertyValueBinding max = null;

foreach (var prop in typeAnnotation.Properties)

{

if (prop.BoundProperty.Name == “Min")

{

min = prop;

}

else if (prop.BoundProperty.Name == "Max")

{

max = prop;

}

IEdmDecimalValue minVal = (IEdmDecimalValue)min.Value;

Console.WriteLine(minVal.Value);

IEdmDecimalValue maxValue = (IEdmDecimalValue)max.Value;

Console.WriteLine(maxValue.Value);

}

We will be focusing more on the completeness and usability of the client API in the upcoming releases.

Example Annotations

In the example above, we looked at annotating a Property of an entity. In OData annotations are supported on several CSDL elements. In WCF Data Services October 2011 CTP, it’s possible to annotate the following in the following way assuming the service that is being annotated is the sample Northwind service:

EntityContainer

</Annotations>

EntitySet

</Annotations >

EntityType

</TypeAnnotation>

</Annotations>

Property

</Annotations>

NavigationProperty

</Annotations>

Summary

Vocabularies feature is a significant new feature that we added to Data Services. Vocabularies increase the expressiveness of OData metadata document to enable a broader spectrum of experiences. Clients and data providers can cooperate to enable richer experiences by enhancing OData metadata with vocabularies.

As always, we are very interested in hearing your thoughts and feedback.

Turker Keskinpala

Program Manager

WCF Data Services/OData Team

Announcing WCF Data Services Oct 2011 CTP for .NET 4 and Silverlight 4

dpblogs — Thu, 13 Oct 2011 23:41:11 GMT

I’m very excited to announce the release of the October 2011 CTP of the next version of WCF Data Services libraries. This release includes libraries for .NET 4 and Silverlight 4 with new client and server features in addition to those included in our last October 2010, March 2011 and June 2011 CTPs.

Below is a brief summary of the features available in this CTP. Subsequent blog posts will discuss each feature in more detail and provide examples of how to use each.

Actions:

The inability to kick-off a (non-CRUD) related server process via an OData hypermedia action was an omission somewhat mitigated by low-fidelity workarounds, such as modeling hypermedia actions as entities. Actions will provide an ROA-underpinned means to inject behaviors into an otherwise data-centric model without obfuscating its data aspects, and (like navigation properties) will be advertised in the payload.

This CTP supports invoking ServiceOperation via handcrafted URL parameters, and also enables invoking parameterless actions that can return void, a single object, or a collection of objects in JSON or ATOM format.

Though this release contains the lower layers of Actions support, which enables custom OData providers to use them, it doesn’t yet enable Actions over EF-Provider out-of-box; a refresh of WCF Data Services succeeding the release of the next Entity/.NET Framework will enable this natively.

Spatial:

The ubiquity of location-aware devices demands a data type suited to communicating geospatial data, so this CTP delivers 16 new spatial OData primitives and some corresponding operations which data consumers can perform on spatial values in filter, select, and orderby clauses.

Spatial primitives follow the OGC’s Simple Features standard, but unlike other primitives, the associated operation set is extensible, which allows some servers to expose deep algorithms for powerful functionality while other servers expose only basic operations. Since the server advertises these advanced capabilities via the Actions feature, they’re discoverable by generic clients.

This CTP allows addition of spatial type properties to models via both Reflection and Custom Service Providers (EF-based services don’t yet support spatial properties), and read/write support (in ATOM or JSON formats) for all spatial types supported by SQL Server 2008 R2. The release also enables querying for all entities ordered/filtered by distance to a location, with all code running server-side; i.e. find all coffee shops near me.

Though this release contains the lower layers of Spatial support, which enables custom OData providers to use them, it doesn’t yet enable Spatial properties over EF-based Services out-of-box; a refresh of WCF Data Services succeeding the release of the next Entity/.NET Framework will enable this natively.

Vocabularies:

Those from the Linked Data and RDF worlds will feel at home with Vocabularies, but for those unfamiliar with the idea, a Vocabulary is a collection of terms sharing a namespace, and a term is a metadata extension with an optional value expression that’s applicable to arbitrary Entity Data Models (EDMs). Terms allow data producers to specify how data consumers can richly interpret and handle data. A simple vocabulary might indicate a property’s acceptable value range, whereas a complex vocabulary might specify how to convert an OData person entity into a vCard entity.

This CTP allows data service authors to configure the service for annotation through annotation files and serve a $metadata endpoint enriched with terms.

ODataLib:

The ODataLib .NET client and server libraries allow flexible low-level serialization/deserialization according to the OData Protocol Specifications.

With the exception of $batch, ODataLib now supports deserialization of all OData constructs in addition to the last CTP’s serialization support. Furthermore, ODataLib now ships with EdmLib, a new in-memory metadata system that makes it easy to build an EDM Model of a service for OData serialization/deserialization.

Frequently Asked Questions

Q1: What are the prerequisites?

A1: See the download center page for a list of prerequisites, supported operating systems, etc.

Q2: Does this CTP install side-by-side with previously released CTPs (March & June) that are currently on my development machine?

A2: No, Installation of this CTP will result in setup automatically uninstalling previously installed CTPs, if any are, installed on the machine.

Q3: Does this CTP install side-by-side with the .NET 4 and Silverlight 4 versions that are currently on my development machine?

A3: By in large this install is side-by-side with existing .NET4 and SL4 bits; however, that was not possible in all cases so some VS files will be modified by the CTP installer to enable the Add Service Reference gesture in Visual Studio 2010 to make use of the new features in this CTP. The files should be replaced to their original state during uninstall of this CTP.

Q4: Does this CTP include support for Windows Phone 7?

A: No, you can download the Windows Phone 7 SDK, which includes the OData client, from here. The Windows Phone 7 client does not yet support new features (Spatial, Actions etc.)

Known Issues, Limitations, and Workarounds

Incorrect reference to Data Services assembly in a project after adding WCF Data Services item template in Visual Studio Express:

After adding a WCF Data Services item template to a Data Services server project, the project will have a reference to System.Data.Services.dll from .NET Framework 4. You will need to remove that reference and replace it with a reference to Microsoft.Data.Services.dll from the bin\.NETFramework directory in the Data Services June October CTP installation directory (by default, it is at %programfiles%\Microsoft Data Services June 2011 CTP) and add references to Microsoft.Data.OData.dll and System.Spatial.dll.

Using add service reference in an website project results in .NET Framework 4 client-side code being generated instead of the expected October CTP 2011 code generation:

Add service reference for website projects is not supported for this CTP. This issue should be resolved by next public release.

Custom element annotation support in OData Library:

There is no support for custom element annotations in the OData Library for this CTP. This issue should be resolved by next public release.

A service using the Entity Framework provider, POCO classes with proxy and a model that has decimal keys will result in an InvalidProgramException:

This is a known issue and will be resolved in the next release of Entity Framework.

Spatial and non-standard coordinate systems:

Geospatial values in Atom only support the default coordinate system, JSON has full coordinate system support.

Support for Windows Phone 7:
The OData Windows Phone 7 client is included in the Windows Phone 7.1 SDK . The Windows Phone 7 client only supports features shipped as part of the .NET Framework 4 and does not support any OData V3 features included in this release.

Support for Datajs client library:
The OData Datajs library 7 client only supports features shipped as part of the .NET Framework 4 and does not support any OData V3 features included in this release.

Giving Feedback

The following forum can be used to provide feedback on this CTP:

http://social.msdn.microsoft.com/Forums/en-US/adodotnetdataservices/threads

We look forward to hearing your thoughts on the release!

Abhiram Chivukula
Program Manager
WCF Data Services

OData Compression in Windows Phone 7.5 (Mango)

dpblogs — Tue, 04 Oct 2011 21:57:08 GMT

One of the most frequently requested features for OData is payload compression. We have added two events to DataServiceContext in the OData phone client included in the Windows Phone SDK 7.1 that enables you to work with compressed payloads:

WritingRequest – occurs immediately before a request is sent
ReadingResponse – occurs immediately after a response is received

Now, let’s take a look at these in action. Here is a method that adds support for gzip compression for OData feeds in a Windows Phone app:

using SharpCompress.Compressor;
using SharpCompress.Compressor.Deflate;

private void EnableGZipResponses(DataServiceContext ctx)
{
     ctx.WritingRequest += new EventHandler<ReadingWritingHttpMessageEventArgs>(
          (_, args) =>
          {
                  args.Headers["Accept-Encoding"] = "gzip";
          }
     };

      ctx.ReadingResponse += new EventHandler<ReadingWritingHttpMessageEventArgs>(
      (_, args) =>
          {
               if (args.Headers.ContainsKey("Content-Encoding") &&
                      args.Headers["Content-Encoding"].Contains("gzip"))
               {
                      args.Content = new GZipStream(args.Content, CompressionMode.Decompress);
               }
         }
      );
}

This method registers two event handlers that make all of the client-side modifications to the message necessary to accept gzip compressed messages; just pass in your DataServiceContext. We’ll examine each event handler individually.

The WritingRequest event handler

Here we simply set the Accept-Encoding to gzip to inform the server that we can accept a gzip’d response. With this header set, the server will send us a gzip’d response, if it can.

The ReadingResponse event handler

The Content-Encoding header tells us how the server encoded the response body. We only modify the response body (in args.Content) when this header has been set to gzip. In this way, gzip-compressed content is decompressed with GZipStream, and everything else is just left as is.

Unfortunately, GZipStream is not currently supported on Windows Phone. We must rely on a third-party library to perform decompression and so we have used the SharpCompress Library, which worked quite well. If you download SharpCompress, you’ll get a zipped folder containing some libraries. Just add SharpCompress.WP7.dll to your project references, and you’ll be ready to use GZipStream on Windows Phone. If you’ve never added a reference before, check out this walkthrough. You can probably skip straight to the section called “To add a reference in Visual C#”. Browse to where you saved the SharpCompress.WP7.dll, and then add it to your project.

Note that if we also wanted to send a compressed request (POST) to the data service, we could simply set the Content-Encoding header to gzip in the WritingRequest handler and compress the payload stream returned by the Content property.

Server-Side Configuration

The client side changes we’ve discussed so far require that our server be configured to support message compression. If you are using IIS, check out these links to get compression set up: IIS 6.0, IIS 7.0, or a more extensive guide for both. You should be compressing OData payloads as soon as your server is ready.

Evan Czaplicki & Shayne Burgess
OData Team

Updated Item Templates for Microsoft Visual Studio 11 Express for Windows Developer Preview

dpblogs — Thu, 15 Sep 2011 18:52:00 GMT

Microsoft recently released the developer preview of the next version Windows as well as a developer preview of Visual Studio 11 for building apps on the new version of Windows. Some of you may have noticed that the “New Item” template for creating a WCF Data Services isn't working correctly (this is pre-release “preview” software after all). We have created a fix for these templates that you can use to unblock creating a WCF Data Service. The details of apply the fix are below – keep in mind this version of Visual Studio is a preview release only and the fix should only be used with that version of Visual Studio and should not be applied to any other beta/RTM version of Visual Studio.

Installation Instructions for Updates Templates:

1. Download and unzip the templates attached to this post.

2. Install the new templates. There are 4 templates to install, and installing them simply requires that you copy the attached templates over the ones in the Visual Studio directory. The names of the templates and the location to copy them are in the table below (each location is relative to the base Visual Studio install directory).

Template Location

AdoNetDataServiceCSharpWap.zip <Program Files>\Microsoft Visual Studio 11.0\Common7\IDE\ItemTemplates\CSharp\Web\1033

AdoNetDataServiceVBWap.zip <Program Files>\Microsoft Visual Studio 11.0\Common7\IDE\ItemTemplates\VisualBasic\Web\1033

AdoNetDataServiceCSharpWebsite.zip <Program Files>\Microsoft Visual Studio 11.0\Common7\IDE\ItemTemplates\Web\CSharp\1033

AdoNetDataServiceVBWebsite.zip <Program Files>\Microsoft Visual Studio 11.0\Common7\IDE\ItemTemplates\Web\VisualBasic\1033

3. Update Visual Studio.
     a. Close any active instances of Visual Studio 2011.
     b. Open an elevated Visual Studio 2011 Developer Command Prompt. You can find a tile for this from the start screen, right-click the tile, select the Advanced button and select Run as administrator.
     c. In the developer command prompt enter the command “devenv /installvstemplates”
     d. Wait for the command to complete and then start Visual Studio and the Item Templates should be working.

If you have any comments or questions on using WCF Data Services in the developer preview of Visual Studio please don’t hesitate to send them to us.

Shayne Burgess
Program Manager OData

Update to the OData Library Available on CodePlex and NuGet

dpblogs — Fri, 02 Sep 2011 18:23:22 GMT

We have just released a new drop of ODataLib and EdmLib on CodePlex as a shared source project. ODataLib is a library used for advanced OData serialization and deserialization scenarios, and EdmLib is a library used to manipulate entity data models. We invite you to download the code and test it out – this is very much an alpha release so any and all feedback is welcome.

You can download the source for these libraries (and a number of others that we have published) at odata.codeplex.com. The libraries are also available as a NuGet package at http://nuget.org/List/Packages/ODataLibrary.

Shayne Burgess
Program Manager – OData

Announcing WCF Data Services June 2011 CTP for .NET4 & SL4

dpblogs — Thu, 30 Jun 2011 20:49:00 GMT

Today we are releasing June CTP of the next version of the WCF Data Services libraries targeting.NET 4 and Silverlight 4. Based on broad community feedback, in addition to features shipped as part of Oct 2010 CTP1, I’m happy to announce that this release includes two of the top three requested features by WCF Data Services developers; support for properties on derived types & support for Any/All LINQ operators.

Below is a brief summary of the features available in this CTP. Subsequent blog posts will discuss each feature in more detail and provide examples of how to use each.

Properties on derived types: The WCF Data Services framework is designed to make it possible to expose a model that has inheritance hierarchy for the entities in the model however a current limitation is that only operations on properties that exist on the base type, associated with the set, are supported. This feature has been among our customers top asks since the lack of support makes exposing models with rich, well-defined inheritance hierarchies impossible to do. To enable such scenarios WCF Data Services now supports both exposing and consuming models which have properties (primitive, complex & navigation) defined on subtypes of the base type associated with the set.

Any/All: One of our customers top asks has been increasing the expressiveness of WCF Data Services queries to be able to express questions/queries like ‘are there any customers which have no orders’ or ‘are there any customers who only spend more than $100 at our shop’. In this release we added support for ‘any’ and ‘all’ canonical functions that can be used to ask these sorts of questions and can be invoked via the WCF Data Services client LINQ support.

OData Library: As part of this release we are releasing a low level OData serializer/deserializer library that can be used in client or server stacks. The currently released library include support for serializing ATOM & JSON formats as well as deserializing JSON format.

Frequently Asked Questions

Q1: What are the prerequisites?

A1: See the download center page for a list of prerequisites, supported operating systems, etc.

Q2: Does this CTP install side-by-side with March CTP that is currently on my development machine?

A2: No, side-by-side installation for these CTPs is not recommended. If the Data Services June 2011 CTP and the Data Services March 2011 CTP are installed on the same machine, Add Service Reference in Visual Studio will use the Data Services June 2011 CTP to generate the service reference in projects using either the March 2011 or June 2011 versions of the Data Services assembly. Please uninstall the Data Services March 2011 CTP before installing the Data Services June 2011 CTP. If you already have both CTPs installed, please uninstall both and then reinstall the Data Services June 2011 CTP.

Q3: Does this CTP install side-by-side with the .NET 4 and Silverlight 4 versions that are currently on my development machine?

Q4: Does this CTP include support for Windows Phone 7?

A: No, you can download the Windows Phone 7 SDK, which includes the OData client, from here. The Windows Phone 7 client does not yet support new features like properties on derived types.

Giving Feedback

The following forum is dedicated to providing feedback on "pre-release" versions of data services such as this CTP: http://social.msdn.microsoft.com/Forums/en-US/dataservices/threads. Please direct all your questions about the release to this forum.

Note: The forum intended for questions on currently shipping versions of ADO.NET Data Services is still available at: (http://social.msdn.microsoft.com/Forums/en-US/adodotnetdataservices/threads ).

We look forward to hearing your thoughts on the release!

Ahmed Moustafa
Program Manager
WCF Data Services

datajs V1 Now Available

dpblogs — Thu, 30 Jun 2011 00:20:00 GMT

Over the last few months, we have been hard at work on the datajs library, releasing four preview versions and working with web developers to fine-tune the library. Today, we’re proud to announce that the first version of datajs is now available for download.

What does it do?
datajs is a JavaScript library for web applications that supports the latest version of the OData protocol and HTML5 features such as local storage. It provides a simple, extensible API that can help you write better web applications, faster. Our goal is to simplify working with data on the web, and to leverage improvements in modern browsers.

Where do I get it?
You can download the development and minified version at http://datajs.codeplex.com/. The source code for the release is also available, distributed under the MIT license.

You can also use NuGet to download the datajs package.

We hope this helps build a better web, and we look forward to hearing more from your experience.

- The datajs team

Announcing datajs version 0.0.4

dpblogs — Mon, 20 Jun 2011 23:47:35 GMT

We are excited to announce that datajs version 0.0.4 is now available at http://datajs.codeplex.com/.

The latest release adds support for Reactive Extensions for Javascript (RxJs), forward and backwards cache filtering, extended metadata, simplified OData call configuration, and provides various performance and quality improvements.

To get started, simply browse over to the Documentation page, where you will find download instructions, overview and detailed topics, and some samples to get started quickly.

This is the last planned release before version 1.0.0. The features and APIs are not expected to change, so this is a great time to try the library out and provide feedback through the project Discussions!

Marcelo Lopez Ruiz
Software Design Engineer
Microsoft

Template	Location
AdoNetDataServiceCSharpWap.zip	<Program Files>\Microsoft Visual Studio 11.0\Common7\IDE\ItemTemplates\CSharp\Web\1033
AdoNetDataServiceVBWap.zip	<Program Files>\Microsoft Visual Studio 11.0\Common7\IDE\ItemTemplates\VisualBasic\Web\1033
AdoNetDataServiceCSharpWebsite.zip	<Program Files>\Microsoft Visual Studio 11.0\Common7\IDE\ItemTemplates\Web\CSharp\1033
AdoNetDataServiceVBWebsite.zip	<Program Files>\Microsoft Visual Studio 11.0\Common7\IDE\ItemTemplates\Web\VisualBasic\1033

WCF Data Services Team Blog

WCF Data Services 5.0.1 Released

NuGet Links

Release Notes

What does the MSI do?

Where should the MSI be installed?

Feedback Please

WCF Data Services EULAs updated

NuGet and Bin Deploy

Managing dependencies with NuGet

Bin Deploying Applications

A Glimpse Into the Future

WCF Data Services, now with more releases!

Adopting semantic versioning

Distribute new releases via NuGet

Changing to a “bin deploy” model

Feedback please!

Metro OData prerelease bits and app

WCF Data Services 5.1.0-rc Prerelease

What is in the prerelease

Getting the prerelease

Call to action

JSON Light Sample Payloads

How to use WCF DS 5.0 in a Web Site project

Actions in WCF Data Services – Part 3: A sample provider for the Entity Framework

Implementation Strategy

Finding Actions

Parameter Marshaling

Delaying invocation

Actions that are bound *sometimes*

Getting the Sample Code

Summary

What happened to application/json in WCF DS 5.0?

The roadmap for serialization formats

When will I get a 415 response and what can I do about it?

Why did WCF DS 5.0 ship before JSON light?

Actions in WCF Data Services – Part 2: How IDataServiceActionProvider works

IDataServiceActionProvider

Exposing ServiceActions

Advertizing ServiceActions

Invoking ServiceActions

Summary

Actions in WCF Data Services – Part 1: Service Author Code

Scenario

Target Experience

Actions whose availability depends upon Entity State

Summary

WCF Data Services 5.0 RTM Release

Announcing OData T4 for C#, Preview 1

Using Geospatial Data

Adding Geospatial Data to the Model

Writing the client

Reading and writing geospatial values

Enabling geo.distance queries

Making a distance query

Actions in WCF Data Services

Using WCF Data Services to Invoke an Action:

Coming Soon…

Setting up a WCF Data Service with Actions:

Conclusion:

Introducing the OData Library

Vocabularies in WCF Data Services

Applying Annotations to Data Service

Authoring an annotations file

Configuring the data service

Client Side

Example Annotations

EntityContainer

EntitySet

EntityType

Property

NavigationProperty

Summary

Announcing WCF Data Services Oct 2011 CTP for .NET 4 and Silverlight 4

OData Compression in Windows Phone 7.5 (Mango)

Updated Item Templates for Microsoft Visual Studio 11 Express for Windows Developer Preview

Update to the OData Library Available on CodePlex and NuGet

Announcing WCF Data Services June 2011 CTP for .NET4 & SL4

datajs V1 Now Available

Announcing datajs version 0.0.4

Actions that are bound sometimes