DEV Community: Rafael Câmara

Ports and Adapters Architecture (Hexagonal Architecture) in practice with .NET

Rafael Câmara — Mon, 23 Jun 2025 12:56:53 +0000

In one of my previous blog posts, I wrote about the Ports and Adapters Architecture, also known as Hexagonal Architecture.

Now we are going to apply those theoretical concepts in practice by using .NET.

Before we go any further, here's an image to recap the structure of the Ports and Adapters Architecture:

The anatomy of a use case

As mentioned in the aforementioned blog post, the Ports and Adapter Architecture is use case driven. Therefore, it's critical to clarify what a use case is and how to structure one properly.

What is a use-case

Use cases are related to user intentions. They describe how users interact with your application to achieve a specific goal. As an example, a use case can be withdrawing money.

In Hexagonal Architecture, use-cases encapsulate business logic, and you should avoid having a use-case call another use-case directly, as they represent different intentions in your system and should evolve independently and for different reasons.

How to structure a use-case

First, it's important to clarify that Hexagonal Architecture is not prescriptive about how you should structure your code.

So anything I mention here about code structure it's nothing but my own opinion on the subject.

I like to think of use cases as actions that have an input and might return an output. Therefore, I like to use a variation of the Command design pattern when it comes to the use cases.

If you try to categorize use cases into groups, you will find 3 main ones:

1. "Regular" use cases. These are use cases that have an input and an output.

Converting this to C#, it would look something like:

public interface IUseCase<TInput, TOutput>
{
    Task<TOutput> ExecuteAsync(TInput input);
}

2. Unit use-cases. The characteristic of these use cases is that they only have an input. Their return is void. You could use this use-case to execute some piece of logic where you don't care about any returns from it (what we could call a command in the CQRS world).

Converting this to C#, it would look something like:

public interface IUnitUseCase<TInput>
{
    Task ExecuteAsync(TInput input);
}

3. Nullary use-cases. The characteristic of these use cases is that they only have an output. Their input is void. An example of where you might want to use this is when you want to get all the elements from a specific collection without any filters being applied (what we could call a query in the CQRS world).

Converting this to C#, it would look something like:

public interface INullaryUseCase<TOutput>
{
    Task<TOutput> ExecuteAsync();
}

Technically speaking, the ports we mentioned are inside the hexagon, so I will give no further explanation about them next.

Inside the hexagon

.NET wise, you can create a Class Library project to hold this hexagon. Let's call it Core:

As mentioned previously, inside the hexagon we will need to have our business logic. As suggested, this business logic can be encapsulated inside a use case.

So, one of the things you can do is to create a port that maps this use case.

Let's assume we want a port to compute a tax rate for a given continent.
We can either directly use the IUseCase<TInput, TOutput> interface or create a more specific one that inherits from this one, which is what we are going to do.

This use case would look something like this:

public interface IComputeTaxRateUseCase : IUseCase<Continent, double>
{
}

Now it's time to make this use-case concrete. As an example:

public class ComputeTaxRateUseCase(IRepository<Domain.Models.TaxRate> repository, INotification notification) : IComputeTaxRateUseCase
{
    public async Task<double> ExecuteAsync(Continent continent)
    {
        var taxRateForContinent = await repository.GetSingleByAsync(x => x.Continent == continent);

        if (taxRateForContinent is null)
        {
            throw new NoTaxRateForContinentException(continent);
        }

        var currentDayOfTheWeek = (int) DateTime.UtcNow.DayOfWeek;

        var updatedTaxRate = taxRateForContinent.Rate * (1 + currentDayOfTheWeek / 7);

        await notification.NotifyAsync(new
        {
            Title = "Tax Rate Computation",
            Message = $"Computed tax rate for {continent} is {updatedTaxRate}",
            Timestamp = DateTime.UtcNow
        });

        return updatedTaxRate;
    }
}

As you can see, this use case drives (i.e. uses) two other ports: one port for persistence (IRepository) and another for notification (INotification).

The interfaces for the driven ports are defined inside the hexagon:

Example port for IRepository:

public interface IRepository<T>
{
    Task<T?> GetSingleByAsync(Func<T, bool> predicate);
}

The implementations are defined outside of it. We will have a look at them next.

Driven Adapters (Right side of the hexagon)

To host the driven adapters, I suggest creating a folder called adapters and, inside it, create another folder that will host the driven adapters.

In our case, we need to implement driven ports for two purposes: ForPersistence and ForNotification. We will create, again, a Class Library for each one, and fake a MongoDB and RabbitMQ adapters (we will not provide exact implementations of them).

As previously mentioned, the actual implementations of these adapters are simple and don't use the underlying technologies we mention.
As an example, this is our fake MongoDB implementation:

namespace MongoDbAdapter
{
    public class MongoRepositoryAdapter<T> : IRepository<T>
    {
        //inject MongoDB context or client here

        public Task<T?> GetSingleByAsync(Func<T, bool> predicate)
        {
            Console.WriteLine("*** Mongo Adapter - Database query");
            return Task.FromResult(Collections.GetCollectionOfType<T>().FirstOrDefault(predicate));
        }
    }

    public static class Collections
    {
        private static List<TaxRate> _collection = [
            new TaxRate { Id = Guid.NewGuid(), Continent = Continent.Europe, Rate = 0.20 },
            new TaxRate { Id = Guid.NewGuid(), Continent = Continent.Africa, Rate = 0.15 },
            new TaxRate { Id = Guid.NewGuid(), Continent = Continent.Asia, Rate = 0.18 },
            new TaxRate { Id = Guid.NewGuid(), Continent = Continent.NorthAmerica, Rate = 0.22 },
            new TaxRate { Id = Guid.NewGuid(), Continent = Continent.SouthAmerica, Rate = 0.19 },
            new TaxRate { Id = Guid.NewGuid(), Continent = Continent.Oceania, Rate = 0.25 },
            new TaxRate { Id = Guid.NewGuid(), Continent = Continent.Antarctica, Rate = 0.10 }
        ];

        public static List<T> GetCollectionOfType<T>()
        {
            if (typeof(T) == typeof(TaxRate))
            {
                return _collection as List<T>;
            }
            throw new InvalidOperationException($"No collection found for type {typeof(T).Name}");
        }

    }

}

As you can see, these adapters here have to implement the port specification that was specified inside the hexagon.

Driver Adapters (Left side of the hexagon)

Inside the adapters folder create a folder called driver. This folder will container all of our driver adapters.

Inside of it, we can create a WebApi project that will host our API adapter.

Here we will manage the endpoints that we are exposing to the outside world and adapt their language to the language that our use cases speak.

For simplicity, we will create only one endpoint that will call our IComputeTaxRateUseCase.

This endpoint could look something like:

app.MapGet("/api/tax-rate", async (IComputeTaxRateUseCase computeTaxRate, string continent) =>
{
    var cont = (Continent)Enum.Parse(typeof(Continent), continent, true);

    return Results.Ok(await computeTaxRate.ExecuteAsync(cont));
});

You can see here a bit of the adaptation I was previously speaking about. Our use case accepts an Enum as input, but we get a string from the outside world (from the actors). So our adapter does just that: adapts. It converts what we get from the actors to a language that our use-case understands.

Tests as a driver/driven mechanism

As you might have noticed in the previous screenshots, we had one folder called test (even though there are no actual tests for simplicity's sake).

Generally speaking, tests are important in software engineering, but they have a key role in hexagonal architecture as they have a highlighted role.

Tests will provide with you an easy way to test how flexible your ports are, meaning if you can plug and play with anything. With tests, you can both simulate actions from the left and right side of the hexagon.

Final

Would you rather see this in video? Please check it here. In the video, I speak about other things, such as improving the isolation between projects even further with the Composite Root design pattern.

Check this repository for the source code.

Ports and Adapters (Hexagonal Architecture)

Rafael Câmara — Wed, 04 Jun 2025 19:27:21 +0000

Have you ever wondered how you could isolate your application from external concerns, like which database to use? Or isolating it who is consuming your application?

Domain-centric architectures, like the Ports and Adapters, allow you to achieve just that.

The Ports and Adapters architecture, also known as Hexagonal architecture, was a concept started by Alistair Cockburn in 1994, but then officially written in his blog in 2005.

Its intention is:

Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases.

This connected to what we previously stated: isolating the business logic from everything external and that can be ever-changing.

Our business logic is the money maker, so we must protect and isolate it from external dependencies. It should not be coupled to anything.

The reason why you should care about this decoupling is because you should consider these external factors as ever-changing. These should be easily replaceable. You don't want to change your business logic just because your database type has changed, or because some application no longer is consuming your services via HTTP and now uses gRPC. You want your application to be tested, maintained, and evolve independently of such factors.

What is the Ports and Adapters architecture

As stated previously, the Ports and Adapters architecture is an architectural style that aims at decoupling the business logic from external factors.

It's a use-case-driven architecture, where you first think about the use cases, and then only about the implementation details like which database to use. By doing this, you could have your application running all in-memory, with in-memory dependencies, which is something that is very powerful when you think about it.

Hexagonal architecture is not prescriptive on how you organize your code inside the hexagon. This makes applying this architectural style much easier, as the focus is on the isolation factor.

Here's a visual overview of this pattern, before we proceed to explain each individual part:

Let's now address some of the most common terms associated with this pattern.

"The Hexagon": Before we go into details about what this is, first let us understand why the hexagon is the chosen shape. The reason is that, back in the day, every architecture diagram was using squares, and Alistair wanted a symmetrical shape that was not already taken and that could have room to insert ports and adapters freely.
Now, as far as the purpose of the hexagon, this is where your core business logic is located, with your use cases and, possibly, domain constructs like domain entities, and so on.
If you look at the architecture diagram above, you'll notice that everything that is on the left-hand side is called Driver X, where X is the element you are referring to (ex. driver adapter). The reason why it's called Driver is because it's the element that is related to the usage of our application.
The right-hand side is called Driven X. It's called this way because it's what the application uses.
You must be wondering: "Sure I have my business logic here, but how can I call it from the outside world? And how can I make use of databases or message brokers?". This is where the concept of ports comes in.
Ports: Ports are interfaces defined by the hexagon. Adapters outside the hexagon implement these interfaces (for driven ports) or consume them (for driving ports).
We have two types of ports: the driver ports and the driven ports.
In the case of the driver ports, they are used to call the use cases, for example, call a use case to debit from someone's bank account.
The driven ports are used by our application to call the driven actors. For example, this port represents the contract that stores, retrieves, updates, and deletes objects from a database.
You can organize the ports by their intent. For example, you can have a group of ports for notifications and another group of ports for administrative tasks.
A misconception is that, because it's a hexagon, it means that we must have exactly 6 ports. This is something that is not correct. You can have as many ports as you want.
So, now we have defined the contracts to interact with our application (and to access the outside world). Now comes the question: who uses such contracts? This is where the adapters come into play.
Adapters: These are the middle elements between the actors and the ports. The driver adapters must be coupled to a specific actor. For example, the driver adapter must be coupled to driver actors, so that they can convert the data they send into data that is compatible with the inputs of the use cases. On the other hand, the driven adapters must convert the data they get from the application to what the driven actor understands, and vice-versa.
Driver actors: Elements that are interested in using our application via our use cases. For example, a user in some Web portal performing administration tasks, or even a message broker is trying to push messages into our application.
Driven actors: Elements that our use cases use, like databases or message brokers.

Conclusion

Enabling domain-centric architectures is always a safe bet when it comes to building resilient and adaptable software.

Ports and adapters are just one way of contributing to this purpose.

Want this see this in video? Check it out.

Want to see this in practice? Stay tuned for the next posts!

Application Monitoring: Black-Box vs White-Box

Rafael Câmara — Sat, 24 May 2025 14:39:18 +0000

Application monitoring, or just monitoring, refers to detecting if anything is failing in your application. Failures include performance degradation, capacity planning, security anomalies, and resource usage.

These failures could have impacts, such as impacting directly your users, or 3rd parties that are reliant on you.

So, with monitoring, we want to ensure that our system functions according to its expected behavior.

In this spirit, there are two complementary ways that we can perform this monitoring: Black-box and White-box.

Black-box monitoring

With black-box monitoring, we look at the system you want to monitor from the perspective of the user or, broadly, putting yourself in the shoes of an external perspective.

You don’t care about the internal implementation details, you are just interested in what are the observable outputs and behavior the system gives you.

Key characteristics

Focus on external behavior: As stated previously, our intention is to monitor the system from the point of view of an external observer, like a user. So we want to look for things like how fast you can get a response, the availability of the services, and if the services are behaving as expected, meaning, that they deliver the promised set of features. This might include doing things a user would do.
No internal access: Every conclusion is based on metrics and alerts that we take exclusively based on external observations, without any need to see the internal implementation details.

This black-box monitoring has the advantage of being user-centric, which means that it allows us to identify and fix any issues that might arise in the user journeys. Simplicity is also something that is a huge advantage of this approach since we don’t have to instrument or access any of the internal systems.

Even though this black-box approach is simple, it might have some drawbacks. As mentioned earlier, one of the advantages of this approach is its simplicity due to the fact that we don’t have to be very granular with our instrumentation level. But this also can be a problem because it makes it harder to try to understand the root cause of something when things go out of normal.

Another disadvantage of this approach is the fact that it alerts us whenever we have problems that are already impacting customers. This means that we are more reactive in our actions, and not as proactive as we should be.

Now let’s have a look at this concept in practice. Assume that we are in the context of a streaming application. If you were taking this black-box approach, what you only care about is if the video you are loading on your screen is loading fast. You don’t care how the streaming service has implemented it, you just care that the video is being loaded fast.

So, in summary, black-box monitoring is used to tell you something is wrong and might be impacting others.

White-box monitoring

In this approach, you can now monitor your system in a transparent way. This means that you can directly instrument your code, or gather metrics from the infrastructure usage. You can be much more granular on what you can consider as the source for the monitoring data because you can see the inner workings of your system.

Key characteristics

Focus on internal behavior: In contrast with the black-box monitoring, here we are focused on the inner workings of the system. Collecting logs, metrics, and traces is our priority. The sources for such data can vary from infrastructure resources, like CPU and memory, to more application level, like the number of HTTP requests processed.

Developer-centric: Often these metrics are used by developers, and the operations team, to understand the health and performance of the system.

Even though this white-box approach is a bit more cumbersome, because the amount of things we might need to instrument is a bit higher than in the case of black-box monitoring, and generates a much bigger data volume, the white-box approach still has some advantages.

First, let’s consider the fact that we are allowed to go deeper in our analysis. This goal is easier to achieve because we are much more granular when it comes to monitoring/observing.

Secondly, based on the data that we can analyze, we can try to understand if there might exist problems for users. This means that approaches are more predictive than proactive.

An example of using this approach is monitoring resources like CPU, and RAM, or even checking how performant your database queries are. Tracing is another example since it allows you to check the flow of a request inside your system.

In summary, white-box monitoring is used to tell you why something is not ok and helps you to understand the root causes of such failures.

Which approach to use?
In my opinion, the discussion should not be about which one to use, but rather how we can create some symbiosis between the two.

These two approaches should be seen as complimentary in the sense that, when used together, they give you a deeper understanding of the state and performance of your system.

As stated previously, one gives us the notion that something is not going right, and the other one lets us dig deeper and understand why that’s happening.

C# LINQ Any Explained

Rafael Câmara — Sat, 25 Jan 2025 22:05:08 +0000

The Any LINQ method allows you to check if there are elements in a given collection that satisfy a given condition. If at least one element satisfies the condition, true is returned. Otherwise, false.

If you provide no condition to check against the collection's elements, the Any LINQ method will check if the collection has any elements. If elements are present in the collection, the method will return true. Otherwise, false.

Let's assume we have the following list of numbers: [1, 2, 3, 4, 5], and you want to check if there are numbers that are greater than 3.

In this case, we do have 4 and 5:

Since we have at least one element that satisfies the condition, the Any method will return true.

If we change the condition to check if any elements are greater than 10, the outcome would be false.

Any in code

Let's first start by creating our sample collection:

public static int[] SimpleCollection = [1, 2, 3, 4, 5];

Let's test the first scenario, which checks if any elements are greater than 3.

var isBiggerThan3 = SimpleCollection.Any(number => number > 3);

Notice the condition number => number > 3. It's passed as a lambda expression to the Any method and will be tested against the elements of the collection.

The variable isBiggerThan3 would hold the value of true.

In the second scenario, we would have to adjust our code to something similar to this:

var isBiggerThan10 = SimpleCollection.Any(number => number > 10);

The variable isBiggerThan10 would hold the value of false.

Resources

If you are more of a visual learner, I’ve created a playlist showcasing the Any LINQ method and other ones.

If you want to go directly to the Any videos, here are the direct links for the theory and practice.

Here you can find a variation of the source code presented in this article.

Downstream Resiliency: The Timeout, Retry, and Circuit-Breaker Patterns

Rafael Câmara — Mon, 02 Dec 2024 14:23:17 +0000

As systems become more connected and dependent, downstream resiliency has become a key consideration in service architecture, guiding how an application responds in case dependent services fail.

This article will dive into downstream resiliency and how timeouts, retries, and circuit breakers work together.

What is Downstream Resiliency?

Downstream Resiliency refers to the capability of a service, say Service A, to function properly when there are failures contributed by its downstream dependencies, for instance, Service B, which itself may further rely on another service (Service C). Most of the time, especially in distributed architectures like microservices, services do not operate in isolation. For example, Service A might call Service B, and that in turn calls Service C to complete its requests. When these services experience either latency or outage, it is important for the originating service, Service A in this case, to implement various measures to handle such situations gracefully.

Timeouts

The first line of defense for ensuring downstream resiliency is the implementation of timeouts. A timeout is a period after which a service will stop waiting for a response from a downstream call. Imagine Service A calling Service B and waiting indefinitely for a response. This can lead to resource exhaustion as Service A holds onto resources while it waits for a response. With a set timeout, Service A can free up resources and resume its functioning even if Service B takes longer to respond.

However, determining the optimal timeout duration is critical. Too short of a timeout could lead to unnecessary failures, and respective potential retries, while too long could waste valuable resources. Utilizing observability tools can help in understanding the typical response times and setting an appropriate timeout threshold, usually slightly higher than the average response time observed.

Retries

Retries occur when an initial request to a downstream service fails or times out. The assumption in such scenarios is that the failure might be transient, meaning that the service is very much capable of handling requests but is just temporarily overwhelmed. In such a case, by retrying the request, Service A can probably receive a successful response without overwhelming Service B.

When it comes to retries, one of the most important characteristics is to understand which backoff strategy we should adopt. A backoff strategy just refers to how long we should wait between retries.
There are a couple of strategies we can go with:

Constant Interval: Retrying after a fixed duration. For example retry every second.

Linear Interval: In this, the wait time is increased linearly after each retry. As an example, the first retry happens after 1 second, the second retry after 2 seconds, and so on.

Exponential Interval: The wait time increases exponentially, thereby helping to reduce the load on Service B. Normally the base of the exponent is 2. For example, the first retry happens at 2 seconds (2 to the power of 1 [retry attempt]), the second at 4 seconds (2 to the power of 2 [retry attempt]), the third at 8 seconds (2 to the power of 3 [retry attempt]), and so on.

Exponential Backoff with Jitter: Introduce randomness in the retry intervals to avoid a "thundering herd" problem where all services retry at the same time and overwhelm Service B. It's the same as the exponential interval but with an added random jitter. For example, the first retry happens at 2.2 seconds (2 to the power of 1 [retry attempt] plus random 0.2 seconds of jitter), the second at 4.7 seconds (2 to the power of 2 [retry attempt] plus random 0.7 seconds of jitter), and so on.

Circuit-Breaker

While retries are suitable for transient issues between services, circuit breakers handle scenarios where a service is likely down, i.e. non-transient failures. The circuit breaker pattern changes the state of the service based on the success or failure of a number of requests. It has three states: Closed, Open, and Half-Open.

Here's a high-level overview of the states and their respective transitions:

In the Closed state, requests flow normally.
If a threshold of failures is reached, the circuit breaker transitions into the Open state, blocking all requests to that service for a defined timeout period.
It transitions after this time into the Half-Open state, when a request is made, to test whether the downstream service has recovered. If the request is successful, it transitions back into the Closed state; if not, into the Open state.

Here's a more visual explanation of these state changes.

(1) Closed circuit. Everything is flowing normally and ok between services:

(2) Open circuit. After a specific number of requests fail (you configure this number/threshold), the downstream dependency is considered as faulty, therefore the circuit is opened.

(3) After a period of the time of open circuit (which is also configured by you), we allow the next request to flow through, to test the waters. By doing so, the first step is to move the state of the circuit to half-opened.

The system won't stay here. The next state will depend on the success of the response to this request. If positive the system will go back to the closed state.

Otherwise, it goes to the open state.

These state changes will continue for as long as the system is alive.

This process prevents Service A from constantly trying to reach a non-responsive Service B, thus saving resources and generally contributing to system stability.

Conclusion

In summary, downstream resilience is a must-have to ensure the stability of modern applications dependent on several services. Adding timeouts, using retry strategies, and applying circuit-breakers build a resilient system that can handle failures in downstream dependencies gracefully. Each of these has its own subtlety and requires careful consideration and monitoring to ensure they work as expected.

Resources

If you are more of a visual learner, I’ve created a video to showcase the concepts explained here.

Automate Your C# Library Deployment: Publishing to NuGet and GitHub Packages with GitHub Actions

Rafael Câmara — Mon, 04 Nov 2024 22:46:46 +0000

So you’ve created a cool C# library that you want to share with your fellow developers, but don’t know how? Maybe you know you could do that with NuGet packages, but don’t know how to create one?

This post showcases how you can make this amazing library you’ve created publicly available so that others can enjoy working with it!

What is a NuGet package?

A NuGet package is a single, packaged library or set of libraries, complemented by metadata and dependencies, designed to easily be distributed and integrated into projects in .NET.

This saves time for the developers by avoiding rewriting or duplicating code, as we promote reusability by installing these packages and making use of their functionality.

Sample library code

We are going to be a very simple logger class that just prints a message to the console. This printing will evolve to showcase that new changes in our library code can be automatically deployed to the package feeds, but we will come to this in a second.

First, let’s create a class library project. We can do so via de command line:

dotnet new classlib -n Something

The outcome should look something like:

We can now change the directory to our project folder:

cd MyAmazingLogger

Another thing we can do is to remove the default Class1.cs file.

Then, let’s create a class that represents the functionality we want to share. In this case, a logger class. Here’s some sample code:

public static class MyCustomLogger
{
     public static void LogMyMessage(string message) => Console.WriteLine($"v1: {message}");
}

Now that we have this base code class let’s make this shareable across the world :)

Configuring the continuous integration (ci) workflow file

If you want your GitHub actions to trigger whenever an event occurs, as an example a commit is made in main.

To configure our GitHub actions we need to place the yaml files inside a specific folder structure: .github → workflows → ci.yaml (this can be named anything)

This ci.yaml file contains the code that will package our library and publish it to the corresponding package source. This file can do many more things, like building the app, running tests, generating docker images, and so on, we are just using a very small fraction of the abilities this gives us.

Now let’s see how this file can look depending on the target package source. For each one of them, I’ll first introduce the final version of the ci.yaml file and then explain the file in detail.

Publishing to GitHub Packages with GitHub Actions

Here’s the CI manifest file to publish your NuGet packages to GitHub packages, via Github actions:

name: ci

on:
  push:
    branches: [main]

jobs:
  generate-version:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v2

      - name: GitHub Tag Bump
        id: tab_bump
        uses: anothrNick/github-tag-action@1.71.0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          INITIAL_VERSION: 1.0.0
          DEFAULT_BUMP: patch

    outputs:
      new_version: ${{ steps.tab_bump.outputs.new_tag }}

  package-and-publish-lib:
    runs-on: ubuntu-latest
    needs: generate-version

    steps:
      - uses: actions/checkout@v2

      - name: Setup .NET
        uses: actions/setup-dotnet@v1
        with:
          dotnet-version: 8.0.x

      - name: Generate NuGet package
        run: |
          dotnet pack MyAmazingLogger/ \
          --configuration Release \
          -p:PackageVersion=${{ needs.generate-version.outputs.new_version }} \
          -p:RepositoryUrl=https://github.com/RafaelJCamara/YT-Nuget-Pkg-Release \
          -o packages

      - name: Publish NuGet package
        run: dotnet nuget push packages/*.nupkg --api-key ${{ secrets.PUSH_NUGET }} --source https://nuget.pkg.github.com/RafaelJCamara/index.json

Now let’s analyze the important bits.

When to trigger a package publish

Based on what we have in our manifest:

on:
  push:
    branches: [main]

Packages are going to be published whenever we have some code merged to main.

What steps are involved

We know that our packages need to have a version. This version follows a format called semantic versioning. This is where the job called generate-version comes in. The output of this job is a version number that will be used when we publish our package in the package-and-publish-lib job.

So, as we can see, we have two main high-level overview steps: one to generate a package version and another to use that generated version in the package to be published.

Analyzing the `generate-version` job

This job only has one step and that step’s only responsibility is to generate a package version.

To help us on this task we are using an action called anothrNick/github-tag-action.

As you can see from our manifest file, we have the following environment variables necessary for this action to properly work:

GITHUB_TOKEN: This token is required for permissioning the tag in the repo. We can use a built-in token called secrets.GITHUB_TOKEN, you don’t have to configure anything to access this token. This token is automatically generated for your repo by GitHub and allows you to safely interact with GitHub’s Apis and your repository, allowing you to do things like publishing packages. As of the writing of this post, this token only has read permissions, therefore we can’t write anything. This is why we have this section at the top of the generate-version job:

    permissions:
      contents: write

This will give our token enough permission to write the tags.

If you don’t give write permissions, this is the error you will get:

There’s another way to solve this problem which is to not use that GitHub token and create your own token with read and write permissions. We will see how we can do this when we speak about the token usage for publishing packages.

INITIAL_VERSION: This presents an initial version we might have. Keep in mind that the notation followed is the semantic versioning one and that the first run of this will increment upon this default value. As an example, if the default value is 1.0.0 with default_bump patch and we run our GitHub action, the end value will be 1.0.1, and not 1.0.0 on the first run.
DEFAULT_BUMP: This represents how the increments will happen. The value we are using is patch, meaning that it will have increments like this: 1.0.5 to 1.0.6. We can have other bump strategies, choose one that best fits your use case.

For more information on these configurations, and possibly others you can enable, please take a look at the action’s documentation.

As you may have noticed, we have defined an output from the job. This is useful so that we can use the produced tag number in other jobs, which is what we want.

    outputs:
      new_version: ${{ steps.tab_bump.outputs.new_tag }}

As we can see from the snippet, we are defining an output with key new_version, which is pretty much just returning the value from the GitHub Tag Bump step. Just note that we had to give an ID to the step (tab_bump) so that we could target the step’s output.

Analyzing the `package-and-publish-lib` job

The two main responsibilities of this job are:

Package our code into a NuGet package (*.nupkg)
Publish this package into a package feed (in this case GitHub packages)

This job has 3 main steps:

Choosing the appropriate .NET version (step Setup .NET)
Generating the NuGet package (step Generate NuGet package)
Publishing this NuGet package (step Publish NuGet package)

Let’s analyze each step with care.

Choosing the appropriate .NET version (step `Setup .NET`)

This step simply uses the action actions/setup-dotnet@v1 to set up our .NET version (in this case .NET 8).

Generating the NuGet package (step `Generate NuGet package`)

Let’s bring the package command closer to us so that we can analyze it better:

 dotnet pack MyAmazingLogger/ \
          --configuration Release \
          -p:PackageVersion=${{ needs.generate-version.outputs.new_version }} \
          -p:RepositoryUrl=https://github.com/RafaelJCamara/YT-Nuget-Pkg-Release \
          -o packages

First, we need to understand that we use the dotnet pack command to generate our NuGet package. In our case, we are using a couple of flags:

--configuration Release: we want to use the Release configuration because it’s more performant and tends to generate bundles with lower storage requirements (smaller size bundles).
-p:PackageVersion=${{ needs.generate-version.outputs.new_version }}: here we are specifying the NuGet package version. As you remember, we generated this version on the previous job (generate-version) and we need to access this output. To do so we can use the needs keyword, then specify the job we want to get the output from (generate-version), and then access the outputs property of this job and then the key of our output (which we named new_version). When you do this, you can get the generated version!
-p:RepositoryUrl=https://github.com/RafaelJCamara/YT-Nuget-Pkg-Release: What this is doing is adding the repository URL metadata to the published NuGet package. There is another way of doing this, which we will cover shortly.
-o packages: Specifies the directory where the generated NuGet package should be placed. In this case, the output will be stored in the packages folder.

After this step, we have our NuGet package ready to be published!

Publishing this NuGet package (step `Publish NuGet package`)

Let’s take a closer look at the publish command:

dotnet nuget push packages/*.nupkg --api-key ${{ secrets.PUSH_NUGET }} --source https://nuget.pkg.github.com/RafaelJCamara/index.json

To publish our package we need to use the dotnet nuget push command. We need to provide 3 important values to it:

Where the NuGet package is located. We do so by passing the packages/*.nupkg parameter. This would normally match with what you’ve inserted as the output of your dotnet pack command.
Where the package feed/repository is located. In this case, our source is https://nuget.pkg.github.com/RafaelJCamara/index.json. Since we are using the GitHub package repository we have a special source structure: https://nuget.pkg.github.com/{github-username}/index.json. This means that if your username is LostJohn1234 your source would be something like https://nuget.pkg.github.com/LostJohn1234/index.json.
The api-key to access the feed. As you can see, we are passing a token from the GitHub secrets. This means we need to create one token that has permission to write packages. In the next section, I’ll show you how to do it.

Creating a GitHub secret

Let’s see how we can create a secret token that has permission to write NuGet packages to our GitHub package feed.

First, let’s go to your profile Settings page.

Go to the Developer Settings section, and select Tokens (classic) inside the Personal access tokens. Generate a classic token.

Make sure you have something like this:

When you generate the token, make sure you copy it because now we must add that token as a secret for our repository.

In your repository, click Settings. Inside the Security section, there is a subsection called Secrets and variables and under that there’s Actions. Make sure to click Actions. On Actions, create a new repository secret.

In the Name field, you need to put the secret name that matches what we have in the manifest file. This secret name was called PUSH_NUGET, but you can call it whatever you want with the condition that it must match what you wrote in the manifest.

In the Secret field, you must place the token value you got from the previous step.

Publishing to NuGet Feed with GitHub Actions

Here’s the CI manifest file to publish your NuGet packages to the NuGet feed, via Github actions:

name: ci

on:
  push:
    branches: [main]

jobs:
  generate-version:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v2

      - name: GitHub Tag Bump
        id: tab_bump
        uses: anothrNick/github-tag-action@1.71.0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          INITIAL_VERSION: 1.0.0
          DEFAULT_BUMP: patch

    outputs:
      new_version: ${{ steps.tab_bump.outputs.new_tag }}

  package-and-publish-lib:
    runs-on: ubuntu-latest
    needs: generate-version

    steps:
      - uses: actions/checkout@v2

      - name: Setup .NET
        uses: actions/setup-dotnet@v1
        with:
          dotnet-version: 8.0.x

      - name: Generate NuGet package
        run: |
          dotnet pack MyAmazingLogger/ \
          --configuration Release \
          -p:PackageVersion=${{ needs.generate-version.outputs.new_version }} \
          -p:RepositoryUrl=https://github.com/RafaelJCamara/YT-Nuget-Pkg-Release \
          -o packages

      - name: Publish NuGet package
        run: dotnet nuget push packages/*.nupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json

The difference between this manifest file and the previous one for GitHub packages is only two: the --source flag in the Publish NuGet package step and an adjustment we need to make in the api-key.

Before the source was the feed that was bound to your GitHub profile, but now the source needs to be the source of the NuGet feed: https://api.nuget.org/v3/index.json.

As far as the api-key, before our api-key was a secret that had a token that belonged to your GitHub profile, but now we must generate a token in nuget.org.

Every other step remains the same as before, so I advise you to take a read of what was written before and make the adjustments we are making in the section.

Creating a NuGet api-key

First of all, head out to nuget.org and do your registration.

After doing so successfully, click on your profile name and select the API Keys section. Click Create.

Select an expiration date that serves your interests and also make sure to put the correct scopes (you would need to add permission to push new packages and versions). You might also need to add the * attribute in the Global Pattern field.

Make sure you have something like this in the end:

Your key should be now visible:

Make sure to click Copy and take this value and put it as the Secret value in our PUSH_NUGET repository secret.

Ready. Set. Action.

After all of this setup, let's commit our code. When you do, by default, it’s going to do so in the main branch, which means that our workflow will trigger.

Now the outcome actually depends on which package source you are using.

If you are using GitHub’s Package repository, you should see your package on the right-hand side of your repository:

You will also notice that next to your commit you will have a success icon (or fail icon) if the underlying GitHub Action went fine:

If, on the other hand, you have used the nuget.org feed, this is what you should see in your published packages:

As you can see, you should be able to see the package you have published, with the correct version number attached to it.

Regardless of how many changes you now do on your package, all of these changes will now be automatically published to your chosen package feed!

How to use your custom NuGet packages

This step depends on which package repository you’ve used.

If you have used the default NuGet feed, you don’t need to do anything special to use your newly created package. Just go ahead and install it! It’s a plug-and-play because this feed comes by default with .NET. To check the current feeds you have, run the command dotnet nuget list source. If you haven’t added any feed, this is the outcome you should have:

If you have published your NuGet package to GitHub’s package repository, we must add it to our current list of sources. To do that we must run this command: dotnet nuget add source <your GitHub package feed> --name MyGitHubNuGetFeed. Normally the <your GitHub package feed> has a structure like https://nuget.pkg.github.com/{your GitHub username}/index.json.

In my case, the <your GitHub package feed> would be https://nuget.pkg.github.com/RafaelJCamara/index.json.

After adding your GitHub package feed, we can run the list source command again and see the newly added feed:

Now you can install your package freely!

Adding metadata to the published NuGet package

As I stated previously, we can set metadata related to our NuGet package in another way, and that another way is by adding metadata in the library .csproj file.

Each property specifies information that will be included in the package manifest, allowing others to understand the purpose, licensing, and source of the package when they download it from nuget.org or other sources. Here’s a breakdown of each property:

<PackageId>: This is the unique identifier for your NuGet package (in this case, MyAmazingLogger). It’s what users will search for when they want to install your package.
<Version>: Defines the version of your package, following semantic versioning (e.g., 1.0.0). This version appears in NuGet package listings and helps users identify updates or specific versions to install. Currently, we are not going to use this, due to our version being created in the GitHub Action.
<Authors>: Specifies the package author(s). This can be a single name or a list of contributors and helps users know who created and maintains the package.
<PackageDescription>: Provides a short description of your package. This text is displayed on nuget.org, where users can see what your package does.
<PackageLicenseExpression>: Indicates the license type for your package, such as MIT, Apache-2.0, or GPL. NuGet uses this to show the licensing terms, which is important for clarity regarding the legal usage.
<PackageTags>: These tags help improve discoverability on NuGet. For example, tagging it as Loggers, it makes it easier for users to find your package when they search for logging-related functionality.
<RepositoryUrl>: This is the URL for the repository where the package source is hosted, often on GitHub. This allows users to view the source code, file issues, or contribute to the project.

When you package and publish the project to NuGet, these metadata values are included in the .nuspec file (the package manifest) and displayed on the package’s page on nuget.org. Don’t worry if some of this information does not showcase if you publish your package in the GitHub package repository, from my experience it tends to not show some of the metadata. Regardless, it’s interesting and important to have such metadata.

Here’s an example of how your metadata can look like in nuget.org:

Resources

Here’s the source code for this post.

If you are more of a visual learner, I’ve created a video to showcase the tutorial explained here.

C4 Model - The Basics

Rafael Câmara — Sun, 27 Oct 2024 08:57:06 +0000

Software Architecture is all about developing systems that scale and are maintainable. Clear visualizations will help teams to communicate the design effectively. The C4 model comes in handy for this task! But what is C4, and why should you care?

What is the C4 model?

The C4 model is a framework that enables the documentation and visualization of software architecture. It gives a structured means of creating diagrams showing how different software systems interact with each other. While some people are quite satisfied with other solutions such as UML or general-purpose tools like draw.io or Excalidraw, C4 can come across as simpler and more standardized, while keeping your diagrams from bloating and being over-engineered.

While there are no fixed rules on how to build your software architecture diagrams, C4 attempts to bring clarity and standardization into this process. It is versatile enough to cover a wide range of detail levels, from high-level overviews to more technical and in-depth diagrams.

Why Use C4?

The value of C4 is in its simplicity and flexibility. You can have very basic diagrams that give someone a general sense of your system architecture but then go into more detailed diagrams, such as deployment models.

If you opt-out by using the diagram-as-code path, you can easily have this source controlled, which means that you see our architecture growing and evolving as time goes by.

4 Levels of the C4 Model

The C4 Model explains the architecture of a system from four levels of abstraction: context, container, component, and code. Each of them depicts the same system architecture in greater detail than the previous one.

Let's dive into each level and what it tries to tell.

Context Diagram

The Context Diagram provides a very high-level overview of the software system and its relationship to external dependencies. This diagram is about showing where your software would sit within the larger landscape, and it will highlight the external systems it interfaces with, such as external APIs, databases, or third-party services like Stripe or an e-mail service.

Purpose: High-level understanding of how the system interacts with the outside world.

Audience: Both technical and nontechnical stakeholders.

Important Details: Would a non-technical person get it instantly from this diagram? If not try to further simplify it.

Here’s an example of a context diagram:

Container Diagram

The Container Diagram zooms in one level further from the overall system into the different containers making up your system. Containers are essentially executables: for example, backend services, front-end applications, or databases. This level helps tear down how various containers are interconnected, showing what their individual responsibilities will be.

Purpose: Understand the building blocks of your system.

Audience: More technical stakeholders who require further details than what the Context Diagram can give them.

Important Details: More often than not, in this layer, one could introduce more technical information, like the programming languages being used and the types of databases. Where the Context Diagram usually tries to convey the whole, big picture, the Container Diagram goes into the internal structure of the system.

Here’s an example of a container diagram:

Component Diagram

The Component Diagram goes even further, as it zooms into the details inside of each container and the internal components that make it up. For instance, if one container is a web application, this diagram can go down to controllers, services, or even repositories inside an application and how they might talk with one another.

Purpose: Breaking down each container to show how internal components work together.

Audience: Technical teams for closer views of the inner details.

Important Details: The level of detail is higher here; hence, it is best used for teams that are directly working on the software.

Here’s an example of a component diagram:

Code Diagram

In that case, the Code Diagram focuses primarily on the internal structure that components usually contain, classes, or objects. Not every situation demands this amount of detail, and such diagrams are frequently created automatically by tools, such as Integrated Development Environments (IDEs). Since C4 doesn't define the notations at this level, other modeling notations, such as UML, can be used to represent code structure.

Purpose: The implementation level details will be depicted, such as class structures.

Audience: All the developers that need to see code-level details.

Important Details: Often this level can be generated automatically with tools, hence it might not be necessary to create these diagrams manually.

Here’s an example of a code diagram, taken from the C4 docs:

Source: https://c4model.com/diagrams

When to Use Different Levels of C4

Another strength of the C4 Model is that it's so flexible, meaning you don't have to use all four levels all of the time. For many systems, drawing a Context Diagram and a Container Diagram will often be sufficient to communicate what a team needs to know about the system. You can often convey the largest part of the information for most stakeholders using just these two levels.

If you're working on a very complex system, or if you need to document more about the system, then that's the time to introduce Component and Code Diagrams. Remember, the deeper the level of detail you want, like using a Code Diagram, the more things change and the more you have to adjust this diagram, and this is an added cost on its own in terms of maintenance.

Architecture vs. Design

Where Does C4 Fit? This interesting debate discusses whether a very detailed diagram, like a Code Diagram, must be taken into consideration in software architecture, or if it is more about software design.

Architecture is basically concerned with higher-level decisions on the structure and the behavior of the system, while design in general covers the implementation of the single components.

This debate emphasizes the flexibility of the C4 Model—whether you use it strictly for architectural purposes or extend it into design is totally up to your team's needs.

Pros and Cons of Using the C4 Model

As with any approach, there are strengths and weaknesses associated with using the C4 Model. Here's a quick rundown:

Pros:

Standardized Approach: The C4 provides a lucid, consistent means to visualize the architecture, which can be quite helpful while onboarding new members into a team.
Flexible: You can choose how much detail to include, from high-level architecture to low-level code structures.
Clear Communication: Non-technical stakeholders can understand the high-level diagrams, thus enhancing communication across teams.

Cons:

Learning Curve: The learning curve may be involved in getting started if your team is not comfortable with the C4 Model.
Maintenance: Detailed diagrams-such as the Code or Component diagrams-may require frequent updates because the system is always evolving, hence adding to more maintenance work.

Conclusion

The C4 Model is a very useful tool for clear and structured visualization of software architecture. Whether it is for high-level overviews when starting or deep insights into the system's internal structure, C4 supports documenting architecture in a way that is understandable and maintainable.

With a small learning curve, the payoffs of using C4 far outweigh the initial setup effort. This is a great investment to maintain clarity and healthy software systems.

Resources

If you are more of a visual learner, I’ve created two YouTube videos to cover C4, one more focused on theory and another focused on practice.

You can find the first 3 diagrams here.

You can also check these amazing resources:

Introducing wontbreak

Rafael Câmara — Fri, 03 May 2024 16:47:44 +0000

Hello everyone!

I'm very happy to announce my second open-source project called wontbreak. You can find its source code on Github.

This is my first npm package, which aims to make your axios requests more resilient.

It implements 3 common resiliency patterns: timeout, retry, and circuit-breaker.

Please refer to the README in the project for a more in-depth analysis and usage of this project!

As always, please feel free to provide some feedback!

Latency vs Throughput

Rafael Câmara — Wed, 21 Sep 2022 20:36:53 +0000

In today's blog we are going to discuss the difference between latency and throughput. These are two important metrics when analysing the performance of our systems.

So let's just get right into it!

Latency

As a fancy definition of latency, we can say that latency is the amount of time it takes data to traverse from one part of your system to another.
When we think about latency, we think of a client-server architecture, and this specific latency is the amount of time it takes for a client to get a response from the server.

But there are other ways of latency. For example, reading a piece of data from memory or from disk.

In an ideal scenario, you would want to minimize the latency of your system, because this might make a big difference on the client side. The lower the client has to wait for his request, the happier it is.

There might be some tuning needed in order to make our latency lower. For instance, use networks with high speeds, make use of mechanisms such as cache or reading from memory (instead of disks), have geographically distributed systems (for example, when a game has a server in Europe and another in America).

Throughput

Throughput is the amount of work a machine can do in a given period of time. An example of this would be the amount of requests a server can handle in a second.

In an ideal scenario, we would want our system to serve as many requests as possible, meaning high throughput. If you run a business, the more clients you can serve, the higher the revenue you will get from it is.

Stuff you can do to make your system's throughput higher include have one super powerful server or have multiple servers to handle the requests. This is quite a debate on whether to use one powerful server or have multiple servers, but if your system serves a lot of traffic, chances are you're better off by having multiple decent servers.

Notes

There one important aspect we must have in consideration. We can’t conclude anything about latency/throughput, by taking in consideration the other one. Let me give you a couple of examples to clarify this.

First scenario: does low latency means high throughput?

The answer is no. For example, our server may be a really slow one (low throughput), but it is not serving requests at the moment. This means that my request will be served immediately by the server, thus resulting in low latency.

Second scenario: does low throughput means high latency?

Again, the answer is no. This example is tied to the one above. Just because our server is slow (low throughput), doesn't mean we will necessarily have high latency. Our server can handle a couple of requests and be really fast in serving them.

😁 I hope this has helped!

That's everything for now! Thank you so much for reading.

If you have any questions please feel free to drop them off.
Follow me if you want to read more about these kinds of topics!

Social Media Links:
LinkedIn
Twitter
Github

C# "using" keyword

Rafael Câmara — Thu, 05 May 2022 21:48:49 +0000

In today's tutorial, we are going to discuss one of the keywords we frequently need to use: the using keyword!

Let's get straight to it!

The using keyword can be used in two contexts:

As namespace directive
In using statement blocks

1. Namespace directive

There are three ways in which we can use using here:

Make use of namespaces (traditional usage)
Make aliases for namespaces
Use static methods from classes namespaces

Down below I will explain each one of them, with a simple example involving writing a message to the console.

1.1. Make use of namespaces (traditional usage)

As we know, to write a message to the console we must use our friend Console.WriteLine.
We have two ways of calling Console.WriteLine. The first one is by calling the fully qualified name, which in this case would be System.Console.WriteLine. The second one would be using the using keyword. The problem with the first approach is that, whenever we want to Console.WriteLine, we must prepend with System. Doing this once is fine, but imagine having to do so multiple times. Even further, imagine if we had a bigger namespace, say Amazing.Big.Complex.DomainNamespace, which would be needed to call every time we wanted to call a method. This would degrade very much the readability of our code.

In the following figure, you can see an example of this using statement, as well as the other "not so good" use case mentioned.

1.2. Make aliases for namespaces

Creating aliases for namespaces, at a visual glance, seems like creating a variable. In order to better explain this concept, please refer to the below image.

As you can see in the first line, we create kinda a variable to store an alias for a specific namespace. In this case, it would not be worth it to make it, but with a bigger codebase, it could make sense in order to organize and make things look easier to read. Beware that this is not a widely used practice!

After declaring the alias we use it in the method WriteMessageToConsoleWithAlias.

1.3. Use static methods from classes namespaces

In this example, the WriteLine method is a static method from a static class (Console class). Every time we want to execute the WriteLine method, we must call Console first. We can improve that by using the static class in the namespace. The following figure shows how to do so.

As you can see from the first line, we have inserted the static keyword and also added the Console class to the namespace. This will allow us to use the static methods inside the Console class in our code without always needing to write Console.WriteLine. You can see this inside the WriteMessageToConsoleWithStaticMethod, where we call the WriteLine method without needing to prepend the Console class.

2. using statement blocks

The using block statements are used when we want to create and manage object resources in a specific scope. When the scope ends, those resources are freed. Using the using block is important because there are types of objects that the Garbage Collector cannot clear, so we need to release such objects explicitly. Examples of such objects are file streams or database connections. Please refer to this article for more information on this topic.

If that might seem confusing, let's have a look at this simple, but clarifying, coding example, which writes a specific content to a file.

public void WriteToFile(string fileName, string content){
     using (StreamWriter writer = new StreamWriter(filename))
     {
          writer.WriteLine(content);
     } //after this, resources used are freed
}

The important aspect to notice here is that the objects we use in the parenthesis of the using statement must implement the IDisposible interface. This interface contains the Dispose method that will be called whenever the scope of the using block ends. This Dispose method objective should be cleaning the object mentioned before.

If we don't do what we mentioned before, and simply wrote two WriteLine methods from two StreamWriter, we would get an error (similar to the one you see in the figure down below).
That error occurs because the resources (from which file1.txt is one of them) that are used are not freed up like they are when we use them inside the using block.

But if, instead, you use the using blocks, you don't have this error, due to the freeing of the resources. The following image shows just that.

😁 I hope this has helped!

That's everything for now! Thank you so much for reading.

The source code for this tutorial can be found here.

If you have any questions please feel free to drop them off.
Follow me if you want to read more about these kinds of topics!

Social Media Links:
LinkedIn
Twitter
Github

C# extension methods

Rafael Câmara — Tue, 26 Apr 2022 20:32:58 +0000

In this tutorial, we will discuss how to use extensions methods in C# and the aspects to be aware of when doing so.

Definition

Extensions methods are methods that we can add to our code or third-party library, that allows to extend or add functionality.

When to use them or not is something that we will address later on, but for now, let's see a simple coding example to show this concept in action.

Coding example

Let's assume we are handed a third-party library whose only purpose is to log messages (in our case to the console). For simplicity's sake, the log class is written down below.

    /*
     * Let's assume this is given in a third party library
     */
    public class Logger
    {
        public void Log(string message)
        {
            Console.WriteLine($"Logged message: {message}");
        }
    }

Line 4: Declaration of the Logger class.
Line 6 to 8: Log method, that logs the message passed as argument.

If we needed to log a particular message, we just needed to instantiate the Logger class and call the log method.

So far so good.

But what if we wanted to give "special" treatment to error messages and print something like "An error occurred. This was the error: {INSERT_ERROR_MESSAGE}"? We don't have access to that source code, so we can't change the Logger library.

C# provides us a way of extending the functionality of the Logger library without modifying the original source code. Add the following code to the previous one shown for the library. The result of adding this would be having an extra method (the LogError method).

    public static class LoggerExtensions
    {
        public static void LogError(this Logger logger, string errorType, string message)
        {
            Console.WriteLine($"Error {errorType}: {message}");
        }
    }

Let's analyze what we just did.
Line 1: Created a static class that will contain all the extensions we can create for the Logger library.
Line 3 to 6: Created a static method, which represents the additional method we are adding to the library, that logs the error type and an error message.
Here we have a couple of things to notice:
- The first parameter has to be the class to be extended. To do so, we must first use the keyword this and then insert the class to be extended like a traditional parameter.
- After the first parameter, we must add the remaining wanted parameters, like a "regular" method. As we can see from the method, two parameters have been added: errorType and message.

The following image shows the log obtained.

In this case, we extended the functionality of a particular class, but we can also abstract this even more and consider extending functionality to interfaces. This means that every class that implements that interface will also be able to use the extended method.

Let's have a look at this in practice, with our Logger class.
Have in consideration the following code to be added and modified.

    public interface ILogger
    {
        void Log(string message);
    }

public static class LoggerExtensions
    {
        public static void LogError(this ILogger logger, string errorType, string message)
        {
            Console.WriteLine($"Error {errorType}: {message}");
        }
    }

    /*
     * Let's assume this is given in a third party library
     */

    public class Logger : ILogger
    {
        public void Log(string message)
        {
            Console.WriteLine($"Logged message: {message}");
        }
    }

    public class AnotherLogger : ILogger
    {
        public void Log(string message)
        {
            Console.WriteLine($"Logged message in another logger: {message}");
        }
    }

Changes that were inserted:

Line 1: Creation of the ILogger interface, containing the important log method.
Line 3: Log method to be implemented.
Line 5: Extension class that will contain our extension methods.
Line 7 to 10: Extension method created. As we can see from the method's signature, everything that implements the ILogger interface will have this method available.
Line 16: Created a Logger class that implements the aforementioned interface.
Line 24: Create another Logger class. The purpose of this is to check that every class that implements that interface will have the extension method created available.

Notice the static class we created for extensions and compare it with the same class from the previous example. Notice the difference? In our first example, we were extending the Logger class, but now we extended the interface ILogger, and the impact of this is that, as mentioned before, every class that implements the interface will access the extension method.

If we now instantiate Logger and AnotherLogger objects, we can see that the extension method is available to us.

The following image shows precisely a possible execution output.

One last final piece of information to have in consideration is that you can also have extension methods in enums. The rationale behind it is the same as with interface, so we won't go into much detail (also because it's not as common to do extension methods in enums).

Before moving on, if you want to take a look at the source code, you can find it here.

😁 I hope this has helped!

That's everything for now! Thank you so much for reading.

If you have any questions please feel free to drop them off.
Follow me if you want to read more about these kinds of topics!

Social Media Links:
LinkedIn
Twitter
Github

SOLID principles explained

Rafael Câmara — Wed, 09 Mar 2022 22:14:07 +0000

The SOLID principles are a set of good practices of the Object-Oriented Design (OOD) world. We should have them in consideration when producing our software if we want it to be more easily scalable, maintainable, and extended.

SOLID is an acronym, and each character of this acronym refers to an OOD principle, explained down below.

S - Single Responsibility Principle

One class should have only one responsibility. Sometimes you can see this principle written as "One class should only have one reason to change". All of this means that a class should only do one job, and do it right!

Let's take a look at a small coding example.

Say we have a class responsible for managing our users, whose code can be seen below.

public class User {
    private String name;
    private int age;

    public User(int name, int age){
        this.name = name;
        this.age = age;
    }

    public void saveUserToDatabase(){
        //implementation detail
    }

    //getters and setters
    ...
}

As you can see from the above code, besides having the basic getters and setters, this class is also responsible for saving the user in the database.

The previous class, being a data container, should only change if changes in our data model occur. With our current class that doesn't happen, because we have a second reason to change. Every time we want to change the database logic, we will have to change our class, and that breaks the Single Responsibility Principle.

The code below shows an example of the refactor we needed to do to have obedience to this principle.

public class User {
    private String name;
    private int age;
    private InfoPersistenseProvider database;

    public User(int name, int age, InfoPersistenseProvider database){
        this.name = name;
        this.age = age;
        this.database = database;
    }

    public void saveUserToDatabase(){
        this.database.saveToDatabase();
    }

    //getters and setters
    ...
}

public class InfoPersistenseProvider{

    public InfoPersistenseProvider(){}

    public void saveToDatabase(User user){
        //implementation detail
    }

    //getters and setters
    ...
}

As you can see from the previous code example, what we did was remove the database logic to a separated class.
Let's resume the example of changing the database type logic. Instead of changing the User class code, we only change the class that holds such logic, which in our case is the InfoPersistenseProvider class. If tomorrow we wanted to change such logic as well, we would only change in the proper place, which would always comply with the Single Responsibility Principle.

O - Open/Closed Principle

A class should be open for extension but closed for modifications. This means that we can add new functionalities without changing the existing code of the "base" class (that was extended).

Now let's take a look at a small coding example below, where we compute the user's interest in a specific video content, based on its previous consumption habits, for example.

public class Video{
    private String type;

    //...

    public double computeUserInterest(){
        if(this.type.equals("Movie")){
            //compute movie interest
        }else if(this.type.equals("TVShow")){
            //compute TVShow interest
        }
    }
}

What happens if you want to add 10 new video types to our platform? Our if-else would become gigantic. This example, where we constantly add if blocks, represents a classic example of the violation of the Open/Closed principle.

How can we obey to this principle?
In the code block below we show how.

public interface Video{
    public double computeUserInterest();
}

public class Movie implements Video{
    public double computeUserInterest(){
        //implementation detail
    }
}

public class TVShow implements Video{
    public double computeUserInterest(){
        //implementation detail
    }
}

Now, what happens if you want to add a new video type to our platform? You just need to make the class implement our interface. This makes our code cleaner and, more important, obeying to the Open/Close principle.

L - Liskov Substitution Principle

In practical terms, this principle states that if you have a parent class and one of its subclasses, you can replace the parent class by the subclass and still have valid behavior. This is the basic behavior we find in the OOP principle inheritance, meaning the subclass should be able to do everything its parent class does.

Let's analyze the upcoming block of code to understand this concept better!

public class Movie{
    public void play(){
        //implementation detail
    }

    public void increaseVolume(){
        //implementation detail
    }
}

public class Joker extends Movie{

}

public class ASilentMovie extends Movie{
    @Override
    public void increaseVolume(){}
}

Let's say we have our Movie superclass, which has two main actions: play (which starts the movie) and increaseVolume (which increases the movie's volume). This logic will work in most of the movies produced in today's day and age, but there is a market niche for silent movies which, as we all know, do not have any volume.

Do we have a correct behavior if, all of sudden, in our code we replaced a Movie object with another object that represents a silent movie? The answer is NO. No, because of the increaseVolume action. It is not correct to say "I will increase the volume of a silent movie", because there is no such thing as the concept of volume in these kinds of movies! This means that we don't obey the Liskov Substitution Principle.

I - Interface Segregation Principle

According to this principle, a class should not be forced to implement methods that it does not depend upon. A nice rule of thumb here is if you detect that you are making a dummy/empty implementation of a method (like the increaseVolume in the ASilentMovie class in the previous example), you are breaking this principle. The purpose here is to have our classes have only the methods that they need to perform their jobs.

Let's continue with our previous movie example, but a bit refactored, to see this principle in action.

public interface Movie{
    public void play();
    public void increaseVolume();
}

public class Joker implements Movie{
    public void play(){
        //implementation detail
    }

    public void increaseVolume(){
        //implementation detail
    }
}

public class ASilentMovie implements Movie{
    public void play(){
        //implementation detail
    }

    public void increaseVolume(){
        //implementation detail [PROBLEM HERE]
    }
}

As we saw from the previous Movie example, there was a problem when we tried to increase the volume of a silent film. We were breaking the Liskov Substitution Principle. As you can now see, and as previously mentioned, we are also breaking the Interface Segregation principle, because the ASilentMovie class is depending(implementing) on a method that is not used.

We can refactor this to comply with the Interface Segregation Principle, as follows.

public interface MoviePlayManager{
    public void play();
}

public interface AudioManager{
    public void increaseVolume();
}

public class Joker implements MoviePlayManager,AudioManager{
    public void play(){
        //implementation detail
    }

    public void increaseVolume(){
        //implementation detail
    }
}

public class ASilentMovie implements MoviePlayManager{
    public void play(){
        //implementation detail
    }
}

As you can see, our ASilentMovie class only depends on the methods it actually uses!

D - Dependency Inversion Principle

According to this principle, your classes should depend only on abstractions and not on particular implementations.

This might be hard to visualize, but have the following code example in consideration.

public class ComedyCategory{

}

public class Movie{
    private String name;
    private ComedyCategory comedyCategory;

    public Movie(String name, ComedyCategory comedyCategory){

    }

    public ComedyCategory getCategory(){
        return this.comedyCategory;
    }

    public void setCategory(ComedyCategory comedyCategory){
        this.comedyCategory = comedyCategory;
    }
}

Take a closer look at the movie class. It has two fields, which are the movie name and the movie category, which is a specific class with its own specificity and characteristics.

What happens with the example I just gave you is that our movie class is depending on a specific implementation of a category (in this case the comedy category). With this, we are creating a tight coupling between our Movie class and the ComedeCategory class. We want to avoid these tight couplings.

One way we can do this is by creating the abstraction/interface of a category and having all existing categories inherit/implement it.

The following refactoring tries to show this in practice.

public interface Category{

}

public class ComedyCategory implements Category{

}

public class Movie{
    private String name;
    private Category comedyCategory;

    public Movie(String name, Category comedyCategory){

    }

    public ComedyCategory getCategory(){
        return this.comedyCategory;
    }

    public void setCategory(Category comedyCategory){
        this.comedyCategory = comedyCategory;
    }
}

As you can see, now our Movie class only depends on the abstraction of the category and not on a specific implementation of a category. What does this mean in practical terms?

With our first approach, to instantiate the Movie class, we should have something like Movie joker = new Movie("Joker", new ComedyCategory()). If we tried and did Movie joker = new Movie("Joker", new DramaCategory()), we would get an error!

With our refactored approach, either way would work (the second one would work if DramaCategory implemented Category, of course). We gain flexibility in which category to place our movie at. This flexibility, which can be more generalized in our projects, is one of the major advantages of obeying this principle. Another one is that our applications get more decoupled.

😁 I hope this has helped!

That's everything for now! Thank you so much for reading. If you are more of a visual learner please refer to this amazing article, which explains the previous concepts in a more visual way!

If you have any questions please feel free to drop them off.
Follow me if you want to read more about these kinds of topics!

Social Media Links:
LinkedIn
Twitter
Github

DEV Community: Rafael Câmara

Ports and Adapters Architecture (Hexagonal Architecture) in practice with .NET

The anatomy of a use case

What is a use-case

How to structure a use-case

Inside the hexagon

Driven Adapters (Right side of the hexagon)

Driver Adapters (Left side of the hexagon)

Tests as a driver/driven mechanism

Final

Ports and Adapters (Hexagonal Architecture)

What is the Ports and Adapters architecture

Conclusion

Application Monitoring: Black-Box vs White-Box

C# LINQ Any Explained

Any in code

Resources

Downstream Resiliency: The Timeout, Retry, and Circuit-Breaker Patterns

What is Downstream Resiliency?

Timeouts

Retries

Circuit-Breaker

Conclusion

Resources

Automate Your C# Library Deployment: Publishing to NuGet and GitHub Packages with GitHub Actions

What is a NuGet package?

Sample library code

Configuring the continuous integration (ci) workflow file

Publishing to GitHub Packages with GitHub Actions

When to trigger a package publish

What steps are involved

Analyzing the generate-version job

Analyzing the package-and-publish-lib job

Choosing the appropriate .NET version (step Setup .NET)

Generating the NuGet package (step Generate NuGet package)

Publishing this NuGet package (step Publish NuGet package)

Creating a GitHub secret

Publishing to NuGet Feed with GitHub Actions

Creating a NuGet api-key

Ready. Set. Action.

How to use your custom NuGet packages

Adding metadata to the published NuGet package

Resources

C4 Model - The Basics

What is the C4 model?

Why Use C4?

4 Levels of the C4 Model

Context Diagram

Container Diagram

Component Diagram

Code Diagram

When to Use Different Levels of C4

Architecture vs. Design

Pros and Cons of Using the C4 Model

Conclusion

Resources

Introducing wontbreak

Latency vs Throughput

Latency

Throughput

Notes

C# "using" keyword

1. Namespace directive

1.1. Make use of namespaces (traditional usage)

1.2. Make aliases for namespaces

1.3. Use static methods from classes namespaces

2. using statement blocks

C# extension methods

Definition

Coding example

SOLID principles explained

Now, what happens if you want to add a new video type to our platform? You just need to make the class implement our interface. This makes our code cleaner and, more important, obeying to the Open/Close principle.

Analyzing the `generate-version` job

Analyzing the `package-and-publish-lib` job

Choosing the appropriate .NET version (step `Setup .NET`)

Generating the NuGet package (step `Generate NuGet package`)

Publishing this NuGet package (step `Publish NuGet package`)