It’s been a few month since I wrote a blog post comparing features of Simple.OData.Client and WCF Data Services client. Judging from NuGet download statistics, questions and GitHub issues I can see that the library has been used in various scenarios and on various platforms, including Xamarin iOS and Android. This is indeed very encouraging but at the same time raises the bar for the platform tests, conformance to OData protocol and API expressiveness. Some of the forthcoming changes to Simple.OData.Client API are breaking, and with respect to semantic versioning I have to release them with a different major version number. So I’d like to give in this blog post a quick overview of each version.
Initial release of Simple.OData.Client came as a library extracted from Simple.Data OData adapter to improve its granularity and portability. The library implemented HTTP communication based on HttpWebRequest and favored synchronous calls. This didn’t work well with platforms like Silverlight and Windows Phone that required asynchronous communication all the way.
This is the most recent (in May 2014) version of Simple.OData.Client with two major changes comparing to version 1:
- The library is now using Microsoft HttpClient PCL (Microsoft.Net.Http);
- The library API has been redesigned to be asynchronous but it still exposes obsolete synchronous methods in addition to asynchronous ones;
I have to admit now that keeping synchronous methods was a mistake – I did it for backward compatibility, but it misleads developers in belief that they can use synchronous API on platforms where it can easily cause deadlocks. In fact, I wouldn’t recommend to use sync API on any platform except .NET 4.x. For the sake of existing .NET 4 clients I will keep adding minor changes to version 2 even after release of newer major versions of the library.
This is already available as release candidate and contains the following significant changes:
- Change of PCL profile from 147 to 78, as described in this blog post;
- Added method overloads with CancellationToken;
PCL profile numbers may not say much, but this is in fact the major change although not reflected in API method signatures. PCL profile 147 corresponds to so called legacy surface area intended to fit most platforms. This requires use of internal wrappers and adapters and as it turned out results in problems – ironically on the legacy platforms. For example, I never managed to succeed using HttpClient PCL from another PCL called from a Silverlight application. So I changed the PCL targeting strategy and now Simple.OData.Client targets .NET 4.0 and Silverlight platforms via native platform-specific libraries with the its PCL targeting other platforms.
Currently Simple.OData.Client uses its own parser and formatter that only support XML payload in the format of RSS feeds. That was the original OData message format, but the protocol has been extended with support for JSON, and being more compact, more readable and more network bandwidth friendly, JSON is becoming a preferred OData payload representation and is selected as a default format by OData feeds built using HTTP Web API. Now that Microsoft has converted its ODataLib (Microsoft.Data.OData) to support all target Simple.OData.Client platforms, I plan to retire internal Simple.OData.Client OData parser and formatter and instead use the one from ODataLib so I can ensure the same message serialization and keep the library up-to-date with most recent OData protocol updates reflected in ODataLib.
Summary: which version to use?
- If you’re using Simple.Data OData adapter, you don’t need to care: just use the most recent version available at NuGet or keep using the one you’re using now if it works fine. Simple.Data OData adapter will be maintained and its dependencies will be updated so you don’t have to take any actions in regards to Simple.OData.Client.
- If you’re using Simple.OData.Client synchronous API with .NET 4.0 applications and everything works fine, you can continue using it. For mobile applications use only asynchronous API calls.
- The release of the version 3 is around the corner, pre-release is already available. Works much better with Silverlight clients, support for cancellation tokens, modern PCL profile widely used on Xamarin platforms.
- Version 4 will add support for JSON payload and will be based on ODataLib. But I haven’t even started working on it.