OData .NET Libraries

1. Introduction

The OData .NET Libraries (or OData .NET, for short) project includes the implementation of core functionalities of OData protocol on the .NET platform which includes URI parsing, request and response reading and writing, Entity Data Model (EDM) building, and also a .Net OData client which can be used to consume OData service. It is a fully open sourced project maintained by Microsoft OData team. The libraries are used by WebApi and RESTier which are recommended to be adopted to build new OData Services.

OData stands for the Open Data Protocol. It was initiated by Microsoft and is now an ISO and OASIS standard. OData enables the creation and consumption of REST APIs, which allow resources, identified using URLs and defined in a data model, to be published and edited by Web clients using simple HTTP requests.

For more information about OData, please refer to the following resources:

• OData.org
• OASIS Open Data Protocol (OData) Technical Committee

For how to adopt this and related libraries to build or consume OData service, please refer to the following resources:

• Build an OData v4 Service with RESTier Library
• Build an OData v4 Service with OData WebApi Library
• OData .Net Client

2. Project structure

The project currently has six branches: ODataV4-6.x, ODataV4-7.x, master, gh-pages, ODATAV3, and WCFDSV4.

ODataV4-6.x branch

The ODataV4-6.x branch includes the .NET libraries for OData V4 only that are now most actively iterated and maintained by the OData team, it has newest OData lib 6.x release code base. It has the following libraries:

• ODataLib (namespace Microsoft.OData.Core):
  The ODataLib contains classes to serialize, deserialize and validate OData JSON payloads.
• EdmLib (namespace Microsoft.OData.Edm):
  The EdmLib contains classes to represent, construct, parse, serialize and validate entity data models.
• Microsoft.Spatial (namespace Microsoft.Spatial):
  The spatial library contains classes and methods that facilitate geography and geometry spatial operations.
• OData Client for .NET (namespace Microsoft.OData.Client):
  The client library is built on top of ODataLib and EdmLib that has LINQ-enabled client APIs for issuing OData queries and consuming OData JSON payloads.

For these libraries, we accept bug reports and pull requests. The corresponding fixes and implementations will be included into every new release.

ODataV4-7.x branch

The ODataV4-7.x branch includes the .NET libraries for OData V4 only that are in development now. It is evolved from ODataV4-6.x with kinds of improvements, new features and so on. It is in-compatible with ODataV4-6.x release and will become the master branch after it is released. It has same libraries as ODataV4-6.x branch.

For these libraries, we accept feature requirements, but we do not accept bug reports and pull requests before first release is ready.

Master branch

The master branch has most recently stable 6.x release code base, and is recommended to use before OData lib 7.x is released.

gh-pages branch

The gh-pages branch contains documentation source for OData v4 Lib - tutorials, guides, etc. The documention source is in Markdown format. It is hosted at ODataLib Pages.

ODATAV3 branch (maintenance mode)

The ODATAV3 branch includes the .NET libraries for OData V1-3 only. It has the similar libraries as the master branch except for some differences in namespaces and two additional libraries:

• ODataLib for OData v1-3 (namespace Microsoft.Data.Core):
  It contains classes to serialize, deserialize and validate OData payloads. Enables construction of OData producers and consumers.
• EdmLib for OData v1-3 (namespace Microsoft.Data.Edm):
  It contains classes to represent, construct, parse, serialize and validate entity data models.
• System.Spatial for OData v1-3 (namespace System.Spatial):
  It contains classes and methods that facilitate geography and geometry spatial operations.
• WCF Data Services Client for OData v1-3 (namespace Microsoft.Data.Services.Client):
  It contains LINQ-enabled client API for issuing OData queries and consuming OData payloads.
• WCF Data Services Server for OData v1-3 (namespace Microsoft.Data.Services):
  Fully-featured server API for responding to OData queries and consuming/producing OData payloads.
• WCF Data Services EntityFramework Provider (namespace Microsoft.OData.EntityFrameworkProvider):
  Server API for responding to OData queries and consuming/producing OData payloads based on entity framework version 6.0 or higher.

These libraries are in maintenance mode. Only security bugs will be accepted. The release will be irregular depends on the bugs fixed.

WCFDSV4 branch (maintenance mode)

The WCFDSV4 branch has the source code of the OData V4 parity of the WCF Data Services Server for OData v1-3. It is only for cloning and doesn't accept contributions. There is no binary release of it either. WCF DS is not recommended to be adopted now, instead WebApi or RESTier is recommended to be adopted to build new OData Services.

3. Building, Testing, Debugging and Release

In the case of VS2013, SQL Express 2008 or above must be installed. In the case of VS2015, LocalDB v12.0 or above will be used which is part of VS2015 and no additional installation is needed. The Database will be automatically initialized by the test code if it doesn't exist.

Note: The project T4CrossPlatformTests.WindowsStore.csproj will not be loaded unless you have installed the Windows 8.1 and Windows Phone 8.0 / 8.1 tools.

3.1 Building and Testing in Visual Studio

Simply open the solution files under 'sln' folder and build them in Visual Studio 2013 or 2015.

Here is the usage of each solution file:

• Microsoft.OData.Lite.sln - Product source and minimal functional tests. Recommended for doing general bugfix and feature development. It is built with .Net Framework Portable version 4.0.
• Microsoft.OData.Full.sln - Product source and full functional tests (excluding test cases in Lite and E2E solution). Used to fully test your code.
• Microsoft.OData.E2E.sln - Product source and end-to-end tests.
• Microsoft.OData.Net35.sln - Solution with product source built with .Net Framework version 3.5.
• Microsoft.OData.Net45.sln - Solution with product source built with .Net Framework version 4.5.
• Microsoft.OData.Portable45.sln - Solution with product source built with .Net Framework Portable version 4.5.
• Microsoft.OData.Performance.sln - Product source and performance tests built with .Net Framework version 4.6.
• Microsoft.OData.CodeGen.sln - Source and tests for OData T4 client code generator.

Each solution contains some test projects. Please open it, build it and run all the tests in the test explorer. For running tests within Microsoft.OData.Full.sln and Microsoft.OData.E2E.sln, you need to open Visual Studio IDE as Administrator so that the test services can be started properly.

3.2 One-click build and test script in command line

Open Command Line Window with "Run as administrator", cd to the root folder and run following command:

build.cmd

The build and test will take about 15 minutes. Here are some other usages:

• build.cmd Nightly. Build and run all nightly test suites.
• build.cmd Rolling. Build and run all rolling test suites (with less legacy tests thus faster).
• build.cmd SkipStrongName. Configure strong name skip of OData libraries on your machine and build (no test run).
• build.cmd DisableSkipStrongName. Disable strong name skip of OData libraries on your machine and build (no test run).

Notes: If there is build error with message "build.ps1 cannot be loaded", right click "build.ps1" -> Properties -> "Unlock".

3.3 Debug

Please refer to the How to debug.

3.4 Nightly Builds

We keep uploading the daily nightly signed NuGet packages for ODataLib/EdmLib/ClientLib/SpatialLib to our MyGet feed.

You can query the latest nightly NuGet packages using this MAGIC OData query

3.5 Official Release

The release of the component binaries is carried out regularly through Nuget.

4. Documentation

Please visit the ODataLib pages. It has detailed descriptions on each feature provided by OData lib, how to use the OData .Net Client to consume OData service etc.

5. Community

5.1 Contribution

There are many ways for you to contribute to OData .NET. The easiest way is to participate in discussion of features and issues. You can also contribute by sending pull requests of features or bug fixes to us. Contribution to the documentations is also highly welcomed. Please refer to the CONTRIBUTING.md for more details.

5.2 Support

• Issues
  Report issues on Github issues.
• Questions
  Ask questions on Stack Overflow.
• Feedback
  Please send mails to odatafeedback@microsoft.com.
• Team blog
  Please visit http://blogs.msdn.com/b/odatateam/ and http://www.odata.org/blog/.

Thank You!

We’re using NDepend to analyze and increase code quality.