Minimal APIs at a glance in .NET 6

https://www.hanselman.com/blog/minimal-apis-at-a-glance-in-net-6

by ingve • 5 years ago

152 111 5 years ago

ddek• 5 years ago

So I guess we've had 'JavaScript but like C#', in the form of TypeScript; so I suppose now we get 'C# like JavaScript'? I must admit, I find this amusing.

I suppose this raises two questions: "Why use C# like this in place of express or koa on node, which idiomatically similar?", and "Why use C# like this instead of C# like that (the way all other AspNetCore apps do it)?"

stevefan19992• 5 years ago

because you dont want to work with a broken module system?

im talking about you, ESM, for all the headaches you induced me on TypeORM and NestJS. I really miss the proper Java packages and dotnet namespaces design

flohofwoe2• 5 years ago

The same can be done in pretty much any other language, it's just a HTTP server wrapper which maps specific URL paths to callback functions which return a HTTP response.

E.g. in Go: https://gobyexample.com/http-servers, or in Python via Flask: https://flask.palletsprojects.com/en/2.0.x/quickstart/#routi...

kevingadd• 5 years ago

I think the fact that this maintains type safety, IDE integration and other useful traits of modern C# like zero-allocation primitives gives it a leg up over TypeScript/JS in some cases.

davidfowl2• 5 years ago

This

nodejs_rulez_12• 5 years ago

They neither broke the type system to make it weaker nor did they stick a browser engine where it doesn't belong.

andix15• 5 years ago

You still get C#/.NET, with it's superior performance and type safety, but just without all the OOP bloat.

LAC-Tech4• 5 years ago

Wait, you think this is not OOP?

    var app = WebApplication.Create(args);
 
    app.MapGet("/", () => "Hello World");
 
    app.Run();

You're creating an object and calling methods on it..

jeswin• 5 years ago

1. The web server component could be fronting a middle-tier written in C#. There are numerous advantages to doing this in .Net over Node.

2. Performance.

3. Native AOT is coming in 6.0. Meaning, you get a native platform specific app which can run without the framework - like golang. But with GC, so not like C/C++/Rust.

GordonS• 5 years ago

I've been using C# since it was released, and I'm a huge fan.

But I can almost guarantee that native AOT doesn't appear with dotnet 6 - they've been promising it for several years, and it's become Microsoft's Duke Nukem Forever,

ripley122• 5 years ago

NativeAOT is supported in more places in .NET 6, there has been a tremendous amount of work to ensure that libraries are trimmer and linker friendly. But I believe ASP.NET’s targeting .NET 7 for that.

stevefan19992• 5 years ago

I don't get it why people always hated (tracing) GC. Unless you are working on a hard real time systems such as DSP or audio synthesizer, having some kind of GC is always the boon.

Not only you can run code faster in some case (by suspending GC in some critical code and just do plain allocate and resume GC at a later time, and this is also how you make it more real-time compatible), it can also help curb fundamental security issues such as dangling pointers and use-after-free.

GC is also not the blame to the bloated size of your app, Nim [1], for example, is a language with GC/runtime while being lightweight. Another honorable mention would be Haxe [2] for gamedev, where it can generate much more compelling C++ code that the binary size is just slightly bigger to what you normally do with C++ while having much less lines needed to code. And it has a tracing GC.

So I do think GC-enabled language can be like C/C++/Rust. Even if there is a binary and performance difference, it won't be huge. But the way it makes your program safer by a huge margin and your programmer less mentally pain, makes having GC a huge difference.

By the way, even smart pointers/move semantics and ownership are one kind of GC (by leveraging linear/affine logic to ensure resources will not drop out of its controllable/life phase commonly called lifetime), so most of the time what I refer to GC is more specifically tracing GC where mark-and-sweep algorithms that usually need to stop-the-world is indeed a fundamental problem in GC design especially for multi-core platform which is going more and more popular nowadays.

[1] https://nim-lang.org [2]: https://haxe.org

oaiey7• 5 years ago

It is about attracting new developers to .NET. Boilerplate does not help. So it boils down what the cool kids consider simple: Express + node.js => ASP.NET Core Minimal API.

Evolve or die. When you see the releases in the last 5 years, C#/.NET tries to evolve and stay relevant.

Do we need to like that: No. Is it necessary for .NET: Yes.

flohofwoe2• 5 years ago

Translation for non-web-people: how to write a minimal web service in dotNET. I probably missed when the acronym "API" was hijacked by the web people to describe a custom web service protocol.

ptx• 5 years ago

I think the point is that the .NET API for writing a minimal web service is now more minimal, thanks to being designed around lambdas instead of heavy use of OOP. The web server API is just an example of this style of .NET API.

inshadows• 5 years ago

Also the word "public" is missing. Cute examples, but I guess you're supposed to set up firewall for auth.

oaiey7• 5 years ago

You can just add auth middleware in there. This is still full fledged ASP.NET Core. They just wire it up using a different style. There is a chapter in the referenced gist about adding middleware.

But I guess you more meant the example than the actual tech.

nodejs_rulez_12• 5 years ago

Yeah, it's like 'front-end' by default means a bunch of js and html mashed together, rather than native UI.

lghh• 5 years ago

Considering these are http wrappers around program A (the web service) that allows program B (a client) to interact with program A, I'd say API is the correct term for what this is.

andix15• 5 years ago

The old convention based model for controllers, was really difficult to understand and debug. You never knew what routes exactly were discovered by reflection. It was just too much magic, and too many conventions.

I hope this will make it easier. Reminds me of the good old Nancy times.

arethuza5• 5 years ago

What about attribute based routing - that makes things nice and explicit?

silon42• 5 years ago

Still too much magic.

andix15• 5 years ago

It is still some kind of reflection magic.

Also most frameworks moved away from attributes and towards builders. For example entity framework or Microsoft.extensions.dependendyinjection.

kumarvvr2• 5 years ago

More importantly, if the default is to depend heavily on conventions, MS should have had a big glaring button / warning / notification in the Introduction page, which summarizes all the conventions used. Would have saved many beginners a lot of time.

I am an experienced programmer and was very frustrated having to search for all the conventions used in the framework.

andix15• 5 years ago

That always drove me nuts. You need to learn all those conventions from the examples. And then you always got the strangest surprises and still needed to use attribute based routing.

SketchySeaBeast• 5 years ago

Absolutely. I've wasted hours doing things that, if I'd been shown the way Microsoft wanted me to do them, I'd solve in 10 minutes, but instead I need to spend a ton of time trying to figure out why the new variable on my model isn't binding correctly because I didn't realize they need to be properties.

numlock86• 5 years ago

So basically this is expressjs for .NET.

andix15• 5 years ago

best of both worlds

0xcoffee• 5 years ago

Is there any example of how this would work with dependency injection? Or it's expected to manually call the service provider inside the lambda?

Or if I just add my interfaces to the lambda parameters they will automatically resolved?

edit: It supports DI using `[FromServices]` attribute!

https://gist.github.com/davidfowl/ff1addd02d239d2d26f4648a06...

edit: Apparently this was in the article, but I overlooked it..

Vake93• 5 years ago

Just pass them as parameters for the lambda. Good Example: https://github.com/DamianEdwards/MinimalApiPlayground/blob/m...

zzbzq• 5 years ago

The target audience for it, though, is probably us folks who want to remove dependency injection altogether. It was going against the grain before because the whole framework was built around Controllers and the part of the pipeline that had a monopoly on constructing them. With these changes it looks like it will be fully supported to write server-side HTTP code as if it were a computer program. Like you can in any other language. Better late than never!

tonyedgecombe• 5 years ago

That's interesting, I've been avoiding .Net for web projects because of the DI. Time to take another look.

jameshart5• 5 years ago

It never takes long when throwing together toy examples with these kinds of APIs to introduce a security risk:

    var uploads = Path.Combine(uploadsPath, file.FileName);

Where file.FileName appears to be drawn from the content-disposition header of the request. MS’s own asp.net docs on file uploads say:

“Use a safe file name determined by the app. Don't use a file name provided by the user or the untrusted file name of the uploaded file.”

I’m always wary of APIs designed to look good in a DevRel evangelist’s presentation, to show how you can do something in ‘just a few lines of code’, when the reality is that actual applications will need to deal with a bunch more concerns anyway and this terse little API is not going to make one jot of difference to the essential complexity you’re trying to express.

Whether you have a node express style server where you’re able to declare all your controller mappings in-line using lambdas, or a spring style router where controllers are in separate classes and methods makes no real difference to the fact you still have to write the controller body, and in any real application it is not going to be handling everything from request body handling to file system operations in one place anyway.

At least when the controllers are all classes I can unit test them.

Zababa• 5 years ago

At least when the controllers are all classes I can unit test them.

You can usually very easily transform lambas in function, so testing shouldn't be a problem.

jhgb• 5 years ago

Lambas, the famous Elvish mathbread?

jameshart5• 5 years ago

But if I'm not writing my controllers using inline lambda syntax, but as functions in classes in a controllers directory,, what's the value of this minimal route declaration syntax over a 'heavierweight' solution that... also puts my controller declarations in methods of classes in a controllers directory?

tester344• 5 years ago

At least when the controllers are all classes I can unit test them.

Do what on "controllers"???

heresy

Jenk6• 5 years ago

At least when the controllers are all classes I can unit test them.

I was always having great difficulty testing ASP.NET MVC controllers given the use of completely closed off, cyclical dependency, sealed class, properties like HttpContext.

Helper libraries made it somewhat easier to set them up but they were always heavy tests as a direct result of the large object graph needed.

tester344• 5 years ago

But why? generally you don't test controllers directly.

You test "service"/"handler" classes that handle those requests.

If you want to test controllers, then you write E2E tests that send HTTP requests

Here's some example of how it might look like

https://docs.microsoft.com/en-us/aspnet/core/test/integratio...

davidfowl2• 5 years ago

In ASP.NET Core the HttpContext is very mockable.

magicalhippo• 5 years ago

At least when the controllers are all classes I can unit test them.

So I've literally just jumped into this world, having never touched asp.net or similar before.

I looked into how to test the controller side of things, and came across this[1] post arguing that unit testing controllers weren't as useful as integration testing them.

Integration testing would definitely be useful, and something I will do, but I assume also a lot more time-consuming so perhaps not something we could do on a per-commit basis.

Would highly appreciate views on this topic.

[1] https://andrewlock.net/should-you-unit-test-controllers-in-a...

achtung82• 5 years ago

Integration testing as im used to it takes less time to write than unittests since you need to spend less time mocking things (mainly just mock external requests). Of course the initial setup requires more time but there are many readymade examples you can copy from. For example the official documentation.

https://docs.microsoft.com/en-us/aspnet/core/test/integratio...

stonemetal12• 5 years ago

Unit tests are valuable if you are doing some sort of "computation". If all code in question is doing is plugging x into y, then unit tests are useless and integration tests are where the payoff is.

If you have code that does both plug and compute you should refactor them so that computing and plugging don't happen in the same place. Doing so will reduce instances of hard to test code.

In general controllers are plugging code not computing code, so integration tests tend to be the more appropriate choice.

andix15• 5 years ago

At least when the controllers are all classes I can unit test them.

There is normally not such a big benefit in unit testing them, as controllers should only call some service behind. This service you can test.

Controllers are better integration tested, with a mock service behind. So you actually test if your routing and response codes are picked up correctly by the framework.

There is TestServer for asp.net core. It gives you a very easy solution for integration testing, if set up correctly they are nearly as fast as plain unit tests.

jameshart5• 5 years ago

If it has a mock service behind it, how is that an integration test?

oaiey7• 5 years ago

If you are interested in following an architect in the .NET team at Microsoft, follow @davidfowl. I met him once irl, and he is the most amazing person.

He is the most influential architect within the .NET team at Microsoft and basically created ASP.NET Core together with Damian Edwards as PM. The non-core edition you need to search higher up the ranks ... Scott Guthrie ... boss of Azure.

reverseblade2• 5 years ago

I like giraffe better. https://github.com/giraffe-fsharp/Giraffe

pharmakom3• 5 years ago

Suave is a cleaner API in my view but Giraffe has better performance on the edges.

nobleach• 5 years ago

When I was doing F#, I loved both of these projects. I don't think we should always view ExpressJS/Sinatra (from Ruby) as "the standard", but there's also something to not having to do an hour of work before we can get endpoints serving responses.

phillipcarter2• 5 years ago

I do too! One thing I do hope happens is Giraffe is able to use some of the newer APIs to simplify configuration. Config is generally something you stuff in a file to not look much at, but it can sometimes feel kinda hairy.

oaiey7• 5 years ago

This is part of a larger push to make ASP.NET Core and .NET easier for beginners. The difference between node.js + express vs. ASP.NET Core was a lot of boilerplate to return the first Hello World. Overcoming that churn is a huge problem for .NET adoption.

Do not take three-line-minimal APIs as the end product for robust, safe and reliable endpoints. We all know better than trusting 3-line-presentations.

As a seasoned .NET programmers I have a love-hate relationship to this new set of features (there are more!!!). The simplicity for rapid prototyping (or beginners) vs. the organized OOP template. The .NET 6 release will be very controversal. .NET will not get worse, however, a lot of (existing .NET/Java) people will complain about the new project/coding style attached to it.

Hawxy• 5 years ago

I've recently started using the new .NET 6 templates and honestly I don't miss the OOP boilerplate. Yes it's a bit of a shock at first, but you quickly realize that having your ASP.NET Core startup code split into two files and three functions has no real-world benefit.

I'll still be using traditional controllers for my endpoints, however the syntactic sugar in C# 10 does improve the experience by reducing nesting and noise in general (file-scoped namespaces & implicit global usings).

Overall I'm pretty happy with it.

jayd162• 5 years ago

code split into two files and three functions

You could always put multiple classes in a file if you wanted to organize that way. The new language changes just reduce nesting and boilerplate the IDE already took care of. (which isn't nothing). These framework changes to focus on lambdas is pretty nice though.

kumarvvr2• 5 years ago

When it is purely about ASP.NET, getting rid of the old style Startup class is ok for me.

The code is more compact, concise and less verbose. Most of the code in the startup is not touched in any meaningful sense after the initial setup.

corpdronejuly• 5 years ago

The bigger issue for me will be the way that these kinds of things tend to split communities.

It doesn't do big enterprise devs much good if we have a lot of cool new features if there's no path towards using them in our 20 year old legacy applications that keep the business running.

giobox• 5 years ago

If you are a server side web app, the migration process from legacy net Framework app to net 5/6 has gotten _a lot_ easier in past few years.

The biggest barrier for most in my experience has been getting through the project file (*.csproj) changes needed. Even today, there is still no fully automated way to do it. Thankfully, after ~4 years of community complaints, Microsoft finally aquiessed and made a CLI tool that does about 80 percent of that work:

https://github.com/dotnet/upgrade-assistant

Before the release of this tool, you had to rely on community made tools/guides or just rewrite the project file by hand to the new format. I inherited a project with over 600 large net4x csproj files - prior to this tool Microsoft's official stance was "rewrite them by hand". This goes down like a cup of cold sick at many Enterprise software shops with hundreds or thousands of project files to update.

I still think the upgrade process needs some more polish/wizards in the VS UI, for junior developers especially, but it's gotten much better. The vast majority of important third party dependencies are all net5 ready now in my experience now, so often just replacing the csproj file and setting target framework to net5 is enough.

If you have a legacy WinForms/GUI app however and want full cross-platform benefits of net5... cost to move to modern UI framework can be significant. CLI apps/web apps are by far the easiest to port to net5.

mathw• 5 years ago

I'm happy to get rid of the "organized OOP template" which is really just a bloaty mess of unnecessary classes. Given that all the IoC and request binding systems are supported in these minimal APIs I have no reason to believe I'll ever have to write a Controller class in .NET 6 again at the moment. And I won't miss it. The MVC pattern from ASP.NET MVC never did make sense for web requests.

oaiey7• 5 years ago

I never considered this as OOP ... they are just names to give some organization. I think the only OOP is the instantiation of the controllers ... which are instantiated per request => pointless ;).

So you are right, easy to transfer, but we will see midterm new file/naming based structures showing up when the first teams working with minimal apis with massive amount of apis.

weijoi• 5 years ago

Everything in a single file without namespaces brackets and other boilerplate. Good.

throwaway4good• 5 years ago

So now that they have gotten bored copying Java Spring, they start copying Express.js?

jf22• 5 years ago

What would be the alternative?

Not integrate and adopt useful features and smart paradigms that other frameworks have?

thrower123• 5 years ago

On the one hand, I've been using approximately this style for defining routes for years using NancyFx. It's easy, it's explicit, it's much better than either the attribute or convention routing ASP MVC and WebApi have used.

On the other, I hate how this is telescoping all the configuration and setup code into a blackbox. Any kind of real project, even minimal microservices, is going to have to deal with authentication and caching and logging and monitoring middlewares, and it's bad that these samples obfuscate the way that one would do that.

LAC-Tech4• 5 years ago

Looking forward to this. I quite enjoyed C# but the boiler plate of ASP.NET always turned me off.

pharmakom3• 5 years ago

Shoehorning OOP into building HTTP APIs was the original sin IMO.

bob1029• 5 years ago

These sort of efforts are commendable.

I still don't like the state of parts of ASP.NET Core. 9/10 times I will just write my own Middleware and directly work with HttpContext. Blazor handles 99% of our former MVC concerns today, so we've basically done away with controllers.

rattray• 5 years ago

As someone who isn't familiar with .NET, I wish this post had an example with a JSON request body and response.

klaussilveira• 5 years ago

You can bind JSON to structs: https://gist.github.com/davidfowl/ff1addd02d239d2d26f4648a06...

Or you can customize how it happens: https://gist.github.com/davidfowl/ff1addd02d239d2d26f4648a06...

As for responses: https://gist.github.com/davidfowl/ff1addd02d239d2d26f4648a06...

DonnyV• 5 years ago

Things start getting a little verbose with everything on 1 line thrown inside a function.

  app.MapGet("/todos/{id:int}", [Authorize("AdminsOnly")] (int id) => "This endpoint is for admins only");

Attributes make things cleaner with everything having its own line. Also you lose the ability to group a bunch of methods in 1 controller together under the same authentication policy.

moogly2• 5 years ago

There is a multitude of ways in which you could format that code:

  app.MapGet(
      "/todos/{id:int}",
      [Authorize("AdminsOnly")](int id)
          => "This endpoint is for admins only");

Or for people who don't like expression bodied members:

  app.MapGet(
      "/todos/{id:int}",
      [Authorize("AdminsOnly")](int id)
      {
          return "This endpoint is for admins only");
      });

Extracted to a method:

  app.MapGet("/todos/{id:int}", GetTodos);

  [Authorize("AdminsOnly"]
  string GetTodos(int id) => "This endpoint is for admins only";

And more...

You could also put these methods in a class and put the attribute on the class, which would solve your "grouping" problem.

phillipcarter2• 5 years ago

I love this, not because of the "it's for beginners" framing, but from a "I want less boilerplate" framing. I look forward to a future .NET that gets less verbose each release, regardless of language chosen.

ripley122• 5 years ago

Same! Your Simple Programs proposal in that area is really great: https://github.com/dotnet/designs/pull/213

I am really looking forward to the day when I can use C# for all my scripting needs instead of Bash/Python/PowerShell. We’re getting there.

urza• 5 years ago

Nancy and Sinatra anyone? :)

zija• 5 years ago

I don't know what to think about it. Half-baked idea: use free functions only in one file in project is meh..

Modern Kotlin, Scala, F# can and use free functions and reduce boilerplates to minimum. C# developers wants attract newbies, juniors, fans of J's, python etc and simultaneously don't disturb old users, fans of c#/java and enterprise development.

"It's only for quick scripts, prototyping, for teaching". Choose a side, don't pretend that you are modern and cool.

Modern c# is fine, but some features are only sugar, and yet i still waiting for proper sum types with exhausting pattern matching. Slow progressing java have this in 17 version..

throw868788• 5 years ago

The real reason is to attract and onboard people onto the platform. Part of me always felt they should of just put a functional wrapper on their APIs, have an API that avoids the mutative fluent interface, and then just show some F# examples. Especially for people outside the .NET ecosystem it would show how terse, yet performant and feature rich the platform actually is. It would compare well to examples from other langs/ecosystems.

In the workplaces I've been in newer developers typically try then abandon the OO paradigm. They've seen they can get by without it and get decent performance, and there is a learning curve which experienced people have already paid for and typically then take for granted (patterns, DI, class structure, interfaces vs abstract classes, etc etc etc).

Minimal APIs at a glance in .NET 6

Related Stories