Experimenting with OData in ASP.NET Core 3.1

Avatar

Hassan

A lot of developers have asked me recently about OData compatibility with ASP.NET Core 3.0 and again with .NET Core 3.1 after it’s very recent release.

This demand became more and more critical with the recent announcement from the .NET team around .NET Core 2.2 reaching the end of its life on Dec 23rd of this year.

And because of all of that, the OData team at Microsoft have been working diligently in the last few months to ensure a stable release of OData that supports .NET Core 3.1 makes it out to the public as soon as possible.

And while the final release might take a bit longer to be production-ready, the OData team has recently released a beta version for developers to experiment with it, learn about it’s capabilities and possibly build some demo APIs and leverage it in some POCs.

In this article, I’m going to show you how you can build a modern ASP.NET Core 3.1 API with OData by simply following very few simple steps.

 

Prerequisites

In order for you to be able to create this demo on your local machine, you want to make sure that you have Visual Studio 2019 version 16.4 or later so you can leverage the capabilities of .NET Core 3.1, if you install that particular version of VS 2019 you will not need to install .NET Core 3.1 separately as it comes with the bundle.

You can check the current version of your Visual Studio 2019 by going to top menu, then Help then About Visual Studio as shows in the following screenshots:

If your current version of Visual Studio 2019 is lower than 16.4, you can upgrade your Visual Studio instance by clicking on the bell icon at the lower right corner of your Visual Studio instance then selecting to upgrade your Visual Studio as shows in the following screenshots:

Once you click the “More Details” link, it usually takes about 10 seconds and then you should be prompt with a dialog to upgrade your Visual Studio instance as follows:

Please make sure you save all your work before you click the “Update” button as the process will require Visual Studio to close automatically, you will not be prompted to save your work before Visual Studio closes, you also want to make sure you have Admin permissions to be able to continue with that process.

Once the upgrade is done, now you are ready to build ASP.NET Core applications with .NET Core 3.1, let’s talk about setting your project up.

 

Setting Things Up

For starters, let’s create a new ASP.NET Core Web Application by either starting a new instance of Visual Studio or simply going to File -> New -> Project, you should be then prompted with the following dialog:

After selecting ASP.NET Core Web Application (with C#) click the Next button you will be prompted to create a new name for your project and then selecting the version and template of which your project should be based on as follows:

 

 

Please make sure you select ASP.NET Core 3.1 from the drop down menu at the top right side, and API as a template for your project then click “Create“.

 

Installing OData

Now that you have created a new project, let’s go ahead and install the beta release of OData for ASP.NET Core 3.1

There are two ways you can install the beta library depends on your preference, if you are a command line kind of developer, you can simply open the package manager console by clicking on the Tools top menu option, then Nuget Package Manager then Package Manager Console as follows:

you will be prompted with a console window so you can type the following command:

If you don’t like using command lines, you can simply install the very same package by going to the exact same menu options we selected above, except you are going to choose Manage Nuget Packages for Solution instead of Package Manager Console the following dialog will appear so you can install the library as follows:

There are few things that I have highlighted in that screenshot that you need to pay attention to:

  1. You must check the “Include prerelease” so you can see the beta release of the nuget package.
  2. Search for Microsoft.AspNetCore.OData and select the first option.
  3. Select the project in which you want to install your library, in our case here since we have one project, it’s safe to just check the entire project.
  4. Make sure you select Latest prerelease 7.3.0-beta in the drop down menu on the right side before you click the Install button.

 

Models & Controllers

Now that we have OData installed, let’s create a Student model and create a controller to return a list of students as follows:

Now let’s create a simple API controller that returns a list of students:

Please notice that this controller is only created this way for a demo purpose, ideally your controller should return an IQueryable to achieve better performance and execute queries on your database server if you are retrieving your data from a database.

 

Final Step

Our final step here is to modify the startup.cs file to support OData, our code here will be very similar to our code from previous articles, let’s start with the ConfigureServices method in our startup.cs file as follows:

You will notice a couple of changes in the above code, Adding OData which is just as similar as any other OData powered application.

The second change is disabling endpoint routing, let’s talk about that for a bit.

For starters, this is not an ideal situation, the final release of OData shall allow endpoint routing while supporting OData queries.

But for those who want to understand what endpoint routing setting is, especially for .NET Core 3.0 and above, here’s a quote from a previous post for Daniel Roth:

In ASP.NET Core 2.2 we introduced a new routing implementation called Endpoint Routing which replaces IRouter-based routing for ASP.NET Core MVC. In the upcoming 3.0 release Endpoint Routing will become central to the ASP.NET Core middleware programming model. Endpoint Routing is designed to support greater interoperability between frameworks that need routing (MVC, gRPC, SignalR, and more …) and middleware that want to understand the decisions made by routing (localization, authorization, CORS, and more …).

While it’s still possible to use the old UseMvc() or UseRouter() middleware in a 3.0 application, we recommend that every application migrate to Endpoint Routing if possible. We are taking steps to address compatibility bugs and fill in previously unsupported scenarios. We welcome your feedback about what features are missing or anything else that’s not great about routing in this preview release.

And while endpoint routing is one of the most important upgrades to ASP.NET Core 3.0, with this beta release you could still leverage the power of OData without leveraging endpoint routing temporarily.

With that being said, let’s move on to the next step which is implementing a GetEdmModel method as we have done previously and change the routing implementing in the Configure method as follows:

 

I have intentionally left the app.UseEndPoints to show you what code you need to remove (again, temporarily for this beta release) and what code you need to add to leverage the power of OData.
And that should be the final step in this tutorial, now you can run you application and call your endpoint as follows:

and the results should be as follows:

 

 

Final Notes

  1. Huge thanks to Sam Xu, Saurabh Madan and the the rest of the OData team on the great efforts they have made to produce this beta release, and as you are reading this article, the team continues to push improvements and features before announcing the final release of OData 7.3.0 for ASP.NET Core 3.1 which should have a long term support of 3 years.
  2. This beta release should not be used in any way shape or form for production environments, it’s mainly for POCs and demos.
  3. OData team should announce the final release of OData for .NET Core 3.1 sometime in the second quarter of 2020.
  4. You can follow up on the most recent updates for OData on this public github repository and this thread as well.
  5. This is a repository for the demo in this article.

If you have any questions, comments, concerns or if you are running into any issues running this demo feel free to reach out on this blog post, we are more than happy to listen to your feedback and communicate your concerns.

 

Update

  1. Just a couple of days ago, OData team has released the final version of OData 7.3.0 to support .NET Core 3.1 you can find the package in here.
  2. OData team is working very closely with the .NET team to address the endpoint routing issue, we will announce the changes as soon as they become ready.
  3. You can now use OData in your production environment as it passed it’s beta stage and is now ready for production-ready applications.

 

Avatar
Hassan Habib

Sr. Software Engineer, Microsoft

Follow Hassan   

10 comments

  • Avatar
    Shimmy Weitzhandler

    Thank you Hassan!
    The effort Microsoft put recently in OData is really a great step forward and really appreciated.

    I wish this effort would also spread to client side OData management.
    Right now, the only .NET client-side OData option is Simple.OData.Client which lacks of low maintenance and lack of support for modern techniques such as IoC/DI, IHttpClientFactory, and others.

    Thanks!

    • Avatar
      Hassan Habib

      Thanks, Shimmy.
      I will communicate this concern with the team, there seems to be definitely a reusable component with Microsoft Graph Clients (since it’s also using OData) but I will definitely follow up on that.

  • Mahmut Jomaa
    Mahmut Jomaa

    Thank you for all the efforts.

    There is actually something I never found out. Is it possible in OData to ignore extra properties on a POST request? Currently it will send a bad request. I know that you can use dynamic properties, but I want to ignore (not use or save) all extra properties of a request. Maybe it is not the right place to ask 🙂

  • Avatar
    Onur Omer OZTURK

    It is good to get selective properties with OData but it makes no great difference/performance gain without passing this selection to data layer. The only gain will be in data size and only between client and the server. Ability to pass this selection to the data layer is provided with EF (I mean IQueryable) but EF is like using anti-biotics, takes more than it brings in the long run.

    Thanks for the OData introduction anyway, I will be using it with a custom ORM, happy to see it in action for .NetCore 3.1.

  • Avatar
    Schaff, Stephen

    Ah OData! It was so wonderful. I and my company loved it so much. Too bad they got so opinionated about date time.

  • ivan zinov
    ivan zinov

    My company created an API that is running on .NET Core 2.2 and it is using the OData package. The dilemma here is that we are not yet in production because VMs for production should be created. Also, Microsoft made the announcement that 2.2 is not going to be supported anymore. In addition to that, my IT department is not willing to install 2.2 on production servers.
    We can do the upgrade of the API to 3.1, but you said your team is not ready yet to be fully compatible with 3.1.
    Please advice how I can proceed.
    Thanks in advance

  • ivan zinov
    ivan zinov

    Is endpoint routing implemented on your final update? or do I need to implement IODataRoutingConvention? Not having this creates an incompatibility with other middlewares that are available on .netcore like HealChecks that needs to be registered through the IEndPointRouterBuilder.

    app.UseEndpoints(endpoints =>
    {
    endpoints.MapHealthChecks(“/healthz”).RequireHost(“*:8080”);
    });

    And having both UseEndpoints and UseMvc is basically a nightmare. I posted the question here as well:
    https://stackoverflow.com/questions/59741591/how-to-register-odata-extension-methods-in-netcore-3-1-outside-of-usemvc-middle/59746510#59746510

Leave a comment