DEV Community: Davide Bellone

HTTP Logging in ASP.NET: how to automatically log all incoming HTTP requests (and its downsides!)

Davide Bellone — Mon, 23 Mar 2026 00:00:00 +0000

Whenever we publish a service, it is important to add proper logging to the application. Logging helps us understand how the system works and behaves, and it's a fundamental component that enables us to troubleshoot problems that occur during application use.

In this blog, we have discussed logging several times. However, we mostly focused on manually written logs.

In this article, we will learn how to log incoming HTTP requests to help us understand how our APIs are being used from the outside.

Scaffolding the empty project

To showcase this type of logging, I created an ASP.NET API. It's a very simple application with CRUD operations on an in-memory collection.

[ApiController]
[Route("[controller]")]
public class BooksController : ControllerBase
{
    private readonly List<Book> booksCatalogue = Enumerable.Range(1, 5).Select(index => new Book
    {
        Id = index,
        Title = $"Book with ID {index}"
    }).ToList();

    private readonly ILogger<BooksController> _logger;

    public BooksController(ILogger<BooksController> logger)
    {
        _logger = logger;
    }
}

These CRUD operations are exposed via HTTP APIs, following the usual verb-based convention.

For example:

[HttpGet("{id}")]
public ActionResult<Book> GetBook([FromRoute] int id)
{
    _logger.LogInformation("Looking if in my collection with {TotalBooksCount} books there is one with ID {SearchedId}"
            , booksCatalogue.Count, id);

    Book? book = booksCatalogue.SingleOrDefault(x => x.Id == id);

    return book switch
    {
        null => NotFound(),
        _ => Ok(book)
    };
}

As you can see, I have added some custom logs: before searching for the element with the specified ID, I also wrote a log message such as "Looking if in my collection with 5 books there is one with ID 2".

Where can I find the message? For the sake of this article, I decided to use Seq!

Seq is a popular log sink (well, as you may know, my favourite one!), that is easy to install and to integrate with .NET. I've thoroughly explained how to use Seq in conjunction with ASP.NET in this article and in other ones.

In short, the most important change in your application is to add Seq as the log sink, like this:

builder.Services.AddLogging(lb => {
    lb.AddSeq();
});

Now, whenever I call the GET endpoint, I can see the related log messages appear in Seq:

But sometimes it's not enough. I want to see more details, and I want them to be applied everywhere!

How to add HTTP Logging to an ASP.NET application

HTTP Logging is a way of logging most of the details of the incoming HTTP operations, tracking both the requests and the responses.

With HTTP Logging, you don't need to manually write custom logs to access the details of incoming requests: you just need to add its related middleware, configure it as you want, and have all the required logs available for all your endpoints.

Adding it is pretty straightforward: you first need to add the HttpLogging middleware to the list of services:

builder.Services.AddHttpLogging(lb => { });

so that you can use it once the WebApplication instance is built:

app.UseHttpLogging();

There's still a problem, though: all the logs generated via HttpLogging are, by default, ignored, as logs coming from their namespace (named Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware) are at Information log level, thus ignored because of the default configurations.

You either have to update the appsetting.json file to tell the logging system to process logs from that namespace:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware": "Information"
    }
  }
}

or, alternatively, you need to do the same when setting up the logging system in the Program class:

builder.Services.AddLogging(lb => {
  lb.AddSeq();
+ lb.AddFilter("Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware", LogLevel.Information);
});

We then have all our pieces in place: let's execute the application!

First, you can spin up the API; you should be able to see the Swagger page:

From here, you can call the GET endpoint:

You should now be able to see all the logs in Seq:

As you can see from the screenshot above, I have a log entry for the request and one for the response. Also, of course, I have the custom message I added manually in the C# method.

Understanding HTTP Request logs

Let's focus on the data logged for the HTTP request.

If we open the log related to the HTTP request, we can see all these values:

Among these details, we can see properties such as:

the host name (localhost:7164)
the method (GET)
the path (/books/4)

and much more.

You can see all the properties as standalone items, but you can also have a grouped view of all the properties by accessing the HttpLog element:

Notice that for some elements we do not have access to the actual value, as the value is set to [Redacted]. This is a default configuration that prevents logging too many things (and undisclosing some values) as well as writing too much content on the log sink (the more you write, the less performant the queries become - and you also pay more!).

Among other redacted values, you can see that even the Cookie value is not directly available - for the same reasons explained before.

Understanding HTTP Response logs

Of course, we can see some interesting data in the Response log:

Here, among some other properties such as the Host Name, we can see the Status Code and the Trace Id (which, as you may notice, is the same as the one in the Request).

As you can see, the log item does not contain the body of the response.

Also, just as it happens with the Request, we do not have access to the list of HTTP Headers.

How to save space, storage, and money by combining log entries

For every HTTP operation, we end up with 2 log entries: one for the Request and one for the Response.

However, it would be more practical to have both request and response info stored in the same log item so we can understand more easily what is happening.

Lucky for us, this functionality is already in place. We just need to set the CombineLogs property to true when we add the HttpLogging functionality:

builder.Services.AddHttpLogging(lb =>
{
+  lb.CombineLogs = true;
}
);

Then, we are able to see the data for both the request and the related response in the same log element.

The downsides of using HTTP Logging

Even though everything looks nice and pretty, adding HTTP Logging has some serious consequences.

First of all, remember that you are doing some more operations for every incoming HTTP request. Just processing and storing the log messages can bring to an application performance downgrade - you are using parts of the processing resources to interpret the HTTP context, create the correct log entry, and store it.

Depending on how your APIs are structured, you may need to strip out sensitive data: HTTP Logs, by default, log almost everything (except for the parts stored as Redacted). Since you don't want to store the content of the requests as plain text, you may need to create custom logic to redact parts of the request and response you want to hide: you may need to implement a custom IHttpLoggingInterceptor.

Finally, consider that logging occupies storage, and storage has a cost. The more you log, the higher the cost. You should define proper strategies to avoid excessive storage costs while keeping valuable logs.

Wrapping up

HTTP Logging can be a good tool for understanding the application behaviour and detecting anomalies. However, as you can see, there are some important downsides that need to be considered.

Fitness Functions in Software Architecture: measuring things to ensure prosperity

Davide Bellone — Thu, 19 Mar 2026 00:00:00 +0000

Just creating an architecture is not enough; you should also make sure that the pieces you are building are, in the end, the ones your system needs.

Is your system fast enough? Is it passing all the security checks? What about testability, maintainability, and other -ilities?

Fitness Functions are components of the architecture that do not execute functional operations, but, using a set of tests and measurements, allow you to validate that the system respects all the non-functional requirements defined upfront.

Fitness Functions: because non-functional requirements matter

An architecture is made of two main categories of requirements: functional requirements and non-functional requirements.

Functional requirements are the easiest to define and test: if one of the requirements is "a user with role Admin must be able to see all data", then writing a suite of tests for this requirement is straightforward.

Non-functional requirements are, for sure, as important as functional requirements, but are often overlooked or not detailed. "The system must be fast": ok, how fast? What do you mean by "fast"? What is an acceptable value of "fast"?

If we don't have a clear understanding of non-functional requirements, then it's impossible to measure them.

And once we have defined a way to measure them, how can we ensure that we are meeting our expectations? Here's where Fitness Functions come in handy.

In fact, Fitness Functions are specific components that focus on non-functional requirements, executing some calculations and providing metrics that help architects and developers ensure that the system's architecture aligns with business goals, technical requirements, and other quality attributes.

Why Fitness Functions are crucial for future-proof architectures

When creating an architecture, you must think of the most important -ilities for that specific case. How can you ensure that the technical choices we made meet the expectations?

By being related to specific and measurable metrics, Fitness Functions provide a way to assess the architecture's quality and performance, reducing the reliance on subjective opinions by using objective measurements. A metric can be a simple number (e.g., "maximum number of requests per second"), a percentage value (like "percentage of code covered by tests") or other values that are still measurable.

Knowing how the system behaves with respect to these measures allows architects to work on continuous improvement: teams can identify areas for improvement and make decisions based not on personal opinion but on actual data to enhance the system.

Having a centralised place to view the historical values of a measure helps understand if you have made progress or, as time goes by, the quality has degraded.

Still talking about the historical values of the measures, having a clear understanding of what is the current status of such metrics can help in identifying potential issues early in the development process, allowing teams to address them before they become critical problems.

For example, by using Fitness Functions, you can ensure that the system is able to handle a certain number of users per second: having proper measurements, you can identify which functionalities are less performant and, in case of high traffic, may bring the whole system down.

You are already using Fitness Functions, but you didn't know

Fitness Functions sound like complex things to handle.

Even though you can create your own functions, most probably you are already using them without knowing it. Lots of tools are available out there that cover several metrics, and I'm sure you've already used some of them (or, at least, you've already heard of them).

Tools like SonarQube and NDepend use Fitness Functions to evaluate code quality based on metrics such as code complexity, duplication, and adherence to coding standards. Those metrics are calculated based on static analysis of the code, and teams can define thresholds under which a system can be at risk of losing maintainability. An example of a metric related to code quality is Code Coverage: the higher, the better (even though 100% of code coverage does not guarantee your code is healthy).

Tools like JMeter or K6 help you measure system performance under various conditions. Having a history of load testing results can help ensure that, as you add new functionality to the system, the performance of specific modules does not degrade.

All in all, most of the Fitness Functions can be set to be part of CI/CD pipelines: for example, you can configure a CD pipeline to block the deployment of the code on a specific system if the load testing results of the new code are worse than the previous version. Or you could block a Pull Request if the code coverage percentage is getting lower.

Wrapping up

Sometimes, there are things we use every day but don't know how to name: Fitness Functions are one of them, and they are the foundation of future-proof software systems.

You can create your own Fitness Functions based on whatever you can (and need to) measure: from average page loading to star-rated customer satisfaction. In conjunction with a clear dashboard, you can provide a clear view of the history of such metrics.

C# Tip: 2 ways to generate realistic data using Bogus

Davide Bellone — Tue, 17 Mar 2026 00:00:00 +0000

In a previous article, we delved into the creation of realistic data using Bogus, an open-source library that allows you to generate data with plausible values.

Bogus contains several properties and methods that generate realistic data, such as names, addresses, birthdays, and so on.

In this article, we will learn two ways to generate data with Bogus. Both produce the same result; the main difference lies in reusability and modularity. In my opinion, it's mostly a matter of preference: there is no approach absolutely better than the other, and either approach can be preferable depending on the context.

For the sake of this article, we are going to use Bogus to generate instances of the Book class, defined like this:

public class Book
{
    public Guid Id { get; set; }
    public string Title { get; set; }
    public int PagesCount { get; set; }
    public Genre[] Genres { get; set; }
    public DateOnly PublicationDate { get; set; }
    public string AuthorFirstName { get; set; }
    public string AuthorLastName { get; set; }
}

public enum Genre
{
    Thriller, Fantasy, Romance, Biography
}

Expose a Faker inline or with a method

It is possible to create a specific object that, using a Builder approach, allows you to generate one or more items of a specified type.

It all starts with the Faker<T> generic type, where T is the type you want to generate.

Once you create it, you can define the rules to be used when initializing the properties of a Book by using methods such as RuleFor and RuleForType.

public static class BogusBookGenerator
{
    public static Faker<Book> CreateFaker()
    {
        Faker<Book> bookFaker = new Faker<Book>()
         .RuleFor(b => b.Id, f => f.Random.Guid())
         .RuleFor(b => b.Title, f => f.Lorem.Text())
         .RuleFor(b => b.Genres, f => f.Random.EnumValues<Genre>())
         .RuleFor(b => b.AuthorFirstName, f => f.Person.FirstName)
         .RuleFor(b => b.AuthorLastName, f => f.Person.LastName)
         .RuleFor(nameof(Book.PagesCount), f => f.Random.Number(100, 800))
         .RuleForType(typeof(DateOnly), f => f.Date.PastDateOnly());

        return bookFaker;
    }
}

In this way, thanks to the static method, you can simply create a new instance of Faker<Book>, ask it to generate one or more books, and enjoy the result:

Faker<Book> generator = BogusBookGenerator.CreateFaker();
var books = generator.Generate(10);

Clearly, it's not necessary for the class to be marked as static: it all depends on what you need to achieve!

Expose a subtype of Faker, specific to the data type to be generated

If you don't want to use a method (static or not static, it doesn't matter), you can define a subtype of Faker<Book> whose customization rules are all defined in the constructor.

public class BookGenerator : Faker<Book>
{
    public BookGenerator()
    {
        RuleFor(b => b.Id, f => f.Random.Guid());
        RuleFor(b => b.Title, f => f.Lorem.Text());
        RuleFor(b => b.Genres, f => f.Random.EnumValues<Genre>());
        RuleFor(b => b.AuthorFirstName, f => f.Person.FirstName);
        RuleFor(b => b.AuthorLastName, f => f.Person.LastName);
        RuleFor(nameof(Book.PagesCount), f => f.Random.Number(100, 800));
        RuleForType(typeof(DateOnly), f => f.Date.PastDateOnly());
    }
}

Using this way, you can simply create a new instance of BookGenerator and, again, call the Generate method to create new book instances.

var generator = new BookGenerator();
var books = generator.Generate(10);

Method vs Subclass: When should we use which?

As we saw, both methods bring the same result, and their usage is almost identical.

So, which way should I use?

Use the method approach (the first one) when you need:

Simplicity: If you need to generate fake data quickly and your rules are straightforward, using a method is the easiest approach.
Ad-hoc Data Generation: Ideal for one-off or simple scenarios where you don't need to reuse the same rules across your application.

Or use the subclass (the second approach) when you need:

Reusability: If you need to generate the same type of fake data in multiple places, defining a subclass allows you to encapsulate the rules and reuse them easily.
Complex scenarios and extensibility: Better suited for more complex data generation scenarios where you might have many rules or need to extend the functionality.
Maintainability: Easier to maintain and update the rules in one place.

Wrapping up

This article sort of complements the previous article about Bogus.

I think Bogus is one of the best libraries in the .NET universe, as having realistic data can help you improve the intelligibility of the test cases you generate. Also, Bogus can be a great tool when you want to showcase demo values without accessing real data.

Easy logging management with Seq and ILogger in ASP.NET

Davide Bellone — Mon, 16 Mar 2026 00:00:00 +0000

Logging is one of the most essential parts of any application.

Wouldn't it be great if we could scaffold and use a logging platform with just a few lines of code?

In this article, we are going to learn how to install and use Seq as a destination for our logs, and how to make an ASP.NET 8 API application send its logs to Seq by using the native logging implementation.

Seq: a sink and dashboard to manage your logs

In the context of logging management, a "sink" is a receiver of the logs generated by one or many applications; it can be a cloud-based system, but it's not mandatory: even a file on your local file system can be considered a sink.

Seq is a Sink, and works by exposing a server that stores logs and events generated by an application. Clearly, other than just storing the logs, Seq allows you to view them, access their details, perform queries over the collection of logs, and much more.

It's free to use for individual usage, and comes with several pricing plans, depending on the usage and the size of the team.

Let's start small and install the free version.

We have two options:

Download it locally, using an installer (here's the download page);
Use Docker: pull the datalust/seq image locally and run the container on your Docker engine.

Both ways will give you the same result.

However, if you already have experience with Docker, I suggest you use the second approach.

Once you have Docker installed and running locally, open a terminal.

First, you have to pull the Seq image locally (I know, it's not mandatory, but I prefer doing it in a separate step):

docker pull datalust/seq

Then, when you have it downloaded, you can start a new instance of Seq locally, exposing the UI on a specific port.

docker run --name seq -d --restart unless-stopped -e ACCEPT_EULA=Y -p 5341:80 datalust/seq:latest

Let's break down the previous command:

docker run: This command is used to create and start a new Docker container.
--name seq: This option assigns the name seq to the container. Naming containers can make them easier to manage.
-d: This flag runs the container in detached mode, meaning it runs in the background.
--restart unless-stopped: This option ensures that the container will always restart unless it is explicitly stopped. This is useful for ensuring that the container remains running even after a reboot or if it crashes.
-e ACCEPT_EULA=Y: This sets an environment variable inside the container. In this case, it sets ACCEPT_EULA to Y, which likely indicates that you accept the End User License Agreement (EULA) for the software running in the container.
-p 5341:80: This maps port 5341 on your host machine to port 80 in the container. This allows you to access the service running on port 80 inside the container via port 5341 on your host.
datalust/seq:latest: This specifies the Docker image to use for the container. datalust/seq is the image name, and latest is the tag, indicating that you want to use the latest version of this image.

So, this command runs a container named seq in the background, ensures it restarts unless stopped, sets an environment variable to accept the EULA, maps a host port to a container port, and uses the latest version of the datalust/seq image.

It's important to pay attention to the used port: by default, Seq uses port 5341 to interact with the UI and the API. If you prefer to use another port, feel free to do that - just remember that you'll need some additional configuration.

Now that Seq is installed on your machine, you can access its UI. Guess what? It's on localhost:5341!

However, Seq is "just" a container for our logs - but we have to produce them.

A sample ASP.NET API project

I've created a simple API project that exposes CRUD operations for a data model stored in memory (we don't really care about the details).

[ApiController]
[Route("[controller]")]
public class BooksController : ControllerBase
{
    public BooksController()
    {

    }

    [HttpGet("{id}")]
    public ActionResult<Book> GetBook([FromRoute] int id)
    {

        Book? book = booksCatalogue.SingleOrDefault(x => x.Id == id);
        return book switch
        {
            null => NotFound(),
            _ => Ok(book)
        };
    }
}

As you can see, the details here are not important.

Even the Main method is the default one:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.MapControllers();

app.Run();

We have the Controllers, we have Swagger... well, nothing fancy.

Let's mix it all together.

How to integrate Seq with an ASP.NET application

If you want to use Seq in an ASP.NET application (may it be an API application or whatever else), you have to add it to the startup pipeline.

First, you have to install the proper NuGet package: Seq.Extensions.Logging.

Then, you have to add it to your Services, calling the AddSeq() method:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

+ builder.Services.AddLogging(lb => lb.AddSeq());

var app = builder.Build();

Now, Seq is ready to intercept whatever kind of log arrives at the specified port (remember, in our case, we are using the default one: 5341).

We can try it out by adding an ILogger to the BooksController constructor:

private readonly ILogger<BooksController> _logger;

public BooksController(ILogger<BooksController> logger)
{
    _logger = logger;
}

So that we can use the _logger instance to create logs as we want, using the necessary Log Level:

[HttpGet("{id}")]
public ActionResult<Book> GetBook([FromRoute] int id)
{
    _logger.LogInformation("I am Information");
    _logger.LogWarning("I am Warning");
    _logger.LogError("I am Error");
    _logger.LogCritical("I am Critical");

    Book? book = booksCatalogue.SingleOrDefault(x => x.Id == id);
    return book switch
    {
        null => NotFound(),
        _ => Ok(book)
    };
}

Using Structured Logging with ILogger and Seq

One of the best things about Seq is that it automatically handles Structured Logging.

[HttpGet("{id}")]
public ActionResult<Book> GetBook([FromRoute] int id)
{
    _logger.LogInformation("Looking if in my collection with {TotalBooksCount} books there is one with ID {SearchedId}"
 , booksCatalogue.Count, id);

    Book? book = booksCatalogue.SingleOrDefault(x => x.Id == id);
    return book switch
    {
        null => NotFound(),
        _ => Ok(book)
    };
}

Have a look at this line:

_logger.LogInformation("Looking if in my collection with {TotalBooksCount} books there is one with ID {SearchedId}"
 , booksCatalogue.Count, id);

This line generates a string message, replaces all the placeholders, and, on top of that, creates two properties, SearchedId and TotalBooksCount; you can now define queries using these values.

Wrapping up

I think Seq is the best tool for local development: it's easy to download and install, supports structured logging, and can be easily added to an ASP.NET application with just a line of code.

I usually add it to my private projects, especially when the operations I run are complex enough to require some well-structured log.

Given how it's easy to install, sometimes I use it for my work projects too: when I have to fix a bug, but I don't want to use the centralised logging platform (since it's quite complex to use), I add Seq as a destination sink, run the application, and analyse the logs in my local machine. Then, of course, I remove its reference, as I want it to be just a discardable piece of configuration.

Introducing the Testing Vial: a (better?) alternative to Testing Diamond and Testing Pyramid

Davide Bellone — Mon, 03 Nov 2025 00:00:00 +0000

Testing is crucial in any kind of application. It can also be important in applications that are meant to be thrown away: in fact, with a proper testing strategy, you can ensure that the application will do exactly what you expect it to do; instead of running it over and over again to fix the parts, by adding some specific tests, you will speed up the development of that throwaway project.

The most common testing strategies are the Testing Pyramid and the Testing Diamond. They are both useful, but I think that they are not perfect.

That's why I came up with a new testing strategy that I called "the Testing Vial": in this article, I'm going to introduce it and explain the general idea.

Since it's a new idea, I'd like to hear your honest feedback. Don't be afraid to tell me that this is a terrible idea - let's work on it together!

The Testing Pyramid: the focus is on Unit Tests

The Testing Pyramid is a testing strategy where the focus is on Unit Tests.

Unit Tests are easy to write (well, they are often easy to write: it depends on whether your codebase is a mess!), they are fast to execute, so they provide immediate feedback.

So, the focus here is on technical details: if you create a class named Foo, most probably you will have its sibling class FooTests. And the same goes for each (public) method in it.

Yes, I know: unit tests can operate across several methods of the same class, as long as it is considered a "unit". But let's be real: most of the time, we write tests against each single public method. And, even worse, we are overusing mocks.

Problems with the Testing Pyramid

The Testing Pyramid relies too much on unit tests.

But Unit Tests are not perfect:

They often rely too much on mocks: tests might not reflect the real execution of the system;
They are too closely coupled with the related class and method: if you add one parameter to one single method, you most probably will have to update tens of test methods;
They do not reflect the business operations: you might end up creating the strongest code ever, but missing the point of the whole business meaning. Maybe, because you focused too much on technical details and forgot to evaluate all the acceptance criteria.

Now, suppose that you have to change something big, like

add OpenTelemetry support on the whole system;
replace SQL with MongoDB;
refactor a component, replacing a huge internal switch-case block with the Chain Of Responsibility pattern.

Well, in this case, you will have to update or delete a lot of Unit Tests. And, still, you might not be sure you haven't added regressions. This is one of the consequences of focusing too much on Unit Tests.

The Testing Diamond: the focus is on Integration Tests

The Testing Diamond emphasises the importance of Integration Tests.

So, when using this testing strategy, you are expected to write many more Integration Tests and way fewer Unit Tests.

In my opinion, this is a better approach to testing: this way, you can focus more on the business value and less on the technical details.

Using this approach, you may refactor huge parts of the system without worrying too much about regressions and huge changes in tests: in fact, Integration Tests will give you a sort of safety net, ensuring that the system still works as expected.

So, if I had to choose, I'd go with the Testing Diamond: implementations may change, while the overall application functionality will still be preserved.

Problems with the Testing Diamond

Depending on the size of the application and on how it is structured, Integration Tests may be time-consuming and hard to spin up.

Maybe you have a gigantic monolith that takes minutes to start up: in this case, running Integration Tests may take literally hours.

Also, there is a problem with data: if you are going to write data to a database (or an external resource), how can you ensure that the operation does not insert duplicate or dirty data?

For this problem, there are several solutions, such as:

using Ephemeral Environments specifically to run these tests;
using TestContainers to create a sandbox environment;
replacing some specific operations (like saving data on the DB or sending HTTP requests) by using a separate, standalone service (as we learned in this article, where we customised a WebApplicationFactory).

Those approaches may not be easy to implement, I know.

Also, Integration Tests alone may not cover all the edge cases, making your application less robust.

Introducing the Testing Vial: the focus is on business entities

Did you notice? Both the Testing Pyramid and the Testing Diamond focus on the technical aspects of the tests, and not on the meaning for the business.

I think that is a wrong approach, and that we should really shift our focus from the number of tests of a specific type (more Unit Tests or more Integration Tests?) to the organisational value they bring: that's why I came up with the idea of the Testing Vial.

You can imagine tests to be organised into sealed vials.

In each vial, you have

E2E tests: to at least cover the most critical flows
Integration tests: to cover at least all the business requirements as they are described in the Acceptance Criteria of your User Stories (or, in general, to cover all Happy Paths and the most common Unhappy Paths);
Unit test: to cover at least all the edge cases that are hard to reproduce with Integration tests.

So, using the Testing Vial, you don't have to worry about the number of tests of a specific type: you only care that, regardless of their number, tests are focused on Business concerns.

But, ok, nothing fancy: it's just common sense.

To make the Testing Vial effective, there are two more parts to add.

Architectural tests, to validate that the system design hasn't changed

After you have all these tests, in a variable number which depends solely on what is actually helpful for you, you also write some Architectural Tests, for example, by using ArchUnit, for Java, or ArchUnit.NET for .NET applications.

This way, other than focusing on the business value (regardless of this goal being achieved by Unit Tests or Integration Tests), you also validate that the system hasn't changed in unexpected ways. For example, you might have added a dependency between modules, making the system more coupled and less maintainable.

Generally speaking, Architectural Tests should be written in the initial phases of a project, so that, by running them from time to time, they can ensure that nothing has changed.

With Architectural Tests, which act as a cap for the vial, you ensure that the tests are complete, valid, and that the architecture-wise maintainability of the system is preserved.

But that's not enough!

Categories, to identify and isolate areas of your application

All of this makes sense if you add one or more tags to your tests: these tags should identify the business entity the test is referring to. For example, in an e-shop application, you should add categories about "Product", "Cart", "User", and so on. This is way easier if you already do DDD, clearly.

In C# you can categorise tests by using TestCategory if you use MSTest or NUnit, or Trait if you use xUnit.*

[TestCategory("Cart")]
[TestCategory("User")]
public async Task User_Should_DoSomethingWithCart(){}

Ok, but why?

Well, categorising tests allows you to keep track of the impacts of a change more broadly. Especially at the beginning, you might notice that too many tests are marked with too many categories: this might be a sign of a poor design, and you might want to work to improve it.

Also, by grouping by category, you can have a complete view of everything that happens in the system about that specific Entity, regardless of the type of test.

Did you know that in Visual Studio you can group tests by Category (called Traits), so that you can see and execute all the tests related to a specific Category?

By using Code Coverage tools wisely - executing them in combination with tests of a specific category - you can identify all the parts of the application that are affected by such tests. This is especially true if you have many Integration Tests: just by looking at the executed methods, you can have a glimpse of all the parts touched by that test. This simple trick can also help you out with reorganising the application (maybe by moving from monolith to modular monolith).

Finally, having tests tagged, allows you to have a catalogue of all the Entities and their dependencies. And, in case you need to work on a specific activity that changes something about an Entity, you can perform better analyses to find potential, overlooked impacts.

And each vial can have a different size, but they will all be stored on a "shelf" that lets you have a glimpse at the whole system.

Wrapping up

With the Testing Vial approach, the shift moves from technical to business concerns: you don't really care if you've written more Unit Tests or more Integration tests; you only care that you have covered everything that the business requires, and that by using Architecture Tests and Test Categories you can make sure that you are not introducing unwanted dependencies between modules, improving maintainability.

Vials are meant to be standalone: by accessing the content of a vial, you can see everything related to it: its dependencies, its architecture, main user cases and edge cases.

Clearly, the same test may appear in multiple vials, but that's not a problem.

I came up with this idea recently, so I want to hear from you what you think about it. I'm sure there are areas of improvement!

Let me know!

I hope you enjoyed this article! Let's keep in touch on LinkedIn, Twitter or BlueSky! 🤜🤛

Happy coding!

🐧

Davide's Code and Architecture Notes - the Error Management Trio, and how it affects your software architecture

Davide Bellone — Tue, 05 Nov 2024 00:00:00 +0000

When designing a new software system, it's easy to focus mainly on the happy flow and forget that you must also handle errors.

You should carefully define and design how to handle errors: depending on the use case, error handling can have a huge impact on the architecture of your software system.

In this article, we'll explore the three main categories of errors that we must always remember to address; for each type of error, we will showcase how addressing it can impact the software architecture differently.

An ideal system with only the happy path

To use a realistic example, let's design a simple system with a single module named MainApplication: this module reads data from an external API, manipulates the data, and stores the result on the DB.

The system is called asynchronously, via a Message Queue, by an external service - that we are going to ignore.

The happy flow is pretty much the following:

An external system inserts some data into the Queue;
MainApplication reads the data from the Queue;
MainApplication calls an external API to retrieve some data;
MainApplication stores some data on the DB;
MainApplication sends a message on the queue with the operation result.

Now, the happy flow is simple. But we should have covered what to do in case of an error.

Introducing the Error Management Trio

In general, errors that need to be handled fall into three categories (that I decided to call "the Error Management Trio"): data validation, transient errors, and faults.

Data Validation focuses on the data used across the system, particularly the data you don't control.

Transient Errors occur when the application's overall status or its dependencies temporarily change to an invalid state.

Faults are errors that take down the whole application, and you cannot recover immediately.

The Trio does not take into account "errors" that are not properly errors: null values, queries that do not return any value, and so on. These, in my opinion, are all legitimate statuses that represent that lack of values but are not errors that have architectural relevance.

Data Validation: the first defence against invalid status

The Data Validation category focuses on ensuring that relevant data is in a valid status.

In particular, it aims to ensure that data coming from external sources (for example, from the Body of an incoming HTTP request or from the result of a database query) is both syntactically and logically valid.

Suppose that the messages we receive from the queue are in the following format:

{
  "Username": "mr. captain",
  "BookId": 154,
  "Operation": "Add"
}

We definitely need to perform some sort of validation on the message content.

For example:

The Username property must not be empty;
The BookId property must be a positive number;
The Operation property must have one of the following values: Add, Remove, Refresh;

How does it impact our design?

We have several choices to deal with an invalid incoming message:

ignore the whole message: if it doesn't pass the validation, discard the message;
send the message back to the caller, describing the type of error
try to fix it locally: if we are able to recreate a valid message, we could try to fix it and process the incoming message;
try to fix it in a separate service: you will need to create a distinct service that receives the invalid message and tries to fix it: if it manages to fix the message, it re-inserts it in the original queue; otherwise, it sends a message to the response queue to notify about the impossibility of recreating a valid message.

As you can see, even for the simple input validation, the choices we make can have an impact on the structure of the architecture.

Suppose that you choose option #4: you will need to implement a brand new service (let's call it ValidationFixesManager), configure a new queue, and keep track of the attempts to fix the message.

All of this only when considering the static validation. How would you validate your business rules? How would you ensure that, for instance, the Username is valid and the user is still active on the system?

Maybe you discover that the data stored on the database in incomplete or stale. Then you have to work out a way to handle such type of data.

For example, you can:

run a background job that ensures that all the data is always valid;
enrich the data from the DB with newer data only when it is actually needed;
fine-tune the database consistency level.

We have just demonstrated a simple but important fact: data validation looks trivial, but depending on the needs of your system, it may impact how you design your system.

Transient Errors: temporary errors that may randomly occur

Even if the validation passes, temporary issues may prevent your operations from completing.

In the previous example, there are some possible cases to consider:

the external API is temporarily down, and you cannot retrieve the data you need;
the return queue is full, and you cannot add response messages;
the application is not able to connect to the DB due to network issues;

These kinds of issues are due to a temporary status of the system or of one of its dependencies.

Sure, you may add automatic retries: for instance, you can use Polly to automatically retry accessing the API. But what if it's not enough?

Again, depending on your application's requirements and the overall structure you started designing, solving this problem may bring you to unexpected paths.

Let's say that the external API is returning a 500 HTTP error: this is a transient error, and it does not depend on the content of the request: the API is down, and you cannot do anything to solve it.

What can we do if all the retries fail?

If we can just accept the situation, we can return the error to the caller and move on with the next operation.

But if we need to keep trying until the operation goes well, we have (at least) two choices:

consume the message from the Queue, try calling the API, and, if it fails, re-insert the message on the queue (ideally, with some delay);
peek the message from the queue and try calling the API. If it fails, the message stays on the queue (and you need a way to read it again). Otherwise, we consider the message completed and remove it from the queue.

These are just two of the different solutions. But, as you can see, this choice will have, in the long run, a huge effect on the future of the application, both in terms of maintainability and performance.

Below is how the structure changes if we decide to reinsert the failed messages into the queue with a delay.

In both cases, we must remember that trying to call a service that is temporarily down is useless: maybe it's time to use a Circuit Breaker?

Fatal Errors: when everything goes wrong

There is one type of error that is often neglected but that may deeply influence how your system behaves: fatal errors.

Examples of fatal errors are:

the host has consumed all the CPU or RAM;
the file system is corrupted;
the connection to an external system is interrupted due to network misconfigurations.

In short, fatal errors are errors you have no way to solve in the short run: they happen and stop everything you are doing.

This kind of error cannot be directly managed via application code, but you need to rely on other techniques.

For example, to make sure you won't consume all the available RAM, you should plan for autoscaling of your resources. So you have to design the system with autoscaling in mind: this means, for example, that the system must be stateless and the application must run on infrastructure objects that can be configured to automatically manage resources (like Azure Functions, Kubernetes, and Azure App Services). Also: do you need horizontal or vertical scaling?

And, talking about the integrity of the system, how do you ensure that operations that were ongoing when the fatal error occurred can be completed?

One possible solution is to use a database table to keep track of the status of each operation, so that when the application restarts, it first completes pending operations, and then starts working on new operations.

A practical approach to address the Error Management Trio

There are too many errors to manage and too much effort to cover everything!

How can we cover everything? Well, it's impossible: for every action we take to prevent an error, a new one may occur.

Let's jump back to the example we saw for handling validation errors (using a new service that tries to fix the message). What if the ValidationFixesManager service is down or the message queue is unreachable? We tried to solve a problem, but we ended up with two more to be managed!

Let me introduce a practical approach to help you decide what needs to be addressed.

Step 1: list all the errors you can think of. Create a table to list all the possible errors that you expect to happen.

You can add a column to describe the category the error falls into, as well as a Probability and Impact on the system column with a value (in this example, Low, Medium and High) that represents the probability that this error occurs and the impact it has on the overall application.

Problem	Category	Probability	Impact on the system
Invalid message from queue	Data Validation	Medium	High
Invalid user data on DB	Data Validation	Low	Medium
Missing user on DB	Data Validation	Low	Low
API not reachable	Transient	High	High
DB not reachable	Transient	Low	High
File system corrupted	Fatal	Low	High
CPU limit reached	Fatal	Medium	High

From here, you can pick the most urgent elements to be addressed.

Step 2: evaluate alternatives. Every error can be addressed in several ways (ignoring the error IS a valid alternative!). Take some time to explore all the alternatives.

Again, a table can be a good companion for this step. You can describe, for example:
the effort required to solve the error (Low, Medium, High)
the positive and negative consequences in terms (also) of quality attributes (aka: "-ilities"). Maybe a solution works fine for data integrity but has a negative impact on maintainability.

Step 3: use ADRs to describe how (and why) you will handle that specific error.

Take your time to thoroughly describe, using ADR documents, the problems you are trying to solve, the solutions taken into consideration, and the final choice.

Having everything written down in a shared file is fundamental for ensuring that, in the future, the present choices and necessities are taken into account, before saying "meh, that's garbage!"

Wrapping up

This article highlights the importance of error management and the fact that even if we all want to avoid and prevent errors in our systems, we still have to take care of them and plan according to our needs.

C# Tip: IEnumerable vs ICollection, and why it matters

Davide Bellone — Tue, 15 Oct 2024 00:00:00 +0000

Defining the best return type is crucial to creating a shared library whose behaviour is totally under your control.

You should give the consumers of your libraries just the right amount of freedom to integrate and use the classes and structures you have defined.

That's why it is important to know the differences between interfaces like IEnumerable<T> and ICollection<T>: these interfaces are often used together but have totally different meanings.

IEnumerable: loop through the items in the collection

Suppose that IAmazingInterface is an interface you expose so that clients can interact with it without knowing the internal behaviour.

You have defined it this way:

public interface IAmazingInterface
{
    IEnumerable<int> GetNumbers(int[] numbers);
}

As you can see, the GetNumbers returns an IEnumerable<int>: this means that (unless they do some particular tricks like using reflection), clients will only be able to loop through the collection of items.

Clients don't know that, behind the scenes, AmazingClass uses a custom class MySpecificEnumberable.

public class AmazingClass: IAmazingInterface
{
    public IEnumerable<int> GetNumbers(int[] numbers)
        => new MySpecificEnumberable(numbers);
}

MySpecificEnumberable is a custom class whose purpose is to store the initial values in a sorted way. It implements IEnumerable<int>, so the only operations you have to support are the two implementations of GetEnumerator() - pay attention to the returned data type!

public class MySpecificEnumberable : IEnumerable<int>
{
    private readonly int[] _numbers;

    public MySpecificEnumberable(int[] numbers)
    {
        _numbers = numbers.OrderBy(_ => _).ToArray();
    }

    public IEnumerator<int> GetEnumerator()
    {
        foreach (var number in _numbers)
        {
            yield return number;
        }
    }

    IEnumerator IEnumerable.GetEnumerator()
        => _numbers.GetEnumerator();
}

Clients will then be able to loop all the items in the collection:

IAmazingInterface something = new AmazingClass();
var numbers = something.GetNumbers([1, 5, 6, 9, 8, 7, 3]);

foreach (var number in numbers)
{
    Console.WriteLine(number);
}

But you cannot add or remove items from it.

ICollection: list, add, and remove items

As we saw, IEnumerable<T> only allows you to loop through all the elements. However, you cannot add or remove items from an IEnumerable<T>.

To do so, you need something that implements ICollection<T>, like the following class (I haven't implemented any of these methods: I want you to focus on the operations provided, not on the implementation details).

class MySpecificCollection : ICollection<int>
{
    public int Count => throw new NotImplementedException();

    public bool IsReadOnly => throw new NotImplementedException();

    public void Add(int item) => throw new NotImplementedException();

    public void Clear() => throw new NotImplementedException();

    public bool Contains(int item) => throw new NotImplementedException();

    public void CopyTo(int[] array, int arrayIndex) => throw new NotImplementedException();

    public IEnumerator<int> GetEnumerator() => throw new NotImplementedException();

    public bool Remove(int item) => throw new NotImplementedException();

    IEnumerator IEnumerable.GetEnumerator() => throw new NotImplementedException();
}

ICollection<T> is a subtype of IEnumerable<T>, so everything we said before is still valid.

However, having a class that implements ICollection<T> gives you full control over how items can be added or removed from the collection, allowing you to define custom behaviour. For instance, you can define that the Add method adds an integer only if it's an odd number.

Why knowing the difference actually matters

Classes and interfaces are meant to be used. If you are like me, you work on both the creation of the class and its consumption.

So, if an interface must return a sequence of items, you most probably use the List shortcut: define the return type of the method as List<Item>, and then use it, regardless of having it looped through or having the consumer add items to the sequence.

// in the interface
public interface ISomething
{
    List<Item> PerformSomething(int[] numbers);
}


// in the consumer class
ISomething instance = //omitted
List<Item> myItems = instance.PerformSomething([2, 3, 4, 5]);

Everything works fine, but it works because we are in control of both the definition and the consumer.

What if you have to expose the library to something outside your control?

You have to consider two elements:

consumers should not be able to tamper with your internal implementation (for example, by adding items when they are not supposed to);
you should be able to change the internal implementation as you wish without breaking changes.

So, if you want your users to just enumerate the items within a collection, you may start this way:

// in the interface
public interface ISomething
{
    IEnumerable<Item> PerformSomething(int[] numbers);
}

// in the implementation

IEnumerable<Item> PerformSomething(int[] numbers)
{
    return numbers.Select(x => new Item(x)).ToList();
}

// in the consumer class

ISomething instance = //omitted
IEnumerable<Item> myItems = instance.PerformSomething([2, 3, 4, 5]);

Then, when the time comes, you can change the internal implementation of PerformSomething with a more custom class:

// custom IEnumerable definition
public class MyCustomEnumberable : IEnumerable<Item> { /*omitted*/ }

// in the interface
IEnumerable<Item> PerformSomething(int[] numbers)
{
    MyCustomEnumberable customEnumerable = new MyCustomEnumberable();
    customEnumerable.DoSomething(numbers);
    return customEnumerable;
}

And the consumer will not notice the difference. Again, unless they try to use tricks to tamper with your code!

This article first appeared on Code4IT 🐧

Wrapping up

While understanding the differences between IEnumerable and ICollection is trivial, understanding why you should care about them is not.

I hope this article helped you understand that yeah, you can take the easy way and return everywhere a List, but it's a choice that you cannot always apply to a project, and that probably will make breaking changes more frequent in the long run.

How to use IHttpClientFactory and WireMock.NET together using Moq

Davide Bellone — Tue, 01 Oct 2024 00:00:00 +0000

Testing the integration with external HTTP clients can be a cumbersome task, but most of the time, it is necessary to ensure that a method is able to perform correct operations - not only sending the right information but also ensuring that we are able to read the content returned from the called API.

Instead of spinning up a real server (even if in the local environment), we can simulate a connection to a mock server. A good library for creating temporary in-memory servers is WireMock.NET.

Many articles I read online focus on creating a simple HttpClient, using WireMock.NET to drive its behaviour. In this article, we are going to take a little step further: we are going to use WireMock.NET to handle HttpClients generated, using Moq, via IHttpClientFactory.

Explaining the dummy class used for the examples

As per every practical article, we must start with a dummy example.

For the sake of this article, I've created a dummy class with a single method that calls an external API to retrieve details of a book and then reads the returned content. If the call is successful, the method returns an instance of Book; otherwise, it throws a BookServiceException exception.

Just for completeness, here's the Book class:

public class Book
{
    public int Id { get; set; }
    public string Title { get; set; }
}

And here's the BookServiceException definition:

[Serializable]
public class BookServiceException: Exception
{
    public BookServiceException(string message, Exception inner) : base(message, inner) { }
    protected BookServiceException(
      System.Runtime.Serialization.SerializationInfo info,
      System.Runtime.Serialization.StreamingContext context) : base(info, context) { }
}

Finally, we have our main class:

public class BookService
{
    private readonly IHttpClientFactory _httpClientFactory;

    public BookService(IHttpClientFactory httpClientFactory)
    {
        _httpClientFactory = httpClientFactory;
    }

    public async Task<Book> GetBookById(int id)
    {

        string url = $"/api/books/{id}";
        HttpClient httpClient = _httpClientFactory.CreateClient("books_client");

        try
        {
                Book? book = await httpClient.GetFromJsonAsync<Book>(url);
                return book;
        }
        catch (Exception ex)
        {
                throw new BookServiceException($"There was an error while getting info about the book {id}", ex);
        }
    }
}

There are just two things to notice:

We are injecting an instance of IHttpClientFactory into the constructor.
We are generating an instance of HttpClient by passing a name to the CreateClient method of IHttpClientFactory.

Now that we have our cards on the table, we can start!

WireMock.NET, a library to simulate HTTP calls

WireMock is an open-source platform you can install locally to create a real mock server. You can even create a cloud environment to generate and test HTTP endpoints.

However, for this article we are interested in the NuGet package that takes inspiration from the WireMock project, allowing .NET developers to generate disposable in-memory servers: WireMock.NET.

To add the library, you must add the WireMock.NET NuGet package to your project, for example using dotnet add package WireMock.Net.

Once the package is ready, you can generate a test server in your Unit Tests class:

public class WireMockTests
{
    private WireMockServer _server;

    [OneTimeSetUp]
    public void OneTimeSetUp()
    {
        _server = WireMockServer.Start();
    }

    [SetUp]
    public void Setup()
    {
        _server.Reset();
    }

    [OneTimeTearDown]
    public void OneTimeTearDown()
    {
        _server.Stop();
    }
}

You can instantiate a new instance of WireMockServer in the OneTimeSetUp step, store it in a private field, and make it accessible to every test in the test class.

Before each test run, you can reset the internal status of the mock server by running the Reset() method. I'd suggest you reset the server to avoid unintentional internal status, but it all depends on what you want to do with the server instance.

Finally, remember to free up resources by calling the Stop() method in the OneTimeTearDown phase (but not during the TearDown phase: you still need the server to be on while running your tests!).

Basic configuration of HTTP requests and responses with WireMock.NET

The basic structure of the definition of a mock response using WireMock.NET is made of two parts:

Within the Given method, you define the HTTP Verb and URL path whose response is going to be mocked.
Using RespondWith, you define what the mock server must return when the endpoint specified in the Given step is called.

In the next example, you can see that the _server instance (the one I instantiated in the OneTimeSetUp phase, remember?) must return a specific body (responseBody) and the 200 HTTP Status Code when the /api/books/42 endpoint is called.

string responseBody = @"
{
""Id"": 42,
""Title"": ""Life, the Universe and Everything""
}
";

_server
 .Given(Request.Create().WithPath("/api/books/42").UsingGet())
 .RespondWith(
  Response.Create()
 .WithStatusCode(200)
 .WithBody(responseBody)
 );

Similarly, you can define that an endpoint will return an error by changing its status code:

_server
.Given(Request.Create().WithPath("/api/books/42").UsingGet())
.RespondWith(
  Response.Create()
 .WithStatusCode(404)
);

All in all, both the request and the response are highly customizable: you can add HTTP Headers, delays, cookies, and much more.

Look closely; there's one part that is missing: What is the full URL? We have declared only the path (/api/books/42) but have no info about the hostname and the port used to communicate.

How to integrate WireMock.NET with a Moq-driven IHttpClientFactory

In order to have WireMock.NET react to an HTTP call, we have to call the exact URL - even the hostname and port must match. But when we create a mocked HttpClient - like we did in this article - we don't have a real hostname. So, how can we have WireMock.NET and HttpClient work together?

The answer is easy: since WireMockServer.Start() automatically picks a free port on your localhost, you don't have to guess the port number, but you can reference the current instance of _server.

Once the WireMockServer is created, internally it contains the reference to one or more URLs it will use to listen for HTTP requests, intercepting the calls and replying in place of a real server. You can then use one of these ports to configure the HttpClient generated by the HttpClientFactory.

Let's see the code:

[Test]
public async Task GetBookById_Should_HandleBadRequests()
{
    string baseUrl = _server.Url;

    HttpClient myHttpClient = new HttpClient() { BaseAddress = new Uri(baseUrl) };

    Mock<IHttpClientFactory> mockFactory = new Mock<IHttpClientFactory>();
    mockFactory.Setup(_ => _.CreateClient("books_client")).Returns(myHttpClient);

    _server
        .Given(Request.Create().WithPath("/api/books/42").UsingGet())
        .RespondWith(
            Response.Create()
            .WithStatusCode(404)
        );

    BookService service = new BookService(mockFactory.Object);

    Assert.CatchAsync<BookServiceException>(() => service.GetBookById(42));
}

First we access the base URL used by the mock server by accessing _server.Url.

We use that URL as a base address for the newly created instance of HttpClient.

Then, we create a mock of IHttpClientFactory and configure it to return the local instance of HttpClient whenever we call the CreateClient method with the specified name.

In the meantime, we define how the mock server must behave when an HTTP call to the specified path is intercepted.

Finally, we can pass the instance of the mock IHttpClientFactory to the BookService.

So, the key part to remember is that you can simply access the Url property (or, if you have configured it to handle many URLs, you can access the Urls property, which is an array of strings).

Let WireMock.NET create the HttpClient for you

As suggested by Stef in the comments to this post, there's actually another way to generate the HttpClient with the correct URL: let WireMock.NET do it for you.

Instead of doing

string baseUrl = _server.Url;

HttpClient myHttpClient = new HttpClient() { BaseAddress = new Uri(baseUrl) };

you can simplify the process by calling the CreateClient method:

HttpClient myHttpClient = _server.CreateClient();

Of course, you will still have to pass the instance to the mock of IHttpClientFactory.

Wrapping up

In this article, we almost skipped all the basic stuff about WireMock.NET and tried to go straight to the point of integrating WireMock.NET with IHttpClientFactory.

There are lots of articles out there that explain how to use WireMock.NET - just remember that WireMock and WireMock.NET are not the same thing!

Ciao!

Davide's Code and Architecture Notes - Practical creation of C4 Model diagrams with Structurizr

Davide Bellone — Tue, 17 Sep 2024 00:00:00 +0000

The C4 Model is a well-known way of representing software architectures, describing the different parts via code in a hierarchical way: you start from the high-level view and gradually describe the details of each component and their interactions.

I'm sure you've already heard of it. But have you ever used it in an actual project?

I have used the C4 Model to describe the architecture of a - quite complex - project, and I decided to use Structurizr as a tool to generate such diagrams.

In this article, I will share my experience with it, as well as some practical tips for using it. I have used Windows 11, but almost everything I share here can be used with other Operating Systems as well.

An overview of the C4 Model

The C4 Model is a framework, created by Simon Brown, used in software architecture to provide a clear and structured way of describing complex software systems.

Generating diagrams with different levels of abstraction provides users with various ways to look at how components are organized, how they communicate, and so on.

It consists of four levels of abstraction: Context, Containers, Components, and Code, each serving a distinct purpose.

Context: a high-level view, with external dependencies

The Context level is the highest level of the model and provides a full-system view, showing how the software system interacts with external entities such as users, systems, and external services.

By looking at this level, readers can see the external parts communicating with the software system.

In general, here is where you want to describe the parts that are not under your control: if you store data in a database managed by somebody else, you can show it here. If you manage the database (even if it is in the cloud - as long as you have some control over it), you should list it at a lower level, like Containers.

Containers: the internal architecture's main modules

The Container level breaks down the system into its major modules, which are typically applications, data stores, microservices, etc.

This level outlines the high-level technology choices and how these containers interact with one another.

Here, for example, you can describe all your microservices, listing the dependencies, the frameworks used to implement them, and so on.

Components: the main parts within a Container

The Component level describes the various modules and parts that are part of the parent Container.

These components are detailed in a way that shows their responsibilities, interactions, and how they work together to fulfil the container's purpose.

In the case of an application based on .NET, you can think of components as the different class libraries within the solution. However, this level works better if you think of the logical separation of the components, not the physical separation.

Code: the low-level view of the code

The most granular level of the C4 Model, the Code level, is often optional but, in some specific cases, it can be incredibly informative.

It provides the implementation details of the system's components, often visualized through class or interface diagrams that show the code structure and dependencies.

From my experience, since the code changes frequently, the Code level risks being outdated; and since wrong info is worse than no info, I generally choose not to include this level.

What is (and what is not) the C4 Model

The C4 Model is particularly beneficial for several reasons. It helps create a common language for team members to discuss architecture, facilitates the onboarding of new developers by providing them with a clear system map, and helps in risk identification and threat modelling.

Moreover, since it's based on abstractions, it's flexible enough to be used at various stages of development, from initial design to documenting existing systems.

It's important to remember that C4 Model is a way of describing software. But it's not a Language, nor a Tool.

To generate a C4 Model, you can use many tools, like Structurizr (created by Simon Brown, the creator of the C4 Model). Structurizr has its own DSL (Domain Specific Language), but nothing stops you from creating C4 Model diagrams using any tool - even a simple handwritten sketch can be acceptable.

Let's create the diagrams for a realistic application: a Web UI that shows the latest articles from a website.

This project is composed of two main parts:

A background job (something like an Azure Function) that accesses an RSS feed and stores the published articles' data on a DB.
A web UI, accessed by users, that reads the info of the articles from the DB and shows them on screen.

Step-by-step C4 diagrams with Structurizr

As we have seen before, the C4 Model is not a language or tool but a type of visual representation.

In this article, we will use Structurizr. To generate diagrams with it, we have to use its specific syntax and have access to it (either in the cloud or locally).

I have my project saved in a Desktop folder. Alongside the production code, I have a folder named "documentation" that stores everything related to - guess what? - docs. Within that folder, I have a "c4-diagrams" directory containing the diagrams and the C4 Model.

File structure for Structurizr

Every "project" is described by its own workspace, which contains everything needed to describe the different levels and modules.

A workspace is nothing but a text file with the .dsl extension. You can create a workspace.dsl file in any directory (though I suggest you do that in a specific "documentation" folder).

Since it's a plain text file, you can add it to source control - this simple tip allows your colleagues to collaborate with the diagram creation.

To start with a very basic example, create a workspace node within the workspace.dsl file.

workspace {
    model {
        mainSystem = softwareSystem "Latest Articles software system" {
        }
    }
}

This workspace contains a model node, that is used to list all the components and modules that are part of the workspace.

In this case, we have only one item: mainSystem, which is an object of type softwareSystem, whose label is "Latest Articles software system".

We will add some real items soon.

2 ways to install Structurizr locally (on Windows 11)

You can use Structurizr on the cloud or locally. I generally prefer having Structurizr Lite installed on my local machine so that I can generate the diagrams locally and, when necessary, modify them before saving the changes.

To use it, have two ways:

Install it as a Java application (it requires Java 17+) running on a UNIX-based system: you must be able to run a Bash script to make it work;
Install it via Docker: pull the Docker image and run the application as a Docker container.

Since I work with Windows, I prefer using Docker.

To pull the image, you have to run the following command.

docker pull structurizr/lite

If you are an absolute beginner with Docker, I published a short article that explains the main concepts without all the fuzz around it.

Run Structurizr locally with Docker

Once you have pulled its Docker image, you can run it specifying the path to the Workspace file:

docker run -it --rm -p 8080:8080 -v C:/Users/d.bellone/Desktop/ProvaStructurizr/documentation/c4-diagrams:/usr/local/structurizr structurizr/lite

There are some important things to notice:

you have to use the full path to the dsl file.
the path separator must be /.
if the workspace file does not exist, it will be created automatically with a default template.

Of course, replace the local path with your own.

Now, if everything goes well, you will be able to see the empty diagram on localhost:8080.

Set up the Context elements

The first level of the C4 Model is the Context: here, you list all the top-level parts that are involved with the software systems, like external dependencies and users.

First, we have the user who interacts with our system. We can call it "Reader".

Then we have the RSS feed that we are integrating, which we can call "RSS Feed".

workspace {
    model {
        reader = person "Reader"
        mainSystem = softwareSystem "Latest Articles software system"
        rssFeed = softwareSystem "RSS Feed"
    }
}

Now we can see the result on Structurizr:

Please note that the order in which the elements appear is the same as the order in which the elements are listed in the model node.

Also, note that three parts characterize each element:

the variable name, reader, that allows us to reference this element in other parts of the diagram;
the type of element, person;
the label associated with the element, Reader, that is shown as box title.

Describe Containers and their interactions

The Containers level describes the different modules of the software system.

In our specific example, we have the following modules:

The Web Application, accessed by the user;
The "FetchJob" job application, that reads the content from the RSS Feed;
The internal Database, that contains the data stored by the FetchJob and read by the Web Application;

All these items are part of the "Latest Articles software system", so they need to be included as children of that node:

workspace {
    model {
        reader = person "Reader"
        rssFeed = softwareSystem "RSS Feed"
        mainSystem = softwareSystem "Latest Articles software system" {
            webapplication = container "Web Application" {
            reader -> this "Reads Articles info"
            }
            fetchJob = container "FetchJob" {
                this -> rssFeed "Fetches RSS Feed"
            }
            database = container "Internal Database" {
                webapplication -> this "Reads articles info"
                fetchJob -> this "Stores articles info"
            }
        }
    }
}

Notice that you can use the this keyword to refer to the active element.

Another important part to consider is that you cannot reference an element that hasn't already been declared. That's why, compared with the previous example, I had to move the rssFeed item before the mainSystem.

Now that we have all the components and their interactions, we can see that the Context layer also shows the inbound and outbound interactions with the external systems.

If we look into the Components layer, we can see how the different components interact with each other and with the external sources.

Even with just these two levels, we have enough info to understand how the system behaves and what the main moving parts are.

Define Components

Each container is made of one or more components.

In our example, the Web Application is made of two components: the Web UI and the Backend Application, which interacts with the database.

workspace {
    model {
        reader = person "Reader"
        rssFeed = softwareSystem "RSS Feed"
        mainSystem = softwareSystem "Latest Articles software system" {
            webapplication = container "Web Application" {
                ui = component "Web UI" {
                    reader -> this "Reads Articles info"
                }
                backend = component "Backend" {
                    ui -> this "Asks for data"
                }
            }
            fetchJob = container "FetchJob" {
                this -> rssFeed "Fetches RSS Feed"
            }
            database = container "Internal Database"{
            backend -> this "Reads articles info"
            fetchJob -> this "Stores articles info"
            }
        }
    }
}

We now have the UI and Backend components. Of course, since they describe the components within the web application in better detail, they replace the content within the webapplication node.

Also, the backend node is now referenced within the database container.

Code level

The Code level is used so rarely that the Structurizr DSL does not even include it.

However, you can use other tools to generate the code diagrams and then reference those diagrams in the C4 Model.

Practical tips for working with Structurizr

Now that we have seen how to create the basic structure of a C4 Model with Structurizer, let's have a look at some practical tips that I found useful when describing the application I was working on. Of course, if you know some others, let me know in the comments section!

Store all the documentation in a single folder: the more scattered the documentation across your systems, the harder it becomes to find what you are looking for and remember to keep everything up-to-date.
Remember to follow the DSL grammar: while the C4 Model is an abstract way to represent a software system, if you want to use Structurizr to generate such type of models, you have to follow its DSL. It's a strict grammar, with some rules you'll get to know while working on it (like the fact that you cannot reference an item before it has been referenced).
Use verbs in the active form: instead of "Is called by", use "Calls", following the arrow direction.
Separate by logical meaning, not physical division: using as an example a .NET application, even if two functionalities (aka: Modules) are part of the same Class Library, you should represent them as separate entities.
Use tags and colours to mark external and internal components: each element can be represented with a specific colour and can be tagged with custom values. Make use of these capabilities to help readers identify internal and external components.
Use themes to customize how the diagram is rendered: Structurizr allows you to apply themes to your diagram to change how the rendering looks like. For example, you can configure it to use Azure icons.
Save your diagrams in GIT: you want to keep track of the changes to your diagrams, ensuring that the description matches the actual structure of the system.
Update the .gitignore file: even if you just update the workspace.dsl file, Structurizr creates some temporary files (metadata, thumbnails, and so on), as you can see in the screenshot below. These files are stored in the .structurizr folder. So, remember to add the .structuriz folder to your gitignore file.

Split the diagram into different parts, and join them using "includes": when the application grows in a way that it becomes difficult to read and manage, you can create separate sub-diagrams and join them using the includes operator. For example, if you have a solution with 15 projects, you can create one diagram inside each of the 15 projects and join them all in a root diagram.
Export the diagrams to other formats: Structurizr is not the only tool you can use to analyze the structure of your system. You can export the diagram in different formats using Mermaid or Ilograph.
Install the Structurizr extension on VSCode: since Structurizr DSL is a custom language, it is not natively supported by the most popular IDEs. To have a nice syntax highlighting, you can install the Structurizr extension for VSCode, as seen below.

Wrapping up

It's not necessary to use Structurizr to generate such C4 Model diagrams. However, it's probably one of the most complete tools you can find online.

Remember, you should describe the architecture to the best level of detail: not too many details (or you'll lose time describing stuff with little to no value) nor too few (or you won't get the sense of the architecture).

C# Tip: ObservableCollection - a data type to intercept changes to the collection

Davide Bellone — Tue, 27 Aug 2024 00:00:00 +0000

Imagine you need a way to raise events whenever an item is added or removed from a collection.

Instead of building a new class from scratch, you can use ObservableCollection<T> to store items, raise events, and act when the internal state of the collection changes.

In this article, we will learn how to use ObservableCollection<T>, an out-of-the-box collection available in .NET.

Introducing the ObservableCollection type

ObservableCollection<T> is a generic collection coming from the System.Collections.ObjectModel namespace.

It allows the most common operations, such as Add<T>(T item) and Remove<T>(T item), as you can expect from most of the collections in .NET.

Moreover, it implements two interfaces:

INotifyCollectionChanged can be used to raise events when the internal collection is changed.
INotifyPropertyChanged can be used to raise events when one of the properties of the changes.

Let's see a simple example of the usage:

var collection = new ObservableCollection<string>();

collection.Add("Mario");
collection.Add("Luigi");
collection.Add("Peach");
collection.Add("Bowser");

collection.Remove("Luigi");

collection.Add("Waluigi");

_ = collection.Contains("Peach");

collection.Move(1, 2);

As you can see, we can do all the basic operations: add, remove, swap items (with the Move method), and check if the collection contains a specific value.

You can simplify the initialization by passing a collection in the constructor:

 var collection = new ObservableCollection<string>(new string[] { "Mario", "Luigi", "Peach" });

 collection.Add("Bowser");

 collection.Remove("Luigi");

 collection.Add("Waluigi");

 _ = collection.Contains("Peach");

 collection.Move(1, 2);

How to intercept changes to the underlying collection

As we said, this data type implements INotifyCollectionChanged. Thanks to this interface, we can add event handlers to the CollectionChanged event and see what happens.

var collection = new ObservableCollection<string>(new string[] { "Mario", "Luigi", "Peach" });
collection.CollectionChanged += WhenCollectionChanges;

Console.WriteLine("Adding Bowser...");
collection.Add("Bowser");
Console.WriteLine("");


Console.WriteLine("Removing Luigi...");
collection.Remove("Luigi");
Console.WriteLine("");

Console.WriteLine("Adding Waluigi...");
collection.Add("Waluigi");
Console.WriteLine("");

Console.WriteLine("Searching for Peach...");
var containsPeach = collection.Contains("Peach");
Console.WriteLine("");

Console.WriteLine("Swapping items...");
collection.Move(1, 2);

The WhenCollectionChanges method accepts a NotifyCollectionChangedEventArgs that gives you info about the intercepted changes:

private void WhenCollectionChanges(object? sender, NotifyCollectionChangedEventArgs e)
{
    var allItems = ((IEnumerable<object>)sender)?.Cast<string>().ToArray() ?? new string[] { "<empty>" };
    Console.WriteLine($"> Currently, the collection is {string.Join(',', allItems)}");

    Console.WriteLine($"> The operation is {e.Action}");

    var previousItems = e.OldItems?.Cast<string>()?.ToArray() ?? new string[] { "<empty>" };
    Console.WriteLine($"> Before the operation it was {string.Join(',', previousItems)}");


    var currentItems = e.NewItems?.Cast<string>()?.ToArray() ?? new string[] { "<empty>" };
    Console.WriteLine($"> Now, it is {string.Join(',', currentItems)}");
}

Every time an operation occurs, we write some logs.

The result is:

Adding Bowser...
> Currently, the collection is Mario,Luigi,Peach,Bowser
> The operation is Add
> Before the operation it was <empty>
> Now, it is Bowser

Removing Luigi...
> Currently, the collection is Mario,Peach,Bowser
> The operation is Remove
> Before the operation it was Luigi
> Now, it is <empty>

Adding Waluigi...
> Currently, the collection is Mario,Peach,Bowser,Waluigi
> The operation is Add
> Before the operation it was <empty>
> Now, it is Waluigi

Searching for Peach...

Swapping items...
> Currently, the collection is Mario,Bowser,Peach,Waluigi
> The operation is Move
> Before the operation it was Peach
> Now, it is Peach

Notice a few points:

the sender property holds the current items in the collection. It's an object?, so you have to cast it to another type to use it.
the NotifyCollectionChangedEventArgs has different meanings depending on the operation:
- when adding a value, OldItems is null and NewItems contains the items added during the operation;
- when removing an item, OldItems contains the value just removed, and NewItems is null.
- when swapping two items, both OldItems and NewItems contain the item you are moving.

How to intercept when a collection property has changed

To execute events when a property changes, we need to add a delegate to the PropertyChanged event. However, it's not available directly on the ObservableCollection type: you first have to cast it to an INotifyPropertyChanged:

var collection = new ObservableCollection<string>(new string[] { "Mario", "Luigi", "Peach" });
(collection as INotifyPropertyChanged).PropertyChanged += WhenPropertyChanges;

Console.WriteLine("Adding Bowser...");
collection.Add("Bowser");
Console.WriteLine("");


Console.WriteLine("Removing Luigi...");
collection.Remove("Luigi");
Console.WriteLine("");

Console.WriteLine("Adding Waluigi...");
collection.Add("Waluigi");
Console.WriteLine("");

Console.WriteLine("Searching for Peach...");
var containsPeach = collection.Contains("Peach");
Console.WriteLine("");

Console.WriteLine("Swapping items...");
collection.Move(1, 2);

We can now specify the WhenPropertyChanges method as such:

private void WhenPropertyChanges(object? sender, PropertyChangedEventArgs e)
{
    var allItems = ((IEnumerable<object>)sender)?.Cast<string>().ToArray() ?? new string[] { "<empty>" };
    Console.WriteLine($"> Currently, the collection is {string.Join(',', allItems)}");
    Console.WriteLine($"> Property {e.PropertyName} has changed");
}

As you can see, we have again the sender parameter that contains the collection of items.

Then, we have a parameter of type PropertyChangedEventArgs that we can use to get the name of the property that has changed, using the PropertyName property.

Let's run it.

Adding Bowser...
> Currently, the collection is Mario,Luigi,Peach,Bowser
> Property Count has changed
> Currently, the collection is Mario,Luigi,Peach,Bowser
> Property Item[] has changed

Removing Luigi...
> Currently, the collection is Mario,Peach,Bowser
> Property Count has changed
> Currently, the collection is Mario,Peach,Bowser
> Property Item[] has changed

Adding Waluigi...
> Currently, the collection is Mario,Peach,Bowser,Waluigi
> Property Count has changed
> Currently, the collection is Mario,Peach,Bowser,Waluigi
> Property Item[] has changed

Searching for Peach...

Swapping items...
> Currently, the collection is Mario,Bowser,Peach,Waluigi
> Property Item[] has changed

As you can see, for every add/remove operation, we have two events raised: one to say that the Count has changed, and one to say that the internal Item[] is changed.

However, notice what happens in the Swapping section: since you just change the order of the items, the Count property does not change.

This article first appeared on Code4IT 🐧

Final words

As you probably noticed, events are fired after the collection has been initialized. Clearly, it considers the items passed in the constructor as the initial state, and all the subsequent operations that mutate the state can raise events.

Also, notice that events are fired only if the reference to the value changes. If the collection holds more complex classes, like:

public class User
{
    public string Name { get; set; }
}

No event is fired if you change the value of the Name property of an object already part of the collection:

var me = new User { Name = "Davide" };
var collection = new ObservableCollection<User>(new User[] { me });

collection.CollectionChanged += WhenCollectionChanges;
(collection as INotifyPropertyChanged).PropertyChanged += WhenPropertyChanges;

me.Name = "Updated"; // It does not fire any event!

Notice that ObservableCollection<T> is not thread-safe! You can find an interesting article by Gérald Barré (aka Meziantou) where he explains a thread-safe version of ObservableCollection<T> he created. Check it out!

As always, I suggest exploring the language and toying with the parameters, properties, data types, etc.

You'll find lots of exciting things that may come in handy.

I hope you enjoyed this article! Let's keep in touch on Twitter or LinkedIn! 🤜🤛

Happy coding!

🐧

C# Tip: IFormattable interface, to define different string formats for the same object

Davide Bellone — Tue, 27 Aug 2024 00:00:00 +0000

Even when the internal data is the same, sometimes you can represent it in different ways. Think of the DateTime structure: by using different modifiers, you can represent the same date in different formats.

DateTime dt = new DateTime(2024, 1, 1, 8, 53, 14);

Console.WriteLine(dt.ToString("yyyy-MM-dddd")); //2024-01-Monday
Console.WriteLine(dt.ToString("Y")); //January 2024

Same datetime, different formats.

You can further customise it by adding the CultureInfo:

System.Globalization.CultureInfo italianCulture = new System.Globalization.CultureInfo("it-IT");

Console.WriteLine(dt.ToString("yyyy-MM-dddd", italianCulture)); //2024-01-lunedì
Console.WriteLine(dt.ToString("Y", italianCulture)); //gennaio 2024

Now, how can we use this behaviour in our custom classes?

IFormattable interface for custom ToString definition

Take this simple POCO class:

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public DateTime BirthDate { get; set; }
}

We can make this class implement the IFormattable interface so that we can define and use the advanced ToString:

public class Person : IFormattable
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public DateTime BirthDate { get; set; }

    public string ToString(string? format, IFormatProvider? formatProvider)
    {
        // Here, you define how to work with different formats
    }
}

Now, we can define the different formats. Since I like to keep the available formats close to the main class, I added a nested class that only exposes the names of the formats.

public class Person : IFormattable
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public DateTime BirthDate { get; set; }

    public string ToString(string? format, IFormatProvider? formatProvider)
    {
        // Here, you define how to work with different formats
    }

    public static class StringFormats
    {
        public const string FirstAndLastName = "FL";
        public const string Mini = "Mini";
        public const string Full = "Full";
    }
}

Finally, we can implement the ToString(string? format, IFormatProvider? formatProvider) method, taking care of all the different formats we support (remember to handle the case when the format is not recognised!)

public string ToString(string? format, IFormatProvider? formatProvider)
{
    switch (format)
    {
        case StringFormats.FirstAndLastName:
            return string.Format("{0} {1}", FirstName, LastName);
        case StringFormats.Full:
        {
            FormattableString fs = $"{FirstName} {LastName} ({BirthDate:D})";
            return fs.ToString(formatProvider);
        }
        case StringFormats.Mini:
            return $"{FirstName.Substring(0, 1)}.{LastName.Substring(0, 1)}";
        default:
            return this.ToString();
    }
}

A few things to notice:

I use a switch statement based on the values defined in the StringFormats subclass. If the format is empty or unrecognised, this method returns the default implementation of ToString.
You can use whichever way to generate a string, like string interpolation, or more complex ways;
In the StringFormats.Full branch, I stored the string format in a FormattableString instance to apply the input formatProvider to the final result.

Getting a custom string representation of an object

We can try the different formatting options now that we have implemented them all.

Look at how the behaviour changes based on the formatting and input culture (Hint: venerdí is the Italian for Friday.).

Person person = new Person
{
    FirstName = "Albert",
    LastName = "Einstein",
    BirthDate = new DateTime(1879, 3, 14)
};

System.Globalization.CultureInfo italianCulture = new System.Globalization.CultureInfo("it-IT");

Console.WriteLine(person.ToString(Person.StringFormats.FirstAndLastName, italianCulture)); //Albert Einstein

Console.WriteLine(person.ToString(Person.StringFormats.Mini, italianCulture)); //A.E

Console.WriteLine(person.ToString(Person.StringFormats.Full, italianCulture)); //Albert Einstein (venerdì 14 marzo 1879)

Console.WriteLine(person.ToString(Person.StringFormats.Full, null)); //Albert Einstein (Friday, March 14, 1879)

Console.WriteLine(person.ToString(Person.StringFormats.Full, CultureInfo.InvariantCulture)); //Albert Einstein (Friday, 14 March 1879)

Console.WriteLine(person.ToString("INVALID FORMAT", CultureInfo.InvariantCulture)); //Scripts.General.IFormattableTest+Person

Console.WriteLine(string.Format("I am {0:Mini}", person)); //I am A.E

Console.WriteLine($"I am not {person:Full}"); //I am not Albert Einstein (Friday, March 14, 1879)

Not only that, but now the result can also depend on the Culture related to the current thread:

using (new TemporaryThreadCulture(italianCulture))
{
    Console.WriteLine(person.ToString(Person.StringFormats.Full, CultureInfo.CurrentCulture)); // Albert Einstein (venerdì 14 marzo 1879)
}

using (new TemporaryThreadCulture(germanCulture))
{
    Console.WriteLine(person.ToString(Person.StringFormats.Full, CultureInfo.CurrentCulture)); //Albert Einstein (Freitag, 14. März 1879)
}

(note: TemporaryThreadCulture is a custom class that I explained in a previous article - see below)

Wrapping up

I hope you enjoyed this article! Let's keep in touch on Twitter or LinkedIn! 🤜🤛

Happy coding!

🐧

How to create custom snippets in Visual Studio 2022

Davide Bellone — Thu, 22 Aug 2024 00:00:00 +0000

One of the best tricks to boost productivity is knowing your tools.

I'm pretty sure you've already used some predefined snippets in Visual Studio. For example, when you type ctor and hit Tab twice, VS automatically creates an empty constructor for the current class.

In this article, we will learn how to create custom snippets: in particular, we will design a snippet that automatically creates a C# Unit Test method with some placeholders and predefined Arrange-Act-Assert blocks.

Snippet Designer: a Visual Studio 2022 extension to add a UI to your placeholders

Snippets are defined in XML-like files with .snippet extension. But we all know that working with XMLs can be cumbersome, especially if you don't have a clear idea of the expected structure.

Therefore, even if not strictly necessary, I suggest installing a VS2022 extension called Snippet Designer 2022.

This extension, developed by Matthew Manela, can be found on GitHub, where you can view the source code.

This extension gives you a UI to customize the snippet instead of manually editing the XML nodes. It allows you to customize the snippet, the related metadata, and even the placeholders.

Create a basic snippet in VS2022 using a .snippet file

As we saw, snippets are defined in a simple XML.

In order to have your snippets immediately available in Visual Studio, I suggest you create those files in a specific VS2022 folder under the path \Documents\Visual Studio 2022\Code Snippets\Visual C#\My Code Snippets\.

So, create an empty file, change its extension to .snippet, and save it to that location.

Now, you can open Visual Studio (it's not necessary to open a project, but I'd recommend you to do so). Then, head to File > Open, and open the file you saved under the My Code Snippets directory.

Thanks to Snippet Designer, you will be able to see a nice UI instead of plain XML content.

Have a look at how I filled in the several parts to create a snippet that generates a variable named x, assigns to it a value, and then calls x++;

Have a look at the main parts:

the body, which contains the snippet to be generated;
the top layer, where we specified:
- the Snippet name: Int100; it's the display name of the shortcut
- the code language: C#;
- the shortcut: int100; it's the string you'll type in that allows you to generate the expected snippet;
the bottom table, which contains the placeholders used in the snippet; more on this later;
the properties tab, on the sidebar: here is where you specify some additional metadata, such as:
- Author, Description, and Help Url of the snippet, in case you want to export it;
- the kind of snippet: possible values are MethodBody, MethodDecl and TypeDecl. However, this value is supported only in Visual Basic.

Now, hit save and be ready to import it!

Just for completeness, here's the resulting XML:

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
  <CodeSnippet Format="1.0.0">
    <Header>
      <SnippetTypes>
        <SnippetType>Expansion</SnippetType>
      </SnippetTypes>
      <Title>Int100</Title>
      <Author>
      </Author>
      <Description>
      </Description>
      <HelpUrl>
      </HelpUrl>
      <Shortcut>int100</Shortcut>
    </Header>
    <Snippet>
      <Code Kind="method decl" Language="csharp" Delimiter="$"><![CDATA[int x = 100;
x++;]]></Code>
    </Snippet>
  </CodeSnippet>
</CodeSnippets>

Notice that the actual content of the snippet is defined in the CDATA block.

Import the snippet in Visual Studio

It's time to import the snippet. Open the Tools menu item and click on Code Snippets Manager.

From here, you can import a snippet by clicking the Import... button. Given that we've already saved our snippet in the correct folder, we'll find it under the My Code Snippets folder.

Now it's ready! Open a C# class, and start typing int100. You'll see our snippet in the autocomplete list.

By hitting Tab twice, you'll see the snippet's content being generated.

How to use placeholders when defining snippets in Visual Studio

Wouldn't it be nice to have the possibility to define customizable parts of your snippets?

Let's see a real example: I want to create a snippet to create the structure of a Unit Tests method with these characteristics:

it already contains the AAA (Arrange, Act, Assert) sections;
the method name should follow the pattern "SOMETHING should DO STUFF when CONDITION". I want to be able to replace the different parts of the method name by using placeholders.

You can define placeholders using the $ symbol. You will then see the placeholders in the table at the bottom of the UI. In this example, the placeholders are $TestMethod$ , $DoSomething$ , and $Condition$ . I also added a description to explain the purpose of each placeholder better.

The XML looks like this:

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
  <CodeSnippet Format="1.0.0">
    <Header>
      <SnippetTypes>
        <SnippetType>Expansion</SnippetType>
      </SnippetTypes>
      <Title>Test Sync</Title>
      <Author>Davide Bellone</Author>
      <Description>Scaffold the AAA structure for synchronous NUnit tests</Description>
      <HelpUrl>
      </HelpUrl>
      <Shortcut>testsync</Shortcut>
    </Header>
    <Snippet>
      <Declarations>
        <Literal Editable="true">
          <ID>TestMethod</ID>
          <ToolTip>Name of the method to be tested</ToolTip>
          <Default>TestMethod</Default>
          <Function>
          </Function>
        </Literal>
        <Literal Editable="true">
          <ID>DoSomething</ID>
          <ToolTip>Expected behavior or result</ToolTip>
          <Default>DoSomething</Default>
          <Function>
          </Function>
        </Literal>
        <Literal Editable="true">
          <ID>Condition</ID>
          <ToolTip>Initial conditions</ToolTip>
          <Default>Condition</Default>
          <Function>
          </Function>
        </Literal>
      </Declarations>
      <Code Language="csharp" Delimiter="$" Kind="method decl"><![CDATA[[Test]
public void $TestMethod$_Should_$DoSomething$_When_$Condition$()
{
    // Arrange

    // Act

    // Assert

}]]></Code>
    </Snippet>
  </CodeSnippet>
</CodeSnippets>

Now, import it as we already did before.

Then, head to your code, start typing testsync, and you'll see the snippet come to life. The placeholders we defined are highlighted. You can then fill in these placeholders, hit tab, and move to the next one.

Bonus: how to view all the snippets defined in VS

If you want to learn more about your IDE and the available snippets, you can have a look at the Snippet Explorer table.

You can find it under View > Tools > Snippet Explorer.

Here, you can see all the snippets, their shortcuts, and the content of each snippet. You can also see the placeholders highlighted in green.

It's always an excellent place to learn more about Visual Studio.

Wrapping up

There are some tips that may improve both the code quality and the developer productivity.

If you want to enforce some structures or rules, add such snippets in your repository; when somebody joins your team, teach them how to import those snippets.

I hope you enjoyed this article! Let's keep in touch on Twitter or LinkedIn! 🤜🤛

Happy coding!

🐧

DEV Community: Davide Bellone

HTTP Logging in ASP.NET: how to automatically log all incoming HTTP requests (and its downsides!)

Scaffolding the empty project

How to add HTTP Logging to an ASP.NET application

Understanding HTTP Request logs

Understanding HTTP Response logs

How to save space, storage, and money by combining log entries

The downsides of using HTTP Logging

Further readings

Wrapping up

Fitness Functions in Software Architecture: measuring things to ensure prosperity

Fitness Functions: because non-functional requirements matter

Why Fitness Functions are crucial for future-proof architectures

You are already using Fitness Functions, but you didn't know

Further readings

Wrapping up

C# Tip: 2 ways to generate realistic data using Bogus

Expose a Faker inline or with a method

Expose a subtype of Faker, specific to the data type to be generated

Method vs Subclass: When should we use which?

Further readings

Wrapping up

Easy logging management with Seq and ILogger in ASP.NET

Seq: a sink and dashboard to manage your logs

A sample ASP.NET API project

How to integrate Seq with an ASP.NET application

Using Structured Logging with ILogger and Seq

Further readings

Wrapping up

Introducing the Testing Vial: a (better?) alternative to Testing Diamond and Testing Pyramid

The Testing Pyramid: the focus is on Unit Tests

Problems with the Testing Pyramid

The Testing Diamond: the focus is on Integration Tests

Problems with the Testing Diamond

Introducing the Testing Vial: the focus is on business entities

Architectural tests, to validate that the system design hasn't changed

Categories, to identify and isolate areas of your application

Further readings

Wrapping up

Davide's Code and Architecture Notes - the Error Management Trio, and how it affects your software architecture

An ideal system with only the happy path

Introducing the Error Management Trio

Data Validation: the first defence against invalid status

Transient Errors: temporary errors that may randomly occur

Fatal Errors: when everything goes wrong

A practical approach to address the Error Management Trio

Further readings

Wrapping up

C# Tip: IEnumerable vs ICollection, and why it matters

IEnumerable: loop through the items in the collection

ICollection: list, add, and remove items

Why knowing the difference actually matters

Wrapping up

How to use IHttpClientFactory and WireMock.NET together using Moq

Explaining the dummy class used for the examples

WireMock.NET, a library to simulate HTTP calls

Basic configuration of HTTP requests and responses with WireMock.NET

How to integrate WireMock.NET with a Moq-driven IHttpClientFactory

Let WireMock.NET create the HttpClient for you

Further readings

Wrapping up

Davide's Code and Architecture Notes - Practical creation of C4 Model diagrams with Structurizr

An overview of the C4 Model

Context: a high-level view, with external dependencies

Containers: the internal architecture's main modules

Components: the main parts within a Container

Code: the low-level view of the code

What is (and what is not) the C4 Model

Step-by-step C4 diagrams with Structurizr

File structure for Structurizr

2 ways to install Structurizr locally (on Windows 11)

Run Structurizr locally with Docker

Set up the Context elements

Describe Containers and their interactions

Define Components

Code level

Practical tips for working with Structurizr

Further readings

Wrapping up

C# Tip: ObservableCollection - a data type to intercept changes to the collection