Exploring a minimal Web API with ASP.NET Core 6
I write about minimal Web APIs in 2016 and my goal has always been for "dotnet server.cs" to allow for a single file simple Web API. Fast forward to 2021 and there's some great work happening again in the minimal API space!
Let's do a 'dotnet new web' with the current .NET 6 preview. I'm on .NET 6 preview 7. As mentioned in the blog:
We updated .NET SDK templates to use the latest C# language features and patterns. We hadn’t revisited the templates in terms of new language features in a while. It was time to do that and we’ll ensure that the templates use new and modern features going forward.
The following language features are used in the new templates:
- Top-level statements
- async Main
- Global using directives (via SDK driven defaults)
- File-scoped namespaces
- Target-typed new expressions
- Nullable reference types
This is pretty cool. Perhaps initially a bit of a shock, but this a major version and a lot of work is being done to make C# and .NET more welcoming. All your favorite things are still there and will still work but we want to explore what can be done in this new space.
Richard puts the reasoning very well:
The templates are a much lower risk pivot point, where we’re able to set what the new “good default model” is for new code without nearly as much downstream consequence. By enabling these features via project templates, we’re getting the best of both worlds: new code starts with these features enabled but existing code isn’t impacted when you upgrade.
This means you'll see new things when you make something totally new from scratch but your existing stuff will mostly work just fine. I haven't had any trouble with my sites.
Let's look at a super basic hello world that returns text/plain:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
if (app.Environment.IsDevelopment()){ app.UseDeveloperExceptionPage(); }
app.MapGet("/", () => "Hello World!");
app.Run();
Slick. Note that I made line 3 (which is optional) just be one line to be terse. Not needed, just trying on these new shoes.
If we make this do more and support MVC, it's just a little larger. I could add in app.MapRazorPages() if I wanted instead of MapControllerRoute, which is what I use on my podcast site.
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddControllersWithViews();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");
app.Run();
Back to the original Web API one. I can add Open API support by adding a reference to Swashbuckle.AspNetCore and then adding just a few lines:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseSwagger();
app.MapGet("/", () => "Hello World!");
app.UseSwaggerUI();
app.Run();
Then I hit https://localhost:5001/swagger and I get the SwaggerUI and a little WebAPI Tester:
Anuraj has a great blog where he goes deeper and pokes around David Fowlers GitHub and creates a minimal WebAPI with Entity Framework and an in-memory database with full OpenAPI support. He put the source at at https://github.com/anuraj/MinimalApi so check that out.
Bipin Joshi did a post also earlier in June and explored in a bit more detail how to hook up to real data and noted how easy it was to return entities with JSON output as the default. For example:
app.UseEndpoints(endpoints => {
endpoints.MapGet("/api/employees",([FromServices] AppDbContext db) =>
{
return db.Employees.ToList();
});
...snip...
}
That's it! Very clean.
Dave Brock did a tour as well and did Hello World in just three lines, but of course, you'll note he used WebApplication.Create while you'll want to use a Builder as seen above for real work.
var app = WebApplication.Create(args);
app.MapGet("/", () => "Hello World!");
await app.RunAsync();
Dave does point out how nice it is to work with simple models using the C# record keyword which removes a LOT of boilerplate cruft.
Check this out!
var app = WebApplication.Create(args);
app.MapGet("/person", () => new Person("Scott", "Hanselman"));
await app.RunAsync();
public record Person(string FirstName, string LastName);
That's it, and if you hit /person you'll get back a nice JSON WebAPI with this result:
{
firstName: "Scott",
lastName: "Hanselman"
}
Dig even deeper by checking out Maria Naggaga's presentation in June that's on YouTube where she talks about the thinking and research behind Minimal APIs and shows off more complex apps. Maria also did another great talk in the same vein for the Microsoft Reactor so check that out as well.
Is this just about number of lines of code? Have we moved your cheese? Will these scale to production? This is about enabling the creation of APIs that encapsulate best practices but can give you the "middleware-like" performance with the clarity and flexibility that was previous available with all the ceremony of MVC.
Here's some more resources:
- David Fowler's GitHub demo https://github.com/davidfowl/dotnet6minimalapi/tree/main/Dotnet6_Minimal_API
- A ToDo API as a Minimal API https://github.com/davidfowl/CommunityStandUpMinimalAPI
- Exploring what Integration Testing looks like in a .NET 6 world by Martin Costello https://github.com/martincostello/dotnet-minimal-api-integration-testing I'll be exploring Martin's codebase next!
Have fun! Lots of cool things happening this year, even in the middle of the panini. Stay safe, friends.
Sponsor: Pluralsight helps teams build better tech skills through expert-led, hands-on practice and clear development paths. For a limited time, get 50% off your first month and start building stronger skills.
About Scott
Scott Hanselman is a former professor, former Chief Architect in finance, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed stand-up comic, a cornrower, and a book author.
About Newsletter
There's reasons to do each of these things, but as a general rule your sense of Code Smell should light up if you smell Stringly Typed things.
