Feedback: Setup, pain points

[atrauzzi]

I wanted to just share a little bit of feedback about my experience getting my first odata resources working in .net core 3.1.

I don't suspect any of what I encountered is related to .net 3.1, but instead is mostly around the nature of how this library applies the notion of "convention".

Put simply, I think this project could benefit from a few key improvements:

• Publish cleaner and more comprehensive official documentation. A little more on this in a moment. But I think this could use a lot of love.
• Wrangle together all existing blog posts the team has authored and ideally put a note on them about which versions of the library and ASP.net each guide applies to.
• Put an ASP.net and library version note/selector somewhere in the official documentation so that people can dial in the correct set of instructions.

---

Convention

When I see "convention", I'm accustomed to any automatic behaviour being end-to-end. That means that unless I need to do a little customizing, things will just work.

Such wasn't the case as I set up my project to use odata. I started out having to spend a lot of time really grappling with just what exactly ODataConventionModelBuilder(app.ApplicationServices) is even doing.

Once I had things such that my $metadata/ route was working, it was onto the next challenge, which was over why my controller just wouldn't work. What confused me the most here was that I couldn't read anywhere about what was going on. My initial assumption was that odata would automatically perform all my CRUD for me without even having to write controllers. Going over tutorial after tutorial though got me thinking that I was still responsible for that, yet when I wrote this:

    [Route("/odata/[controller]")]
    [ApiController]
    public class BlogPostController
    {
        // ...

...I got nothing!

It was only until I removed any kind of MVC typing and turned my controller into a POCO controller that I started to get odata-style responses.

    public class BlogPostController
    {
        // ...

---

So, hmm.. How to best tie this together? I guess the biggest issue right now is that this library surprised me a lot. The resultant functionality is desirable, if not a bit odd in its wiring. I'd rather have my EDM be based directly off of my DbContext. It might also be nice to not have to write any controllers at all for the most basic of scenarios.

Anyway, I want this to also be a discussion so that if you want to pick my brain, I'll try to help you understand how I didn't understand this. I'd say I'm about 85% of the way there and can go back to my implementation work. But I think some love for the newcomer experience would really go a long way for this library! 💖

[atrauzzi]

Oh, by the way, see this: https://stackoverflow.com/questions/55728791/pagination-with-aspnetcore-odata-missing-odata-properties-in-response

I had to stumble upon this self-answered Stack Overflow question - entirely by chance - before I could solve my controller issue!

[Sreejithpin]

@atrauzzi . Thanks for the input. We are definitely trying to improve our documentation process, especially for new users and we are in the process of that. Meanwhile in your search did you stumble on https://docs.microsoft.com/odata ?, if so will be great to know if you found it will be helpful? Also WebApi is designed to give full control to the developers. However we have a wrapper on top of webapi called restier https://github.com/OData/RESTier. Feel free to take a look at it

[atrauzzi]

I did see that documentation and unfortunately those were some of the docs I followed that didn't give me a working setup.

Also, I'm not necessarily trying to use WebApi, though it's not clear to me whether odata requires WebApi or builds on it (you've somewhat clarified that here a little) and what the difference is between WebApi and....?? I'm not sure what else? I just have a POCO controller...

(My understanding was that in .net Core, the notion of API project types was going away and everything was just "routing".)