DEV Community: Marcel Michau

Taming Startup.cs in ASP.NET Core

Marcel Michau — Tue, 20 Oct 2020 08:44:45 +0000

Overview

There are plenty of ASP.NET Core projects out on the internet. All of them have one thing in common. The Startup.cs file. There's also another thing that a lot of these Startup.cs files have in common - they are HUGE.

The Problem

For those unfamiliar with Startup.cs, this is the class that wires up pretty much everything in ASP.NET Core. It's where the request pipeline, dependency injection container, configuration & others get configured. The official docs can be found here. The issue with being responsible for wiring up pretty much everything is that this class tends to grow quite large as more things need to be configured. This problem is compounded with plenty of documentation & tutorials suggesting that, to wire up [insert feature here], all you need to do is drop [insert code snippet here] into Startup.cs and you're off to the races. And the file just keeps on growing...

This causes a few things:

The Startup class becomes difficult to navigate because there's a lot happening in it
The Startup class violates the Single Responsibility Principle (SRP) because it no longer has a single reason to change
It hurts maintainability because there's a high chance of merge conflicts if multiple developers make changes to the Startup class simultaneously

The Problem in Practice

Let's take the following Startup.cs template as a starting point, taken from the .NET Core Web API template (comments removed for brevity):

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseHttpsRedirection();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

Awesome, clean & simple. For now.

Now let's add our first feature. Any application with reasonable complexity is going to need to store some data somewhere. So, let's add Entity Framework Core & wire it up with SQL Server. As per the docs, we add the following to ConfigureServices:

services.AddDbContext<SchoolContext>(options =>
    options.UseSqlServer(Configuration.GetConnectionString("SchoolContext")));

We also want to be good citizens & document our API so that it can be used by others. So let's use Swashbuckle to add some Open API (Swagger) documentation to our API. So we add the following to ConfigureServices:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My Awesome API", Version = "v1" });
});

And the following to Configure, inside the env.IsDevelopment() check:

app.UseSwagger();
app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "My Awesome API v1"));

We've also written a couple of custom classes & interfaces which we need to add to the ServiceCollection for Dependency Injection, so let's add them to ConfigureServices:

services.AddScoped<INotificationService, EmailNotificationService>();
services.AddScoped<INotificationService, SmsNotificationService>();
services.AddScoped<INotificationService, PushNotificationService>();

That's enough features for today. Not too many, but enough to start off with. Now our Startup class looks like this:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();

        services.AddDbContext<SchoolContext>(options =>
            options.UseSqlServer(Configuration.GetConnectionString("SchoolContext")));

        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new OpenApiInfo { Title = "My Awesome API", Version = "v1" });
        });

        services.AddScoped<INotificationService, EmailNotificationService>();
        services.AddScoped<INotificationService, SmsNotificationService>();
        services.AddScoped<INotificationService, PushNotificationService>();
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
            app.UseSwagger();
            app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "My Awesome API v1"));
        }

        app.UseHttpsRedirection();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

It's not too hairy quite yet, but we've only added three features. Imagine what this will look like once we add authentication, authorization, validation, exception handling, logging, caching, customizing Swagger, etc. It can get out of hand for a reasonably-sized application.

The Alternative

The following approach aims to address these issues by refactoring our Startup.cs file so that we can all sleep a little better at night, and we all know that sleep is important.

Let's try to separate some of the Startup class' concerns by refactoring some of them to separate classes. We can use some of the same tricks used by the ASP.NET Core team to accomplish this. For example, if we look at the following line:

services.AddControllers();

What that's doing is configuring all the necessary bits & pieces so that we can use Controllers in an ASP.NET Core Web API, including stuff like Authorization, CORS, Data Annotations, ApiExplorer, etc. But it's all just one line of code. Neat.

That is also an extension method that operates on IServiceCollection. So let's try and write some of our own extension methods which work with IServiceCollection, starting with the database:

internal static class DatabaseServiceCollectionExtensions
{
    public static IServiceCollection AddDatabaseConfiguration(this IServiceCollection services,
        IConfiguration configuration)
    {
        services.AddDbContext<SchoolContext>(options =>
            options.UseSqlServer(Configuration.GetConnectionString("SchoolContext")));

        return services;
    }
}

Here we have a static class named DatabaseServiceCollectionExtensions because it contains extension methods which operate on IServiceCollection.

There is one static method, AddDatabaseConfiguration which takes the IServiceCollection & IConfiguration as parameters and returns an IServiceCollection. This method then calls the same code we had in Startup to configure Entity Framework Core, and then returns the updated IServiceCollection.

Then we can use it in our Startup class inside ConfigureServices like so:

services.AddDatabaseConfiguration(Configuration);

The Configuration argument is optional for these extension methods, it's just there for the case where the extension method needs something from config in order to perform it's logic, as is the case with the AddDatabaseConfiguration method.

We can then continue this trend for our own application services:

internal static class ApplicationServicesServiceCollectionExtensions
{
    public static IServiceCollection AddApplicationServicesConfiguration(this IServiceCollection services)
    {
        services.AddScoped<INotificationService, EmailNotificationService>();
        services.AddScoped<INotificationService, SmsNotificationService>();
        services.AddScoped<INotificationService, PushNotificationService>();    

        return services;
    }
}

And use it in Startup:

services.AddApplicationServicesConfiguration();

As for Swagger, we needed to make changes to both ConfigureServices and Configure in order to wire it up. Therefore,we'll need two extension methods, one which operates on IServiceCollection as before, and one which operates on IApplicationBuilder for the logic in the Configure method:

internal static class SwaggerExtensions
{
    public static IServiceCollection AddSwaggerConfiguration(this IServiceCollection services,
        IConfiguration configuration)
    {
        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new OpenApiInfo { Title = "My Awesome API", Version = "v1" });
        });

        return services;
    }

    public static IApplicationBuilder UseSwaggerConfiguration(this IApplicationBuilder app)
    {
        app.UseSwagger();

        return app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "My Awesome API v1"));
    }
}

Then we just use them in Startup in their respective methods. In ConfigureServices:

services.AddSwaggerConfiguration();

And in Configure:

app.UseSwaggerConfiguration();

After all this, our Startup class looks like this:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();
        services.AddDatabaseConfiguration(Configuration);
        services.AddApplicationServicesConfiguration();
        services.AddSwaggerConfiguration();
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
            app.UseSwaggerConfiguration();
        }

        app.UseHttpsRedirection();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

That's a bit better. 😁

Conclusion

This approach has a few benefits:

It keeps the Startup class focused by moving configuration logic out to separate classes
It prevents the Startup class from growing uncontrollably
It maintains a better separation of concerns such that, when something changes in the configuration of Swagger, for example, that change is isolated to the class which deals with Swagger configuration
It improves maintainability because it's easier to find & navigate to the class which deals with a specific feature rather than scrolling through the entirety of the Startup class looking for the specific line which needs to be changed

I hope this has proved useful to someone & that it helps you make your applications' code slightly simpler. 😀

Quickly Scaffold REST API Model Classes in Visual Studio

Marcel Michau — Mon, 01 Jun 2020 11:17:41 +0000

Photo by Pakata Goh on Unsplash

Picture the following scenario:

PM:
We need to integrate with FooBar's API.

You:
Okay cool, what kind of API is it? REST? GraphQL? gRPC? SOAP? *shudders*

PM:
It's a JSON REST API.

You:
Oh wonderful, do they have some Swagger docs?

PM:
Not that I know of.

You:
Hmm, Postman collection?

PM:
Nope.

You:
Any documentation?

PM:
No, we've been given some endpoints & you'll need to check what they send back.

You:
Okay great.

PM:
So how long will it take to integrate with their API?

You:
Well, there are a lot of unknowns: we don't know what Auth they have on the API, how complex their response models are, or whether the data is even going to be useful or not.

PM:
Okay so rough estimate? More than a week? Less than a week?

You:
I will need to do some investigation first, can you give me until tomorrow?

PM:
Hmm, yeah, is there any way we can bring in the timeline? We need to get this done as soon as possible.

You:

Okay, so maybe this tip will not solve all potential issues which may arise in the software development industry, but it may help you save some time when you need to work with a third party API.

Visual Studio Paste Special to the Rescue

For those of you who already know about this feature, stop reading now, you are already as productive as you can be. :)

But for those of you who don't, this is quite a lesser known feature in Visual Studio not many people are familiar with. I feel it can really help out when you need to create your C# POCO (Plain Old CLR Object) classes for serilializing/deserializing your JSON API payloads - without having to type them all out by hand. Let the computers do the boring, repetitive stuff. Plus, this tip does not require the use of any extensions or third-party utilities.

For example, let's assume we get the following response from an API (taken from the Working with JSON page from MDN):

{
  "squadName": "Super hero squad",
  "homeTown": "Metro City",
  "formed": 2016,
  "secretBase": "Super tower",
  "active": true,
  "members": [
    {
      "name": "Molecule Man",
      "age": 29,
      "secretIdentity": "Dan Jukes",
      "powers": [
        "Radiation resistance",
        "Turning tiny",
        "Radiation blast"
      ]
    },
    {
      "name": "Madame Uppercut",
      "age": 39,
      "secretIdentity": "Jane Wilson",
      "powers": [
        "Million tonne punch",
        "Damage resistance",
        "Superhuman reflexes"
      ]
    },
    {
      "name": "Eternal Flame",
      "age": 1000000,
      "secretIdentity": "Unknown",
      "powers": [
        "Immortality",
        "Heat Immunity",
        "Inferno",
        "Teleportation",
        "Interdimensional travel"
      ]
    }
  ]
}

Now, in order to be able to use this data in our C# application, we'd need to create a class with properties that correspond to the properties in the JSON response object.

For a simple response like this, it might not take too long. But for an object with 50 properties, different data types & multiple levels of nesting it can get quite tedious.

To quickly scaffold this JSON payload's POCO in Visual Studio, firstly create a new class & remove the class declaration so that only the namespace declaration remains:

Then, copy the entire JSON response object to your clipboard, then back in Visual Studio, place your cursor at the location you want to paste, but instead of using a normal paste, navigate to Edit > Paste Special > Paste JSON as Classes.

This will then generate the following classes:

The scaffolding tool will then parse the JSON and create properties for each of the objects & try to guess the correct data type for each one. In this case, you can see that it set some properties to string, int & bool. Sometimes it may trip up on things like dates where the format might be a bit weird.

By default, Visual Studio will give the root class a name of Rootobject & name the properties the same as the keys in the JSON object, but you are free to change the class & property names to match your naming convention. Just be aware that you may need to configure your JSON serializer appropriately, depending on your case convention.

For the Visual Studio Code users among us, there is an awesome extension which provides much of the same (and more) functionality than the built-in Visual Studio one. Check it out here: Paste JSON as Code.

That's pretty much it! It's quite a simple little thing, but I've seen quite a few people that didn't know about this handy little feature. I hope it helps you out & shaves off a bit of your precious time.

Happy coding!

Building a Microservice Application using C#, ASP.NET Core, Docker & Kubernetes

Marcel Michau — Tue, 28 Jan 2020 08:37:59 +0000

Photo by Anas Alshanti on Unsplash

Hello everyone!

This is my first post on dev.to, so I'm very new to this. :)

I'd like to share something which I built recently.

After reading the .NET Microservices: Architecture for Containerized .NET Applications book, I felt inspired to build something using the concepts I learned in the book. But you know how it goes, I got the old writer's block when deciding what on Earth I'm going to build. I didn't want to write yet another to-do app because I wanted to play around with the Domain-Driven Design (DDD) & Command Query Responsibility Segregation (CQRS) concepts described in the book. A simple to-do app would not have the appropriate domain complexity which would allow me to flex my newly acquired DDD muscle (the muscle in question is still quite small, I've only just gotten into this).

I wanted to tackle a problem which was just complex enough to apply some DDD patterns, but not too complex such that it requires expert knowledge to understand. Therefore, I chose a completely imaginary problem.

How often do you find yourself in the need to decide between multiple options? Whether it's where to go for your next team lunch, which book to read next, which Game of Thrones character to dress up as for Halloween, or how to arrange your Steam wishlist. Don't you wish there was something that could make this decision process easier? Fortunately, there is a method that plenty of industry experts use to gather feedback on specific topics: Surveys. But what if you don't have the time or resources to compile a survey, send it out to multiple respondents, wait for their feedback, consolidate the results and then finally make your decision? This is where Fake Survey Generator comes in...

Yes, the interface is basic, but it's also minimal.

How it works: you capture some basic info about the survey you'd like to create:

Click on Create Survey, and the results will be calculated:

There. It's definitive. The community has spoken.

Fake Survey Generator features

The back-end side of the app is built with a variety of frameworks, tools & libraries predominantly centered around the C# .NET stack, while the front-end side is currently a basic React app written in TypeScript. In a nutshell, it's slightly more complex than a to-do app, but it's built as if it were a real-world, production-ready microservice application. Therefore, it uses a real database, has authentication, validation rules, health checks, fault handling, logging, caching, unit tests, integration tests & a CI/CD pipeline that deploys to Kubernetes. In short, overkill.

I mainly built Fake Survey Generator as a platform to teach myself new concepts and to try stuff out, while also serving as a reference application when building new things. There are still plenty of features I'd like to add to the app in due course such as asynchronous messaging using queues, experimenting with GraphQL & gRPC, and adding some more bounded contexts.

Hopefully it can serve as a useful reference for any other .NET devs out there who are interested in topics such as Clean Architecture, DDD, CQRS as well as Docker & Kubernetes.

More information & guidelines on how to run everything can be found on the project README on GitHub:

MarcelMichau / fake-survey-generator

A slightly more-than-trivial full-stack application built with DDD & CQRS concepts

Logo by Undraw

Fake Survey Generator

This is an app. That generates surveys. Fake ones. For fun. That is all

Open in github.dev

Screenshot

What is this?

This is a .NET | C# | React | TypeScript full-stack application of moderate complexity (not just a to-do app), used as a playground for experimentation. Simply put: This is where I mess around with code. It is heavily inspired by the .NET Microservices: Architecture for Containerized .NET Applications book, as well as its companion reference application eShopOnContainers. It also incorporates various elements from different repos & blog posts which served as inspiration.

It is built using Vertical Slice Architecture principles with CQRS (Command Query Responsibility Segregation) and DDD ( Domain-Driven Design) thrown into the mix. It doesn't follow these principles to the letter, but provides a decent example of how to apply the basics of these principles.

It is heavily centered…

View on GitHub

I'm keen to hear any feedback, and of course, PRs, contributions & suggestions are welcome!