DEV Community: Mirza Leka

How to build a reusable Excel export service in ASP.NET Core

Mirza Leka — Sat, 30 May 2026 09:36:59 +0000

This article will teach you how to export any list into Excel in C# using the ClosedXML library.

Steps to complete

Create the data model with dummy data that we'll export into Excel.
Create ExportExcel interface methods that accept any type of List (using IEnumerable<T>) and a Dictionary List and export a byte array.
Create extension methods and convert the provided data into rows and columns (using DataTable).
Create a service class that implements the interface methods and export the data table into a Memory Stream (byte array) using ClosedXML.
Create one API endpoint that exports data in memory into Excel. Create another endpoint that exports incoming (custom) request data into Excel.
Wire up dependencies.

Project structure


  ├── Program.cs                        ← Project startup & dependency injection
  │
  ├── controllers /
  │   └── ExportToExcelController.cs    ← API entry point

  ├── services /
  │   ├── IExportToExcelService.cs      ← Export Excel interface
  │   └── ExportToExcelService.cs       ← Export Excel concrete class
  │
  ├── models /
  │       ├── Car.cs                    ← Car class definition & dummy data
  │       ├── ExcelResponse.cs          ← Wrapper class for excel file name and data
  │       └── ExportExcelRequest.cs     ← Request class for that accepts any kind of list that will be exported
  │
  └── extensions /
      └── IEnumerableExtensions.cs      ← Extension methods for List<T> and List<Dictionary>

1️⃣ Data model

I've created the dummy data model to demonstrate the dynamic implementation.

    public enum FuelType
    {
        Petrol,
        Diesel,
        Electric,
        Hybrid
    }

    public class Car
    {
        public Guid Id { get; set; }
        public string Name { get; set; }
        public string Manufacturer { get; set; }
        public int YearProduced { get; set; }
        public string Color { get; set; }
        public FuelType FuelType { get; set; }
        public int HorsePower { get; set; }
        public int NumberOfDoors { get; set; }
        public bool AutomaticTransmission { get; set; }
        public double AverageFuelConsumption { get; set; }
        public int MaxSpeed { get; set; }
        public decimal Price { get; set; }

        public static List<Car> GetCars() { ... }

    }

The model has a static method GetCars() that returns hardcoded data that will be exported to Excel. You can find full data in the example Gist.

2️⃣ Create ExportExcel Service Interface

This is a very brief contract that takes the name of an Excel file and a generic list (e.g., Cars) and returns an ExcelResponse.

The second method works the same for the most part, but also allows for processing incoming data.

    public interface IExportToExcelService
    {
        ExcelResponse GetExcelFromEnumerable<T>(string fileName, IEnumerable<T> genericList);

        ExcelResponse GetExcelFromDictionaryList(string fileName, List<Dictionary<string, object>> dictionaryList);
    }

ExcelResponse is a reusable model that contains the file name and byte data.

    public class ExcelResponse
    {
        public string Name { get; set; }
        public byte[] Data { get; set; }

        public static ExcelResponse ToResponse(string name, byte[] data)
        {
            return new ExcelResponse()
            {
                Name = $"{name}.xlsx",
                Data = data
            };
        }
    }

The ExportExcelRequest model (used in the Controller) accepts any data to export to Excel. This will be used only on the POST endpoint.

    public class ExportExcelRequest
    {
        public string FileName { get; set; }
        public List<Dictionary<string, object>> Data { get; set; }
    }

3️⃣ Converting data into DataTables

The DataTable class represents a single in-memory table organized into rows and columns. You can learn more about DataTables here.

I like to create a separate extension methods class for all mappings.

    public static class IEnumerableExtensions
    { 
        public static DataTable ToDataTable<T>(this IEnumerable<T> genericList, string fileName) {}

        public static DataTable ToDataTable(this List<Dictionary<string, object>> dictionaryList, string fileName) {}       
    }

IEnumerable to DataTable

This method is useful whenever you have a collection and want to extract its data and map it into rows and columns.

    public static DataTable ToDataTable<T>(this IEnumerable<T> genericList, string fileName)
    {
        var table = new DataTable(fileName);

        // # Column headers
        // Extract property names from the dynamic list (using Reflection)
        var props = typeof(T).GetProperties();

        // Loop through the list of props and insert the name of each as DataTable column
        foreach (var p in props)
        {
            table.Columns.Add(p.Name, typeof(string));
        }

        // # Rows data
        foreach (var item in genericList)
        {
            // Create a new DataRow for the DataTable
            var row = table.NewRow();
            foreach (var p in props)
            {
                // Retrieve the value from the list (for each property) and add it to the row
                var value = p.GetValue(item);
                row[p.Name] = value?.ToString() ?? string.Empty;
            }
            table.Rows.Add(row);
        }

        return table;
    }

List of Dictionary to DataTable

This method is useful whenever you expose an endpoint that accepts a collection of data of unknown type and wish to format it into rows and columns.

    public static DataTable ToDataTable(this List<Dictionary<string, object>> dictionaryList, string fileName)
    {
        var table = new DataTable(fileName);

        // # Columns
        // Read dictionary keys
        if (dictionaryList.Count > 0)
        {
            foreach (var col in dictionaryList[0].Keys)
            {
                // Insert each key as column to data table
                table.Columns.Add(col, typeof(string));
            }
        }

        // # Rows data
        foreach (var row in dictionaryList)
        {
            // Create a new DataRow for the DataTable
            var dtRow = table.NewRow();

            foreach (var col in row.Keys)
            {
                // Retrieve the value for each key and add it to the row (belonging to that key)
                dtRow[col] = row[col]?.ToString() ?? string.Empty;
            }

            table.Rows.Add(dtRow);
        }

        return table;
    }

4️⃣ Create ExportExcel Service

Now, let's create the service and implement the interface.

Install ClosedXML from NuGet

Be sure to install the ClosedXML package which is needed to convert the DataTable into Excel.

Write the service

    public class ExportToExcelService : IExportToExcelService
    {
        public ExcelResponse GetExcelFromEnumerable<T>(string fileName, IEnumerable<T> genericList)
        {
            // Mapping List<T> into the table using the extension method
            DataTable dataTable = genericList.ToDataTable(fileName);

            // Converting DataTable into Excel
            var dataStream = CreateMemoryStream(fileName, dataTable);

            return ExcelResponse.ToResponse(fileName, dataStream.ToArray());
        }

        public ExcelResponse GetExcelFromDictionaryList(string fileName, List<Dictionary<string, object>> dictionaryList)
        {
            // Mapping List<Dictionary> into the table using the extension method
            DataTable dataTable = dictionaryList.ToDataTable(fileName);

            // Converting DataTable into Excel
            var dataStream = CreateMemoryStream(fileName, dataTable);

            return ExcelResponse.ToResponse(fileName, dataStream.ToArray());
        }

        /// <summary>
        /// Converts a DataTable into an Excel workbook stored inside a MemoryStream.
        /// </summary>
        /// <param name="worksheetName">Name of the sheet inside the Excel file.</param>
        /// <param name="dataTable">Tabular data to be written into the Excel sheet.</param>
        /// <returns>MemoryStream containing the serialized .xlsx file.</returns>
        private static MemoryStream CreateMemoryStream(string worksheetName, DataTable dataTable)
        {
            var stream = new MemoryStream();

            // Create in-memory Excel workbook
            using var xlWb = new XLWorkbook();

            // ClosedXML adds DataTable into the workbook
            xlWb.Worksheets.Add(dataTable, worksheetName);

            // Serialize the workbook into the MemoryStream (writes XLSX bytes)
            xlWb.SaveAs(stream);

            // Reset position so the caller reads from the beginning
            stream.Position = 0;

            return stream;
        }
    }

5️⃣ Create a new Controller

The API controller will have two routes:

GET — to export data from memory
POST — to export incoming data.

    [Route("api/[controller]")]
    [ApiController]
    public class ExportToExcelController(IExportToExcelService exportToExcelService) : ControllerBase
    {
        private readonly List<Car> _cars = Car.GetCars();
        private const string EXCEL_MIME_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";


        /// <summary>
        /// Demonstrates how to export list in memory (from DB query, HTTP response, etc.) into Excel.
        /// </summary>
        /// <param name="fileName">Name of the file to be exported.</param>
        /// <returns>File</returns>
        [HttpGet("DataInMemory/{fileName}")]
        public IActionResult ExportExcelFromDataInMemory([FromRoute] string fileName = "cars")
        {
            try
            {
                var excel = exportToExcelService.GetExcelFromEnumerable(fileName, _cars);
                return File(excel.Data, EXCEL_MIME_TYPE, excel.Name);
            }
            catch (Exception ex)
            {
                return StatusCode(500, ex.Message);
            }
        }

        /// <summary>
        /// Demonstrates how to export custom data into Excel.
        /// </summary>
        /// <param name="request">Name of the file and data to be exported.</param>
        /// <returns>File</returns>
        [HttpPost("CustomData")]
        public IActionResult ExportExcelFromCustomData([FromBody] ExportExcelRequest request)
        {
            try
            {
                var report = exportToExcelService.GetExcelFromDictionaryList(request.FileName, request.Data);
                return File(report.Data, EXCEL_MIME_TYPE, report.Name);
            }
            catch (Exception ex)
            {
                return StatusCode(500, ex.Message);
            }
        }

    }

The byte array will be returned as an Excel file via the File class in the Controller.

6️⃣ Dependency injection

Don't forget to inject the dependencies in the Program.cs file:

var builder = WebApplication.CreateBuilder(args);

// Dependency Injection
builder.Services.AddScoped<IExportToExcelService, ExportToExcelService>();

var app = builder.Build();

app.UseSwaggerExtension();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Demo

In-memory dummy data

Request:

Excel file:

Incoming custom data

Request body:

{
  "fileName": "Games",
  "data": [
    {
      "Title": "Call of Duty 4",
      "Publisher": "Activision",
      "ReleaseYear": 2007,
      "Genre": "FirstPersonShooter",
      "Setting": "ModernDay"
    },
    {
      "Title": "Splinter Cell",
      "Publisher": "Ubisoft",
      "ReleaseYear": 2002,
      "Genre": "StealthAction",
      "Setting": "ModernDay"
    },
    {
      "Title": "F1 25",
      "Publisher": "Electronic Arts",
      "ReleaseYear": 2025,
      "Genre": "Racing",
      "Setting": "ModernDay"
    }
  ]
}

Response:

That's it.
Be sure to download the whole code from the provided Gist.

See you in the next one 👋

Read environment variables from .env file in Angular

Mirza Leka — Thu, 28 May 2026 17:10:42 +0000

This article will teach you how to read environment variables from .env files into multiple Angular environments.

What is the .env file?

The .env file is a plain-text file used to store sensitive data and environment-specific configuration for a software application. Sample file:

GREETING=HELLO WORLD
SECRET=12345

By default, Angular uses the Environment files built into the framework (under src/environments), which are good for runtime but are publicly visible (and thus expose environment secrets). To get around this, we'll create a .env file for each environment (dev, staging, production) and load those variables into the Angular env file.

How are we going to implement this?

Create an .env file for each environment
Create a Node.js script that loads those .env files into memory
Use the script to override Angular environment project files with values from the .env files
Run the Angular build

This solution adds environment variables to the project before build time. So the latest build has variables baked in.

This solution is suitable if:

You're doing local development ✅
You're hosting the application (dist files) yourself ✅
You're building a Docker image (for any environment) ✅

It is not helpful if you need to add environment variables after the build (through some UI on AWS, GitHub, or elsewhere). ❌

You can grab the full code on this repository.

Implementation

1️⃣ Creating environment files

Create a separate .env file for each environment in the root directory:

.env.development
.env.staging
.env.production

Create a scripts directory inside your root project folder. Then, initialize the npm project within this folder.

> npm init -y
angular-multi-env\scripts\package.json:

{
  "name": "scripts",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

This will generate a package.json and a package-lock.json file.

Install the dotenv package to load environment variables from the selected .env file. This will generate the node_modules directory.

> npm i dotenv

Then create the index.js file in the scripts directory. This is where we'll write the script.

Finally, update the package.json file and add "type": "module".

2️⃣ Loading environment files within the script

The idea here is that when someone runs a build with a particular environment flag, we'll load the variables from the .env file based on that flag. So if you open a CLI and run:

> npm run build production

The script will look for the .env.production file and read variables only from that file. Likewise for development and staging environments.
We'll use the built-in Node.js command process.argv to read the "environment flag".

Start off by importing the required dependencies:

import dotenv from 'dotenv'; // the package we've just installed
import path from 'node:path'; // native node.js module
import fs from 'node:fs'; // native node.js module

Then read the (env) argument (flag) from CLI:

  const environment = process.argv[2];

  if (!environment) {
    throw new Error(`Missing environment flag: ${environment}!`);
  }

We'll also do some validation checks to stop anyone from adding dummy flags:

  const allowedEnvs = ['development', 'staging', 'production'];

  if (!allowedEnvs.includes(environment.toLowerCase())) {
    throw new Error(`Invalid environment selected: ${environment}!`);
  }

We need to set up a full environment name (and extension), which will be .env.[flag]:

  const envFile = `.env.${environment}`;

Now we have to locate this file on the disc:

  const currentWorkingDirectory = process.cwd();
  const pathToEnvFile = path.resolve(currentWorkingDirectory, envFile);

  if (!pathToEnvFile) {
    throw new Error(`Env file not found: ${pathToEnvFile}!`);
  }

The process.cwd() is another command built-into Node.js that returns current working directory. For me, it prints:

'D:\\Angular\\angular-multi-env'

So that the path to the .env file (pathToEnvFile) becomes:

D:\Angular\angular-multi-env\.env.development or
D:\Angular\angular-multi-env\.env.staging or
D:\Angular\angular-multi-env\.env.production

Next, we use the dotenv package to load the variables from the .env file by specifying the path:

  dotenv.config({
    path: pathToEnvFile
  });

The environment variables should appear in the process.env object. We can log the variables to the console to confirm that:

  console.table({
    environment,
    isProduction: process.env.production,
    greeting: process.env.greeting,
    apiBaseURL: process.env.apiBaseURL
  });

Quick Demo

angular-multi-env> node scripts/index.js development

┌──────────────┬─────────────────────────────┐
│ (index)      │ Values                      │
├──────────────┼─────────────────────────────┤
│ environment  │ 'development'               │
│ isProduction │ 'false'                     │
│ greeting     │ 'Hello DEV!'                │
│ apiBaseURL   │ 'http://localhost:3000/api' │
└──────────────┴─────────────────────────────┘

3️⃣ Load the Angular Environment files

Now we do the same thing for Angular. Locate the Angular environment file from the project folder:

  const angularEnvFile = `src/environments/environment.${environment}.ts`
  const pathToAngularEnvFile = path.resolve(currentWorkingDirectory, angularEnvFile);

  if (!pathToAngularEnvFile) {
    throw new Error(`Env file not found: ${pathToAngularEnvFile}!`);
  }

4️⃣ Override Angular environment files

Use the Node.js FileSystem module to read the contents of the selected environment as a string.

  const currentContent = fs.readFileSync(pathToAngularEnvFile, 'utf8');

If the file is empty, generate content. Otherwise, update it:

  let contentToOverride = '';

  if (!currentContent) {

    // If empty => create new content
    const newContent = `
    export const environment = {
  production: ${process.env.production === 'true'},
  apiBaseURL: '${process.env.apiBaseURL}',
  greeting: '${process.env.greeting}'
};
`;

    contentToOverride = newContent.trim();

  } else {

    // Update the existing contents of the Angular environment file (using RegEx)
    const updatedContent = currentContent
      .replace(/production: .*/, `production: ${process.env.production === 'true'},`)
      .replace(/apiBaseURL: .*/, `apiBaseURL: '${process.env.apiBaseURL}',`)
      .replace(/greeting: .*/, `greeting: '${process.env.greeting}',`);

    contentToOverride = updatedContent;
  }

  // Override the file content
  fs.writeFileSync(pathToAngularEnvFile, contentToOverride);

5️⃣ Add build scripts for each environment

Update the package.json of the Angular project. Include scripts to run the environment script (for each environment.ts file you have).

I have three files:

/src/environments/environment.development.ts
/src/environments/environment.staging.ts
/src/environments/environment.production.ts

So I'll add three scripts as prebuild scripts:

  "scripts": {
    "ng": "ng",
    "start": "ng serve",

    "prebuild:development": "node scripts/index development",
    "prebuild:staging": "node scripts/index staging",
    "prebuild:production": "node scripts/index production",

    "build:development": "ng build --configuration development",
    "build:staging": "ng build --configuration staging",
    "build:production": "ng build --configuration production",
  }

The way prebuild scripts work is, if you run a build script, e.g.

> npm run build:development

The NPM will run the prebuild:development first. So it will generate/update the environment.development.ts file and then run the selected script.

6️⃣ Final Demo

> npm run build:production

> angular-multi-env@0.0.0 prebuild:production
> node scripts/index production # Loading prebuild script

┌──────────────┬─────────────────────────┐
│ (index)      │ Values                  │
├──────────────┼─────────────────────────┤
│ environment  │ 'production'            │
│ isProduction │ 'true'                  │
│ greeting     │ 'Hello PROD!'           │
│ apiBaseURL   │ 'https://myapp.com/api' │
└──────────────┴─────────────────────────┘
Environment file updated!

> angular-multi-env@0.0.0 build:production
> ng build --configuration production

Initial chunk files   | Names         |  Raw size | Estimated transfer size
main-PQGIXNIB.js      | main          | 224.85 kB |                60.28 kB
polyfills-FFHMD2TL.js | polyfills     |  34.52 kB |                11.28 kB
styles-BT3MSNLR.css   | styles        |  54 bytes |                54 bytes

                      | Initial total | 259.42 kB |                71.62 kB

Application bundle generation complete. [1.991 seconds]

Update .gitignore file

Don't forget to add .env files and the scripts/node_modules directory to the .gitignore file.

# Environments
.env
.env.*

# Node_modules
/scripts/node_modules

# Also exclude changes from the Angular environment files
/src/environments/*

Once again, you can grab the full code here. If you're interested in learning how to Dockerize an Angular application, you can learn that here.

Bye for now 👋

Mermaid.js - Sketching diagrams using code

Mirza Leka — Sun, 10 May 2026 22:42:31 +0000

Mermaid.js is a text-based diagramming language that lets technical writers create and modify complex diagrams with simple code.

Example

Let's say you're making a family tree and want to visualize it with Mermaid.js:

:::mermaid
flowchart TD
A["Grandad"]
B["Dad"]
C["Me"]
:::

What this does is:

tells Mermaid.js that you want to use a flowchart diagram
to create three separate entities (boxes) with labels on them

Then add arrows to create a relationship between entities.

:::mermaid
flowchart TD
A["Grandad"]
--> B["Dad"]
B --> C["Me"]
:::

And there you go. But you can also apply different conditions (A => B or A => C):

:::mermaid
flowchart TD
A["Raining outside?"]
A --> |Yes| B["Take umbrella"]
A --> |No| C["Take sunglasses"]
:::

Mermaid supports a wide range of diagram types, including flowcharts, pie charts, sequence diagrams, UML diagrams, mind maps, etc, as well as colors and style kits for each.

I'm not going to go through each one of these because the official documentation is pretty detailed. I'm going to teach you how to use these diagrams today.

Where can I render the diagram?

You can preview Mermaid diagrams in any markdown file - GitHub repository, code editor of choice, or Notion.

GitHub markdown file

Create a markdown file in your GitHub repository and paste the snippet inside the code block:

:::mermaid
<YOUR-DIAGRAM-CODE>
:::

Surround the code block with three backticks or three colons, followed by the text "mermaid".

Here is a GitHub gist snippet I created for this demonstration.

Visual Studio Code

Just like on GitHub, create a markdown file inside the project and write your Mermaid.js script. To preview the diagram, the VSC has a markdown preview extension you can install in your editor.

Then, right-click on the markdown file (you wish to preview), choose Open With, and then choose the Markdown preview extension you've installed. The markdown should appear in the preview window.

Can I use AI?

It's actually one of my favorite things to do when I need to document a feature or when I'm getting started on a new project.

Just for reference, this is the original code that I gave to Claude Code:

[Route("api/[controller]")]
[ApiController]
public class GamesController(IGamesService _gamesService) : ControllerBase
{

    [Route("NewGameMode")]
    [HttpPost]
    public async Task<ActionResult<GetGameModeDTO>> NewGameMode([FromBody] CreateGameModeDTO dto)
    {
        try
        {
            return await _gamesService.CreateGameMode(dto);
        }
        catch (Exception ex)
        {
            return BadRequest(ex.Message);
        }
    }
}

    public async Task<GetGameModeDTO> CreateGameMode(CreateGameModeDTO gameMode)
    {
        var newGameMode = new GameModes
        {
            Title = gameMode.Title,
            ShortTitle = gameMode.ShortTitle,
            GameType = gameMode.GameType
        };

        _gamesContext.GameModes.Add(newGameMode);
        await _gamesContext.SaveChangesAsync();

        var mappedGameMode = GetGameModeDTO.ToResponse(newGameMode);
        return mappedGameMode;
    }

public class GetGameModeDTO
{
    public int ID { get; set; }
    public string Title { get; set; }
    public string ShortTitle { get; set; }

    public static GetGameModeDTO ToResponse(GameModes gameMode)
    {
        return new GetGameModeDTO()
        {
            ID = gameMode.ID,
            Title = gameMode.Title,
            ShortTitle = gameMode.ShortTitle
        };
    }

}

Now, Open Claude (or your LLM agent of choice) and ask it to analyze the project:

Hey Claude, analyze this project for me and summarize the language used, classes and core functionalities.

Then ask it to draw you a map:

Claude, can you describe what's going on from the games controller to the database using a Mermaid.js sequence diagram in the README.md?

And the output is a Mermaid.js diagram

:::mermaid
sequenceDiagram
    participant Client
    participant GamesController
    participant GamesService
    participant GamesContext
    participant SQL as SQL Server (Game_Modes)

    Client->>GamesController: POST /api/games/NewGameMode — { title, shortTitle, gameType }
    GamesController->>GamesService: CreateGameMode(CreateGameModeDTO)
    GamesService->>GamesService: new GameModes { Title, ShortTitle, GameType }
    GamesService->>GamesContext: GameModes.Add(newGameMode)
    GamesService->>GamesContext: SaveChangesAsync()
    GamesContext->>SQL: INSERT INTO Game_Modes (Title, Short_Title, Game_Type) VALUES (...)
    SQL-->>GamesContext: auto-generated ID
    GamesContext-->>GamesService: entity with new ID populated
    GamesService->>GamesService: GetGameModeDTO.ToResponse(entity)
    GamesService-->>GamesController: GetGameModeDTO
    GamesController-->>Client: 200 OK — { id, title, shortTitle }
:::

That you can preview in the markdown file.

Pretty neat, right? Much faster than drawing manually.
Here's another example of asking Claude to do my homework.

Summary

Mermaid.js is a pretty powerful tool when you need to sketch out functionalities to analyze or demonstrate. For more on Mermaid.js, feel free to visit the official documentation.

Until next time 👋

Message-Driven architecture vs REST-APIs

Mirza Leka — Thu, 26 Mar 2026 21:05:04 +0000

A question I often get: "Do you use message-driven architecture just because REST APIs are slow?" - Well… yes, but actually no. There’s much more behind that decision.

Why use Message-Driven architecture

Cross-device support

The messaging systems allow for real-time communication across servers, desktops, web & mobile apps — all decoupled and event-driven.

Asynchronous communication

REST API forces the sender to wait. Messaging lets you offload heavy work to background consumers while the app stays responsive.

Supports monoliths

The producer-consumer architecture can be used within a single service using in-process events.

Multi-destination delivery

With REST APIs, the sender needs to know the exact endpoint of each receiver. Messaging system publishes to a topic — whoever’s subscribed gets the message. No need to know who or where they are.

Retention

REST API fails if the receiving server is down. Messaging brokers store messages until consumers reconnect. With TTL, you can control how long unconsumed messages are retained before they are discarded.

Fault tolerance

Retries and dead‑letter queues are ideal for systems that favor built‑in recovery mechanisms to reduce the need for manual intervention.

But is messaging suitable for every backend?
No. You should also be aware of the drawbacks.

Drawbacks of MDA

Extra complexity

You need to manage brokers, consumers, retry policies, and observability.

Tracking requests is harder

Messages can fan out to multiple destinations. Tracing who picked up what, when, and what happened next is a challenge.

And because messaging is inherently push‑based...

No immediate response

Publishers don't wait for a response; the server can’t guarantee instant feedback to user actions.

Eventual consistency

Messaging systems can always send requests, but the downed services need to catch up later. This is not ideal for systems that require strict transactional processes.

Idempotency

The retry mechanism may redeliver the same message when a consumer fails or times out. The consumers must be idempotent to avoid processing the same request multiple times.
Idempotency doesn't spare REST APIs either.

Every software architecture is a trade‑off. Which direction do you lean into?

If you’re curious to dive deeper into Messaging or Event‑Driven Architecture, I’ve written a handful of articles on the topic.

Build Domain-driven HTTP services

Mirza Leka — Fri, 20 Feb 2026 04:21:37 +0000

You're building ASP .NET web APIs that need to communicate with external APIs.

The UserRegister API needs to insert a new user into the database, but also talk to three different services:

FileStoreService - uploads the user's profile photo
PDFService - generates a new document for the user to sign
EmailService - sends PDF as an email attachment.

You need to register an HTTP client for each external service you want to connect to from your service. A common approach is to use the HTTPClientFactory and the named clients as follows:

Add clients to the appsettings.json

{
  "FileStorageServiceUri": "https//file-storage-service:1234",
  "PDFServiceURI": "https//pdf-service:4567",
  "EmailServiceUri": "https//email-service:8883"
}

Register each (named) HTTP client in Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient("FileStorage", c =>
{
    c.BaseAddress = new Uri(builder.Configuration["FileStorageUri"]);
    c.DefaultRequestHeaders.Add("Accept", "application/json");
});

builder.Services.AddHttpClient("PDF", c =>
{
    c.BaseAddress = new Uri(builder.Configuration["PDFServiceURI"]);
    c.DefaultRequestHeaders.Add("Accept", "application/json");
});

builder.Services.AddHttpClient("Email", c =>
{
    c.BaseAddress = new Uri(builder.Configuration["EmailServiceUri"]);
    c.DefaultRequestHeaders.Add("Accept", "application/json");
});


var app = builder.Build();

// ...

app.Run();

In the user service, you'd invoke each service using the HTTP Client Factory.

    public class UserService(IHttpClientFactory httpFactory) : IUserService
    {
        private readonly IHttpClientFactory _httpClientFactory = httpFactory;

        public async Task<User> RegisterUser(UserDTO newUser)
        {
            //Invoke the File storage service
            var fileStorageClient = _httpClientFactory.CreateClient("FileStorage");
            HttpResponseMessage fsResponse = await fileStorageClient.PostAsJsonAsync("/upload", newUser.ProfilePhoto);

            if (!fsResponse.IsSuccessStatusCode)
            {
                // handle error
            }

            // handle response
            var base64Encoded = await fsResponse.Content.ReadAsStringAsync();

            // Save user to DB

            // Generate PDF

            // Send Email
        }
    }

If you continue down this path of

instantiating an HTTP client for each external service call and
validating the request before sending and handling the response after for each client
as well as writing the rest of the business logic in the same method

The RegisterUser method will become unreadable very soon.

The solution - Separate class per HTTP client

Move the business logic of each external service into its own service class:

FileStorageService
PDFService
EmailService

    public interface IFileStorageService
    {
        Task<string> UploadProfilePhoto(UserDTO newUser);
    }

Create an HTTP client that talks to an external service using the factory:

    public class FileStorageService(IHttpClientFactory httpFactory) : IFileStorageService
    {
        private readonly IHttpClientFactory _httpClientFactory = httpFactory;

        public async Task<string> UploadProfilePhoto(UserDTO newUser)
        {
            // Invoke the File storage service
            var fileStorageClient = _httpClientFactory.CreateClient("FileStorage");
            HttpResponseMessage fsResponse = await fileStorageClient.PostAsJsonAsync("/upload", newUser.ProfilePhoto);

            if (!fsResponse.IsSuccessStatusCode)
            {
                // handle error
            }

            // handle response
            return await fsResponse.Content.ReadAsStringAsync();
        }
    }

Also, inject the file storage service as Scoped or Transient:

builder.Services.AddScoped<IFileStorageService, FileStorageService>();

// ...

var app = builder.Build();

Now, the FileStorageService handles all calls to the File Storage microservice. All UserService has to do is inject the interface and invoke the upload method when needed:

    public class UserService(IFileStorageService fileStorageService): IUserService
    {
        private readonly IFileStorageService _fileStorageService = fileStorageService;

        public async Task<User> RegisterUser(UserDTO newUser)
        {
            var profileImage = await _fileStorageService.UploadProfilePhoto(newUser);

            // Save user to DB

            // Generate PDF

            // Send Eemail
        }
    }

The same applies to calls to the remaining external services.

The Problem

Even though you did write all the FileService-related logic into its own class, there is nothing stopping anyone from injecting an HttpClientFactory in a different class and creating another instance of the FilesStorageService:

    public class PetService(IHttpClientFactory httpFactory): IPetService
    {
        private readonly IHttpClientFactory _httpClientFactory = httpFactory;


        public async Task<Pet> CreatePet(Pet newPet)
        {
            var fileStorageClient = _httpClientFactory.CreateClient("FileStorage");
            // ...

        }
    }

In other words, you should prohibit access to the FileStorage HTTP Client to any class that does not use the designated service (FileStorageService).
How to do that?

Typed HTTP Clients

Rather than injecting the HTTP client and the FileStorage service separately, you'll combine the two into one injection:

// transient injection
builder.Services.AddHttpClient<IFileStorageService, FileStorageService>(client =>
{
    client.BaseAddress = new Uri(builder.Configuration["FileStorageServiceUri"]);
    client.DefaultRequestHeaders.Add("Accept", "application/json");
});
// delete the previous HTTP Client and Services.AddScoped<>() injection

This tells the project that only the FileStorage service has access to the FileStorage external service (via HTTP client).

It also means that the FileStorage service will no longer use the HttpClientFactory to create new clients. Instead, the service contains the HttpClient with a base address pointing to the FileStorage external microservice.


    public class FileStorageService(HttpClient fileStorageClient) : IFileStorageService
    {
        public async Task<string> UploadProfilePhoto(UserDTO newUser)
        {
            // Invoke the File storage service
            HttpResponseMessage fsResponse = await fileStorageClient.PostAsJsonAsync("/upload", newUser.ProfilePhoto);

            // ...
        }
    }

The UserService can continue calling the FileStorage Service using the interface (as before):

    public class UserService(IFileStorageService fileStorageService): IUserService
    {
        private readonly IFileStorageService _fileStorageService = fileStorageService;

        public async Task<User> RegisterUser(UserDTO newUser)
        {
            var profileImage = await _fileStorageService.UploadProfilePhoto(newUser);

            // ...
        }

But the UserService can't, nor can any other class, inject the HTTP Client Factory that talks to the FileStorage microservice. There simply isn't a name to provide:

var client = _httpClientFactory.CreateClient("There is no name");

Note: This solution isn't well-suited to singleton services.

Summary

This article explains how to use the dependency inversion principle to abstract business (domain) HTTP calls within services that handle them, preventing other services from making the same HTTP calls on their behalf.

Abstract text content in Angular

Mirza Leka — Sun, 08 Sep 2024 11:00:10 +0000

If you're developing websites, you're likely writing a lot of text in the component templates:

Writing text like this is not broken or buggy but rather tiresome to maintain for long-running projects. To improve this, you can create a file containing all the text for a particular feature and reuse it throughout the app by importing the correct keys.

This file can be:

JSON file
TypeScript file

I'll describe the pros and cons of both approaches.

I) JSON translations file

(1) Create a JSON file

In the root directory of your project, go to src/assets and create a new folder (wording) and a JSON file (wording.json):

📁 src 
|__ 📁 assets
|_____ 📁 wording
|_______ wording.json

And add your translations:

{
  "APP": {
    "TITLE": "Movies App",
    "DESCRIPTION": "The best site for movies"
  },
  "COMMON": {
    "BUTTON": "Peek In"
  },
  "MOVIES": {
    "BATMAN": {
      "TITLE": "Batman",
      "SERIES": {
        "THE_DARK_KNIGHT": {
          "TITLE": "The Dark Knight Series",
          "MOVIES": {
            "BATMAN_BEGINS": {
              "TITLE": "Batman Begins",
              "DESCRIPTION": "Bruce learns the art of fighting to confront injustice."
            },
            "THE_DARK_KNIGHT": {
              "TITLE": "The Dark Knight",
              "DESCRIPTION": "Lorem Ipsum"
            },
            "THE_DARK_KNIGHT_RISES": {
              "TITLE": "The Dark Knight Rises",
              "DESCRIPTION": "Lorem Ipsum"
            }
          }
        }
      }

    }
  }
}

(2) Update TSConfig

If needed, add resolveJsonModule: true to tsconfig.json compilerOptions to allow importing JSON files into ECMAScript modules:

{
  "compilerOptions": {
    "resolveJsonModule": true, // Add this line to tsconfig.json
  }
}

(3) Use the JSON file

Import the file directly into the component

// component file
import wording from '../../assets/wording/wording.json';

@Component({...}) 
export class HomeComponent implements OnInit {

  public pageText!: any;

  ngOnInit(): void {
    this.pageText = wording.MOVIES.BATMAN;
  }

}

Or create a service that imports all wording globally:

// translations.service.ts

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';

@Injectable({
  providedIn: 'root'
})
export class TranslationsService {

  public wording!: any;

  constructor(private http: HttpClient) {
    this.setTranslations();
  }

  private setTranslations() {
    this.http.get('./assets/wording/wording.json').subscribe(data => {
      this.wording = data;
     });
  }

}

And then inject the service into your component.

@Component({...}) 
export class HomeComponent implements OnInit {

  public pageText!: any;

  constructor(private readonly translationsService: TranslationsService) {}

  ngOnInit(): void {
    this.pageText = this.translationsService.wording.MOVIES.BATMAN;
  }

}

However, the downside of this approach is that you don't have any intellisense for the text content.

  <div class="movie-main-container">
    <span class="heading0">{{ pageText.TITLE }}</span>
    <!-- ..............No complaints here 👇 -->
    <div class="heading4">{{ pageText.HELLO_WORLD }}</div>
  </div>

To resolve this, you'd have to build a custom type or an interface around the whole wording.json file or the particular object ("Batman") you're using in the component.

II) TypeScript translations file

Another way to do this is to ditch the JSON file and create a Typescript file instead.

(1)

Create new wording.ts file anywhere in the src/app

// wording.ts
const WORDING = {
  APP: {
    TITLE: 'Movies App',
    DESCRIPTION: 'The best site for movies',
  },
  COMMON: {
    BUTTON: 'Peek In',
  },
  MOVIES: {
    BATMAN: {
      TITLE: 'Batman',
      SERIES: {
        THE_DARK_KNIGHT: {
          TITLE: 'The Dark Knight Series',
          MOVIES: {
            BATMAN_BEGINS: {
              TITLE: 'Batman Begins',
              DESCRIPTION:
                'Bruce learns the art of fighting to confront injustice.',
            },
            THE_DARK_KNIGHT: {
              TITLE: 'The Dark Knight',
              DESCRIPTION: 'Lorem Ipsum',
            },
            THE_DARK_KNIGHT_RISES: {
              TITLE: 'The Dark Knight Rises',
              DESCRIPTION: 'Lorem Ipsum',
            },
          },
        },
      },
    },
  },
};

export default WORDING;

(2) Create a class that reads from this file

You could import a new wordings.ts file in any desired component. However, I like to create a custom (UseWording) class that reads from this file.

// use-wording.ts

import WORDING from './wording';

/**
 * Wrapper for translation wording
 */
export default class UseWording {

  get useWording() {
    return WORDING
  }
}

(3) Inerit the UseWording class in your components

import { Component } from '@angular/core';
import UseWording from '../../../shared/translations/use-wording';

@Component({...})
export class HomeComponent extends UseWording {
  readonly pageText = this.useWording.MOVIES.BATMAN
}

With this, you can immediately see the intellisense in the template.

Additionally, you can create more class properties that target specific keys in the wording object:

@Component({...})
export class HomeComponent extends UseWording {
  readonly pageText = this.useWording.MOVIES.BATMAN;
  readonly movies = this.useWording.MOVIES.BATMAN.SERIES.THE_DARK_KNIGHT.MOVIES;
  readonly common = this.useWording.COMMON;
}

<div class="movie-main">
  <div class="movie-main-container">
    <span class="heading0">{{ pageText.TITLE }}</span>
    <div class="heading4">{{ pageText.SERIES.THE_DARK_KNIGHT.TITLE }}</div>
  </div>

  <div class="movie-main-cards">
    <div class="layout-centered">
      <div class="heading1">{{ movies.BATMAN_BEGINS.TITLE }}</div>
      <div class="heading4">
        {{ movies.BATMAN_BEGINS.DESCRIPTION }}
      </div>
      <button class="button-primary">{{ common.BUTTON }}</button>
    </div>
    <div class="layout-centered">
      <div class="heading1">{{ movies.THE_DARK_KNIGHT.TITLE }}</div>
      <div class="heading4">
        {{ movies.THE_DARK_KNIGHT.DESCRIPTION }}
      </div>
      <button class="button-primary">{{ common.BUTTON }}</button>
    </div>
    <div class="layout-centered">
      <div class="heading1">
        {{ movies.THE_DARK_KNIGHT_RISES.TITLE }}
        <div class="heading4">
          {{ movies.THE_DARK_KNIGHT_RISES.DESCRIPTION }}
        </div>
        <button class="button-primary">{{ common.BUTTON }}</button>
      </div>
    </div>
  </div>
</div>

Note that if your class component injects dependencies via the constructor, the constructor must contain a 'super' call.

export class MyComponent extends UseWording {

  searchAccountsForm!: FormGroup;

  constructor(
    private fb: FormBuilder
  ) {
    super(); // <-- this is mandatory
  }

And just like with JSON, if you need to change a title or a description, you do it in one place (wording.ts) instead of changing multiple files/components.

Wrapping up

This article demonstrates two ways of using wording in Angular components. Both methods have advantages and disadvantages.

Using the TypeScript file speeds things up and takes care of the intellisense, but it may not be suitable for working with multiple languages.

Using the JSON file requires some extra work, but it's beneficial when the exact translations are used across various apps built with different technologies (that support JSON format).

If you learned something new, don't forget to hit the follow button. Also, follow me on Twitter to stay updated with my upcoming content.

Bye for now 👋

Getting Started with LINQ (3/3)

Mirza Leka — Mon, 05 Aug 2024 21:16:48 +0000

Language Integrated Query or LINQ is a C# feature that allows you to query different data sources using a unified language syntax.

In the first two parts we learned what is LINQ, when it is used and then went through every-day operations, projection, filtering, sorting, set operations, aggregation, etc. If you're not familiar, I suggest taking a peek.

In this final part we'll go over methods to generate, partition, compare and join collections. Once again, we'll be working a List imported from JSON. Here, you can aquire the data as well as learn how to import it into C#.

GENERATORS

Empty Collection

Let's kick things off with creating empty collections. This is one way to declare an empty Students collection:

var = Enumerable.Empty<Student>();

Alternatively you can do this too:

var emptyCollection = new List<Student>();

In this example, imagine you have to return an empty collection from a method. Here is one way to do it:

    public IEnumerable<Student> GetStudents()
    {
        return Enumerable.Empty<Student>();
    }

Or declare a new empty List when the return type is List<T>:

    public List<Student> GetStudents()
    {
        return new List<Student>();
    }

If you're using .NET 8 or above you can reduce the number of steps by using a collection expression []. This works both for IEnumerable<T> and the List<T>:

    public IEnumerable<Student> GetStudents()
    {
        return [];
    }

    public List<Student> GetStudents()
    {
        return [];
    }

This also works when declaring empty collections:

List<Student> emptyCollection = [];

Range

This operator is used to generate an IEnumerable for a specified range:

IEnumerable<int> fiveNumbers = Enumerable.Range(1, 5);
// [1, 2, 3, 4, 5]

We can also use Range to generate a new collection of students:

IEnumerable<Student> newStudents = Enumerable.Range(1, 3).Select(count =>
{   // creates new Student for each count (1 - 3)
    return new Student()
    {
        ID = count,
        Name = "Placeholder",
        Country = "Placeholder",
        Age = count * 10
    };
});

Repeat

The Repeat operator generates a sequence that contains one repeated value. For example let's create 5 exact same students:

var repeatTimes = 5;

var csharpStudent = Enumerable.Repeat(new Student()
{
    ID = 1,
    Name = "C#",
    Country = string.Empty
}, repeatTimes);

PARTITION

Take, TakeLast, TakeWhile

The Take operator is used to limit the number of items in the collection.

IEnumerable<string> firstThreeNames = students.Select(s => s.Name).Take(3);  
// ["Mirza", "Armin", "Alan"]

IEnumerable<string> lastThreeNames = students.Select(s => s.Name).TakeLast(3);
// ["Eddy", "Abdurahman", "Amy"]

If the number specified is greater than the number of elements in the collection, the Take operator will trim the list at the last element (without throwing errors).

The TakeWhile operator returns all the elements that satisfy the specified condition and skips the rest. In this example, we limit the collection to students under 20 years old.

IEnumerable<string> teens = students
    .OrderBy(s => s.Age) // order from youngest to oldest
    .TakeWhile(s => s.Age < 20) // take younger than 20. ignore the rest
    .Select(s => s.Name); // take only names
// ["Mirza", "Farook", "Alan", "Eddy", "Abdurahman"]

Skip, SkipLast, SkipWhile

The Skip operator ignores all the elements until a point specified.

IEnumerable<string> lastFive = students.Skip(5).Select(s => s.Name);
// ["Raj", "Nihad", "Eddy", "Abdurahman", "Amy"] (remaining five)

IEnumerable<string> firstFive = students.SkipLast(5).Select(s => s.Name);
// ["Mirza", "Armin", "Alan", "Seid", "Farook"]

Here we're ignoring all the students that are under 20.

IEnumerable<string> teens = students
    .OrderBy(s => s.Age)
    .SkipWhile(s => s.Age < 20)
    .Select(s => s.Name);
// ["Armin", "Raj", "Nihad", "Seid", "Amy"]

The Skip and Take operators are commonly used when creating API pagination.

EQUALITY

SequenceEqual

The SequenceEqual operator is used to compare two collection to determine if they're equal or not. Let's demonstrate that with a simple example:

string[] countries = { "Bosnia", "UK", "Turkey" }; 
string[] countries2 = { "Bosnia", "UK", "Turkey" };

var isEqual = countries.SequenceEqual(countries2);
// true

If we'd change the order in either collection, the output would not evaluate to true.

string[] countries = { "Bosnia", "UK", "Turkey" }; 
string[] countries2 = { "Turkey", "Bosnia", "UK" };

var isEqual = countries.SequenceEqual(countries2);
// false

Back to the students collection, we can filter out student objects from the same country and compare the results:

// I created this to avoid writing the predicate `s => s.Country == "Bosnia"` twice
Func<Student, bool> isFromBosnia = s => s.Country == "Bosnia";

var studentsFromBosnia = students.TakeWhile(isFromBosnia);
var studentsFromBosnia2 = students.Where(isFromBosnia);

var isEqual = studentsFromBosnia.SequenceEqual(studentsFromBosnia2);
// true

JOINS

In this section we'll look at various ways to combine collections.

Zip

The Zip operator in LINQ pairs elements from two collections based on their positions (indexes). Let's create a new collection that will be paired with countries collection:

int[] countryCodes = { 387, 44, 20, 90, 91, 86, 1 };
var distinctCountries = students.DistinctBy(s => s.Country).Select(s => s.Country);

Now let's merge the two using Zip:

var countriesMerge = countryCodes.Zip(distinctCountries);

Concat

The Concat operator is used to concatenate (join) multiple collections together.

int[] nums = { 1, 2, 3, 4, 5 };
int[] newNums = { 100, 2, 300, 4, 500 };

var totalNums = nums.Concat(newNums);

The Concat operator seems similar to the Union. Both join operators collections. However, there are some differences when using the Concat:

No duplicate elements were removed
The order is preserved
The second collection is added to the end of the first

Let's join a collection of students ages with another randomly-generated ages collection and combine the result.

var studentsAges = students.Select(s => s.Age);
var eldersAges = Enumerable.Range(1, 10).Select(_ =>
{
    // I'm randomly generating an age between 65 & 100
    var random = new Random();
    int minAge = 65;
    int maxAge = 100;

    // Add adding random age into the eldersAges collection
    return random.Next(minAge, maxAge);
});

IEnumerable<int> combinedAges = studentsAges.Concat(eldersAges);
int totalAges = combinedAges.Count(); // 20

SelectMany

In the students.json file we're using, we know that each student object has a classes property, which represents an array of objects. How can we access those?

  {
    "ID": 1,
    "Name": "Mirza",
    "Age": 18,
    "Country": "Bosnia",
    "Classes": [
      {
        "ID": 1,
        "Title": "CAD"
      },
      {
        "ID": 2,
        "Title": "IT"
      }
    ]
  }

Bad way

The first choice would be to use the Select() projection operator:

var classesList = students.Select(s => s.Classes);

Since s.Classes is the collection as well, the variable classesList is of type IEnumerable<List<Classes>>. To get the list of titles we need to loop through outer collection and then use Select in the inner collection:

var classesList = new List<string>();

foreach (var stud in students)
{
    foreach (var cl in stud.Classes)
    {
        classesList.Add(cl.Title);
    }
}

However, there is a simpler way.

Better way

Using the SelectMany() projection operator we can drill into the inner array with ease.

IEnumerable<string> classTitles = students
    .SelectMany(s => 
        s.Classes.Select(s => s.Title)
    );

The SelectMany() acts like a join between the outer and inner array.

If we expand our student object with a new Hobbies property that contains a List:

public class Student {
....
    public List<string> Hobbies { get; set; } = [];
}

And then add a few to one of our students:

students.First().Hobbies = new List<string> { "Games", "Hiking", "Blogging" };

We can easily extract it once again the SelectMany():

var hobbies = students.SelectMany(s => s.Hobbies);

As opposed to doing:

var hobbiesList = new List<string>();

foreach (var stud in students)
{
    foreach (var hob in stud.Hobbies)
    {
        hobbiesList.Add(hob);
    }
}

Alternative SelectMany

The SelectMany() also has the second mode that accepts two parameters:

The first parameter is again the collection we're trying to extract
The second is a function containing data of the original collection and the inner we're trying to extract

var data = students.SelectMany(
    s => s.Hobbies,
    // original collection, inner collection
    (student, hobbies) => ... }
    );

Let's use this to create a combination of student names and hobbies:

var hobbies = students.SelectMany(
    s => s.Hobbies,
    (student, hobbies) => new { Name = student.Name, Hobbies = hobbies }
    );

The output is the name of thes student followed by their hobby.

Join

The Join operator is used to create a combination of two collections. For this example I created a new countries collection that we'll join with the students collection.

public class Country
{
    public int ID { get; set; }
    public string Name { get; set; }
    public string CapitalCity { get; set; }
    public string Continent { get; set; }
}

var countries = new List<Country>
{
    new Country() { ID = 1, Name = "Bosnia", CapitalCity = "Sarajevo", Continent = "Europe" },
    new Country() { ID = 2, Name = "UK", CapitalCity = "London", Continent = "Europe" },
    new Country() { ID = 3, Name = "Egypt", CapitalCity = "Cairo", Continent = "Africa" },
    new Country() { ID = 4, Name = "Turkey", CapitalCity = "Ankara", Continent = "Asia" },
    new Country() { ID = 5, Name = "India", CapitalCity = "New Delhi", Continent = "Asia" },
    new Country() { ID = 6, Name = "China", CapitalCity = "Beijing", Continent = "Asia" },
    new Country() { ID = 7, Name = "USA", CapitalCity = "Washington", Continent = "North America" },
    // Countries below have no students:
    new Country() { ID = 8, Name = "Croatia", CapitalCity = "Zagreb", Continent = "Europe" },
    new Country() { ID = 9, Name = "Serbia", CapitalCity = "Belgrade", Continent = "Europe" },
};

All students have a country property and we'll use that to link the two collections. Here is a basic join:

var studentsCountriesJoin = students.Join(
    countries,
    student => student.Country,
    country => country.Name,
    ((student, country) => ( student: student.Name, continent: country.Continent ))
);

Let's clarify what happened here.

The students is the outer collection that is joining the inner collection (countries). That's the part students.Join(countries)
Then we determine on what property we are going to join the two. We join two on the country name:

    student => student.Country,
    country => country.Name,

// SQL equivalent
ON Student.Country = Country.Name

Then we group the two (student, country)
And then we decide what we're going to return. In this case it's a collection with two properties, student and continent:

( student: student.Name, continent: country.Continent )

The outcome of the join

var studentsCountriesJoin = students.Join(
    countries,
    student => student.Country,
    country => country.Name,
    ((student, country) => ( student: student.Name, continent: country.Continent ))
);

is the following collection:

LINQ also allows join by multiple properties as well as applying multiple Joins. More on in the video.

Join & Group

Let's again join students and countries and then group students by continents they're from. The desired structure will look like:

{
  "Europe": [List of students where continent is "Europe"],
  "Africa": [List of students where continent is "Africa"],
  ...
}

var studentsByContinents = students
    .Join(
        countries,
        student => student.Country,
        country => country.Name,
// Note we do not need to specify { Name = student.Name, Continent = country.Continent }
// C# will do that for us
        ((student, country) => new { student.Name, country.Continent })
    )
    // Now comes the groupping part
    .GroupBy(g => g.Continent)
    .ToDictionary(
        // The continent is the key
        g => g.Key,
        // Value is the list of student names
        g => g.Select(sc => sc.Name).ToList());

GroupJoin

The GroupJoin operator is used to group elements from the second sequence (right side) that match each element from the first sequence (left side). It produces a hierarchical result set.

To get started, let's look again at our join of students and countries.

var studentsCountriesJoin = students.Join(
    countries,
    student => student.Country,
    country => country.Name,
    (student, country) => new { student.Name, Country = country.Name, country.Continent }
);

We know that the output here is going to be a collection containing a student name, country and the continent belong to that student. Now let's see the GroupJoin:

var studentsGroupedByCountry = countries.GroupJoin(
    students,
    country => country.Name,
    student => student.Country,
    (country, studentsGroup) => 
  new { country.Continent, Country = country.Name, Students = studentsGroup.Select(s => s.Name) }
);

Let's analyze what happened here:

First of all, we can see that we groupped students by country while joining
Second thing, the Name is represented as a collection with a Count property, not the actual student names
But the most importantly, we have countries without students. There are no students from countries at the bottom and the groupjoin() is indicating that.

In SQL terms,

The Join() operator represents the INNER JOIN as it produces the result where only the matching elements from both sequences are included (only the students and the countries with students).
The GroupJoin() operator represents the LEFT OUTER JOIN as it produces all records from the inner table (countries), and the matching records from the outer table (students). As we can see all countries are in the result, even those without matching students.

If we'd apply groupping again, the output would be the same thing we had above with Join & Group:

var studentsGroupedByCountry = countries.GroupJoin(
    students,
    country => country.Name,
    student => student.Country,
    (country, studentsGroup) => new { country.Continent, Students = studentsGroup.Select(s => s.Name) }
);

var groupedByContinent = studentsGroupedByCountry
    .GroupBy(x => x.Continent)
    .Select(g => new
    {
        Continent = g.Key,
        Students = g.SelectMany(x => x.Students).ToList()
    })
    .ToList();

Wrapping Up

That's all I wanted to share on LINQ. If you learned something new, don't forget to hit the follow button. Also, follow me on Twitter to stay up to date with my upcoming content.

Bye for now 👋

Getting Started with LINQ (2/3)

Mirza Leka — Mon, 29 Jul 2024 12:04:32 +0000

Language Integrated Query or LINQ is a C# feature that allows you to query different data sources using a unified language syntax.

In the first part we learned what is LINQ, when it is used and went through every-day operations. You can learn all about it in the article below:

In this blog we're moving forward with LINQ:

Set Operations
Quantifiers
Aggregation

Once again, we'll be working a List<Student> imported from JSON. Here, you can aquire the data as well as learn how to import it into C#.

SET OPERATIONS

LINQ Provides set operators to perform mathematical set operations on sequences or collections.

Distinct

The Distinct operator is used to filter out (remove) the duplicate elements from the collection:

IEnumerable<string> countries = students.Select(s => s.Country );
// ["Bosnia", "Bosnia", "UK", "Turkey", "India", "Turkey"...]

IEnumerable<string> distinctCountries = students.Select(s => s.Country).Distinct();
// ["Bosnia", "UK", "Turkey", "India", "Egypt"...]

DistinctBy

The DistinctBy operator takes a predicate that specifies the condition for the distinction:

IEnumerable<Student> distinctStudents = students.DistinctBy(s => s.Country)
// collection of students from distinct countries

This can be applied to a collection of countries as well:

var distinctCountries = students.DistinctBy(s => s.Country).Select(s => s.Country);
// unique countries

Union

The Union operator joins multiple collections into one leaves out the duplicate values. To make things more interesting I created another collection of students that we'll use alongside the original:

var newStudents = new List<Student>
{
    new Student() { ID = 11, Name = "Anz", Age = 19, Country = "Australia" },
    new Student() { ID = 12, Name = "Mohamed", Age = 23, Country = "Egypt" },
    new Student() { ID = 13, Name = "Amar", Age = 24, Country = "Bosnia" }
};

Let's say we want to take countries from both collections and create union of the two. Here's how that'd be done:

var originalStudentsCountries = students.Select(s => s.Country);
var newStudentsCountries = newStudents.Select(s => s.Country);

var countriesUnion = originalStudentsCountries.Union(newStudentsCountries);

As we can, the new collection is combination of the two other collections without duplicate entries.

UnionBy

The UnionBy speeds things up by reducing the number of steps needed to make the union.

var countriesUnion2 = students.UnionBy(newStudents, s => s.Country);
// the same result as above

Intersect

The Intersect operator is used to compare two collections and find the elements that are present in both sets. We'll once again compare the countries in two collections and inspect the result:

var originalStudentsCountries = students.Select(s => s.Country);
var newStudentsCountries = newStudents.Select(s => s.Country);

var countriesIntersection = originalStudentsCountries.Intersect(newStudentsCountries);
// ["Bosnia", "Egypt"]

The outcome is the distinct list of countries that are present in both collections.

IntersectBy

The logic can once again be simplified by applying the IntersectBy operator:

var countriesIntersection2 = students
    .IntersectBy(newStudents.Select(ns => ns.Country), s => s.Country);
// the same result as above

Except

The Except operator returns a combination of elements that are present in one collection, but not in the other. Basically the opposite of Intersect.

var originalStudentsCountries = students.Select(s => s.Country);
var newStudentsCountries = newStudents.Select(s => s.Country);

var countriesException = originalStudentsCountries.Except(newStudentsCountries);

The output is the list of countries present in the first, but not present in the second collection.

ExceptBy

The ExceptBy achieves the same as Expect with less steps:

var countriesException2 = students
    .ExceptBy(newStudents.Select(ns => ns.Country), s => s.Country);
// the same result as above

QUANTIFIERS

Contains

The Contains operator is used to validate if a specific item exists in the collection. For example, we can confirm that we have at least one student from Bosnia:

bool existingStudent = students.Select(s => s.Country).Contains("Bosnia"); 
// true

But what we don't have is a student that is 100 years old.

bool nonExistingStudent = students.Select(s => s.Age).Contains(100); 
// false

Any

Similarly to Contains, the Any operator is used to confirm if there is at least one student that meets specified criteria.

bool atLeastOneFromUK = students.Any(s => s.Country == "UK"); 
// true

All

The All operator is used to verify if all elements in the collection meet specified criteria:

bool allEighteenOrAbove = students.All(s => s.Age >= 18); 
// true

AGGREGATION

Count

The Count is used to to add together all the elements in a collection:

int totalStudentsCount = students.Count();

Console.WriteLine(totalStudentsCount); // 10

int studentsFromTurkeyCount = students.Where(s => s.Country == "Turkey").Count();

Console.WriteLine(studentsFromTurkeyCount); // 2

Min, Max, Average

These operators are used to determine the minimum, maximum and average element in the collection.

var ages = students.Select(s => s.Age);

var youngestAge = ages.Min(); // 18
var oldestAge = ages.Max(); // 24
var averageAge = ages.Average(); // 19.89

Sum

The Sum operator is used to aggregate all elements in the collections:

var ages = students.Select(s => s.Age);
int agesSum = ages.Sum();

Console.WriteLine(agesSum); // 199

GroupBy

The GroupBy operator is used to group items in the collection by one or more properties. For example, earlier we learned that we can retrieve a list of unique countries:

var countries = students
    .Select(s => s.Country)
    .Distinct();

The same can be achieved using the GroupBy operator.

var countries2 = students
    .GroupBy(s => s.Country)
    .Select(group => group.Key);

GroupBy groups by specified properties (Country)
Select is used to read values out of groupped collection
group is a groupped collection (IEnumerable<IGroupping<T>>)
The Key is the groupping property (Country)

The end result is the same as above.

Here is another example of using Groupby operator to calculate the occurrences of each country in the collection:

var countryOccurrences = students
    .GroupBy(s => s.Country)
    .Select(g => new { Country = g.Key, Occurrences = g.Count() });

Since the groupped collection (g) is an IEnumerable, we can call any of the LINQ operators (in this case Count).

Lastly, we can group the students by their age in dictionary structure, like:

{
  18: [List of students that are 18 years old],
  19: [List of students that are 19 years old],
  ...
}

var studentsGrouppedByAge = students
    .GroupBy(s => s.Age) // group by age
    .ToDictionary(g => g.Key, g => g.ToList() // form a dictionary
        .Select(s => new { Name = s.Name, Country = s.Country })); // select specific properties

Furthermore, we can print each group and each student by using a combination of foreach loops:

foreach (var studentsGroup  in studentsGrouppedByAge)
{
    foreach (var student in studentsGroup.Value) // we use .Value because studentsGroup is a dictionary
    {
        Console.WriteLine($"Name: {student.Name}, Country: {student.Country}");
    }
}

Other Chapters:

In the coming parts we'll dive deeper into LINQ.

Don't forget to hit the follow button. Also, follow me on Twitter to stay up to date with my upcoming content.

Bye for now 👋

Getting Started with LINQ (1/3)

Mirza Leka — Sun, 28 Jul 2024 10:55:02 +0000

Language Integrated Query or LINQ is a C# feature that allows you to query different data sources, such as:

In memory collections (arrays, lists, dictionaries)
SQL collections
XML collections

using a unified language syntax.

There are two ways to use LINQ:

Query syntax consist of a set of query keywords defined into the .NET Framework that resemble SQL-Like commands.
Method syntax consist of operator functions (extension methods) chained together using a declarative programming paradigm.

For this tutorial we'll use LINQ Extension method syntax.

Where can we use LINQ?

Language Integrated Query syntax works with any type of collection in C# that implements the IEnumerable interface, such as arrays, lists, dictionaries, etc. Simply put, whenever you see a type IEnumerable or type that implements the IEnumerable, you can use LINQ.

Setup

To speed things up, I've already created a collection of students in the JSON file. The Gist I wrote will explain how to import the JSON data into a C# collection.

Each student is a class containing properties:

public class Student
{
    public int ID { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
    public string Country { get; set; }
}

var student = new LINQTutorial();
List<Student> students = student.GetStudents();

The method GetStudents() on the student instance retrieves a collection of students populated using the JSON file. More in the Gist.

Now let's make use of various LINQ Operators to query the students data.

FILTERS

First & Last

The First() operator returns the first record in the collection:

var firstStudent = students.First();

Console.WriteLine($"Name: {firstStudent.Name}, Age: {firstStudent.Age}, Country: {firstStudent.Country}");
// Name: Mirza, Age: 18, Country: Bosnia

The opposite of First() is the Last() operator that returns the last record:

var lastStudent = students.Last();

Console.WriteLine($"Name: {lastStudent.Name}, Age: {lastStudent.Age}, Country: {lastStudent.Country}");
// Name: Amy, Age: 21, Country: USA

This is one way of using First() and Last() operators. The LINQ operators have an overload method that accepts a predicate and return the record/s that match the condition inside.

var firstStudent = students.First(x => x.Age == 19);

Console.WriteLine($"Name: {firstStudent.Name}, Age: {firstStudent.Age}, Country: {firstStudent.Country}");
// Name: Alan, Age: 19, Country: UK

var lastStudent = students.Last(x => x.Age == 20);

Console.WriteLine($"Name: {lastStudent.Name}, Age: {lastStudent.Age}, Country: {lastStudent.Country}");
// Name: Raj, Age: 20, Country: India

First/Last Or Default

What would happen if we'd query for first student with the age of 100?

var firstStudent = students.First(x => x.Age == 100);

Because there is no record of a student with age 100, the C# program execution will stop and throw an exception:

System.InvalidOperationException: Sequence contains no matching element

To prevent this we can use the FirstOrDefault() operator that works just the same as the First(), with an exception that it returns the default value (null for strings and objects, 0 for numbers) if no record meets the condition.

var firstStudent = students.FirstOrDefault(x => x.Age == 19); 
// {...} 

var nonExistingStudent = students.FirstOrDefault(x => x.Age == 100);
// null

var nonExistingStudentName = students
    .Select(s => s.Name)
    .FirstOrDefault(name => name == "Homer");
// null


var nonExistingStudentAge = students
    .Select(s => s.Age)
    .FirstOrDefault(age => age == 100);
// 0

The same applies for the Last() and LastOrDefault() operators.

ElementAt

This method is used to retrieve an element at a specific index.

var fifthStudent = students.ElementAt(4);

Console.WriteLine($"Name: {fifthStudent.Name}, Age: {fifthStudent.Age}");
// Name: Farook, Age: 18

That said, if you use an index that is not present, the exception will be thrown:

var nonExistingStudent = students.ElementAt(100);

System.ArgumentOutOfRangeException: Index was out of range.

So it's safer to use ElementAtOrDefault:

var nonExistingStudent = students.ElementAtOrDefault(100); // null

Where

The Where() operator is used to filter multiple elements. The output is an array of all elements that meet a specified criteria.

var studentsFromBosnia = students.Where(x => x.Country == "Bosnia");

foreach (var student in studentsFromBosnia)
{
    Console.WriteLine($"Name: {student.Name}, Age: {student.Age}");
}
// Name: Mirza, Age: 18
// Name: Armin, Age: 20

One thing to note about studentsFromBosnia is that is not of type List<Student>, but rather IEnumerable<Student>. The LINQ works in either way.

However, if you need to pass this collection to a method that takes an array or a list as a parameter, you can cast an IEnumerable to derived types.

BUILDERS

To convert an IEnumerable to an array simply do:

var studentsArray = studentsFromBosnia.ToArray(); 
// Array<Student>

To convert an IEnumerable to a list simply do:

var studentsList = studentsFromBosnia.ToList(); 
// List<Student>

To convert an IEnumerable collection to a dictionary, first restructure the data into an anonymous key-value pair object and then covert the object to dictionary.

var studentsDictionary = studentsFromBosnia
  .Select((stud, index) => new { index, stud }) // creating an anonymous object
  .ToDictionary(x => x.index, x => x.stud); // converting object to dictionary
// Dictionary<int, Student>

PROJECTION

Select

The Select operator is used to retrieve a list of specific properties from an IEnumerable, in this case List. For example, let's say we want to pick names of all students:

IEnumerable<string> names = students.Select(s => s.Name);

foreach (var name in names)
{
    Console.WriteLine(name); 
    // Mirza, Armin, Alan, Seid...
}

Or a combination of properties (Name & Country):

var customList = students.Select(s => new { Name = s.Name, Country = s.Country });

foreach (var student in customList)
{
    Console.WriteLine($"Name: {student.Name}, Country: {student.Country}");
}

SORTING

OrderBy

The OrderBy operator is used to order elements in the collections. For example, if we'd take ages of all students and put them into a collection:

var ages = students.Select(s => s.Age);

The outcome would be a collection sorted in the order the students were created. Applying the OrderBy, the ages are shown from smallest to largest:

var agesInOrder = students.OrderBy(s => s.Age).Select(s => s.Age);
// [18, 18, 18, 19, 19, 20, 20, 21, 22, 24]

It's clear that we have duplicate elements. We can fix that using the Distinct() operator:

var agesInOrder = students.OrderBy(s => s.Age).Select(s => s.Age).Distint();
// [18, 19,20, 21, 22, 24]

The OrderBy operator can also be applied after the Select:

var agesInOrder = students
    .Select(s => s.Age)
    .OrderBy(s => s) // sort by values in the collection (ages)
    .Distinct();
// [18, 19,20, 21, 22, 24]

In this instance, the ordering by ages is still hapening, but because we've already filtered the ages in the previous line, the OrderBy has less work to do.

OrderByDescending

The OrderbyDescending is doing the same but in the reversed order:

var agesInReverseOrder = students
    .Select(s => s.Age)
    .OrderByDescending(s => s)
    .Distinct();
// [24, 22, 21, 20, 19, 18]

ThenBy, ThenByDescending

The ThenBy operator is used to apply the additional sorting after the OrderBy.

var orderedByAgeAndCountry = students
    .OrderBy(s => s.Age)
    .ThenBy(s => s.Country)
    .Select(s => s.Name);
// ["Mirza", "Eddy", "Farook", "Abdurahman", "Alan"...]

var orderedByAgeAndCountry2 = students
    .OrderBy(s => s.Age)
    .ThenByDescending(s => s.Country)
    .Select(s => s.Name);
// ["Farook", "Eddy", "Mirza", ...]

Next Chapters:

In the coming parts we'll dive deeper into LINQ.

Don't forget to hit the follow button. Also, follow me on Twitter to stay up to date with my upcoming content.

Bye for now 👋

Managing Resources with Using in C#

Mirza Leka — Sun, 14 Jul 2024 20:20:00 +0000

The using statement is a poweful utility for automatic disposal of unused resources.

The base implementation works like this:

        using (var ch = new CustomHandler())
        {
            /* Do something with ch */
        }

The using statement is useful for preventing memory leaks by handling unmanaged resources like:

Close files that are no longer being used
Close database connections
Handle HTTP Client termination, etc.

In order to use the using statement for a given class, the class must implement the IDisposable interface:

class CustomHandler : IDisposable
{
    public void SayHello()
    {
        Console.WriteLine("Hello World!");
    }

    // coming from IDisposable
    public void Dispose()
    {
        Console.WriteLine("Handled dispose!");
    }
}

The automatic disposal can be verified by throwing an exception in SayHello() method.

class CustomHandler : IDisposable
{
    public void SayHello()
    {
        throw new Exception("Something went wrong!");
    }

    public void Dispose()
    {
        Console.WriteLine("Handled dispose!");
    }
}

I created a new class Main that creates an instance of CustomHandler().

Without Using

First test, no using.

public class Main
{
    public void LearnUsing()
    {
        var ch = new CustomHandler();
        ch.SayHello();
    }

}

var m = new Main();
m.LearnUsing();

The exception is thrown and the process is terminated as expected, but no resources were disposed.

Unhandled exception. System.Exception: Something went wrong!

Process finished.

With Using

public class Main
{
    public void LearnUsing()
    {
        using (var ch = new CustomHandler())
        {
            ch.SayHello();
        }
    }

}

var m = new Main();
m.LearnUsing();

This time around the resources are disposed sucessfully.

Unhandled exception. System.Exception: Something went wrong!

Handled dispose! <<<<<<<

Process finished.

Manual Disposal

By this point you probably asked yourself a question, why not use Try-Catch-Finally block? That works too, but Try-Catch doesn't dispose resources. It only handles errors.

In order to dispose resources in Try-Catch you'd need to manually call the dispose method:

        var ch = new CustomHandler();
        try
        {
            ch.SayHello();
        }
        catch (Exception ex)
        {
            /* Handle exception */
        }
        finally
        {
            // Manual disposal
            ch.Dispose();

            // I'm using finally here because it will be invoked
            // regardless if SayHello() is a success or an exception
        }

The using statement on the other hand calls the Dispose() method automatically.

Using in Existing Classes

As mentioned, any class that implements the IDisposable interface can be used within the using block.

FileStream

        using (FileStream fs = new FileStream("greetings.txt", FileMode.Open))
        {
            /* Write to file */
        }

HTTPClient

    public async Task LearnUsing()
    {
        using (var httpClient = new HttpClient())
        {
            var response = await httpClient.GetAsync("/api/getData");

            if (response.IsSuccessStatusCode)
            {
                /* Handle response */
            }
        }
    }

Just make sure you prefix the call to LearnUsing() with await keyword as it now a Task.

await m.LearnUsing()

SQL Connection

The using statement is also used when executing database queries without using any frameworks. To get started, install System.Data.SqlClient package via nuget package manager and import it as a dependency.

Then setup a connection string to your DB. For this I created a local DB via SQL Server.

To connect to your local DB set up a connection string in your C# application.

        string connectionString = "Server=<Server-Name>;Database=<Database-Name>;Integrated Security=True;";
// or in my case
        string connectionString = "Server=DESKTOP-F5;Database=Games;Integrated Security=True;";

Now using a combination of using statements:

Establish a connection with the database (SqlConnection)
Excute SQL Query (SqlCommand)
Read the response from the Table (SqlDataReader)

Here you can see how to nest the using statements.

        string connectionString = "Server=DESKTOP-F5;Database=Games;Integrated Security=True;";

        using (SqlConnection connection = new SqlConnection(connectionString))
        {
            try
            {

                await connection.OpenAsync();

                string sqlQuery = "SELECT * FROM Game_Types";

                using (SqlCommand command = new SqlCommand(sqlQuery, connection))
                {
                    using (SqlDataReader reader = await command.ExecuteReaderAsync())
                    {
                        while (await reader.ReadAsync())
                        {
                            Console.WriteLine(reader["Title"]); // Multiplayer 
                            // prints row data for each iteration
                        }
                    }
                }

            }
            catch (SqlException ex)
            {
                Console.WriteLine(ex.Message);
            }

            catch (Exception ex)
            {
                Console.WriteLine(ex.Message);
            }
        }

Note: If you're using an Entity Framework, the queries do not need to be wrapped with using. The DbContext class automatically disposes the resources.

For immediate disposal, the using statement can also be used inline (without curly brackets).

using (var fs = new FileStream("my-file.txt", FileMode.Open))
    Console.WriteLine("File open!");

That's all I have for today. Don't forget to hit the follow button. Also, follow me on Twitter to stay up to date with my upcoming content.

Bye for now 👋

Creating Global Styles for your Web App

Mirza Leka — Sat, 11 May 2024 10:14:48 +0000

This article will teach you how to set global styles for colors, fonts, layouts, buttons, and forms without using the CSS frameworks. I'll use SCSS in the Angular project, but feel free to use any tech that suits your project.

Global Styles

I like to sort styles by category:

Base
Layouts
Colors
Typography
Forms
Buttons

There is also a Styles.scss file where all others are imported.

// styles.scss
@import "./assets/styles/_base";
@import "./assets/styles/_layouts";
@import "./assets/styles/_colors";
@import "./assets/styles/_typography";
@import "./assets/styles/_forms";
@import "./assets/styles/_buttons";

Colors

Let's start with colors.
Create and define all colors within the :root to be globally used anywhere on the page.

// _colors.scss
:root {
 /* CSS variables */
  --primary-theme-color: green;
  --primary-theme-color-dark: darkgreen;
  --primary-theme-color-light: lightgreen;

  --secondary-theme-color: white;
  --secondary-theme-color-dark: darkgray;
  --secondary-theme-color-light: lightgray;

  --primary-white-color: white;
  --primary-black-color: black;
  --primary-error-color: red;
}

Then, classes that make these colors easily accessible for later uses:

// _colors.scss
  .primary-background {
    background: var(--primary-theme-color);
  }
  .primary-background-dark {
    background: var(--primary-theme-color-dark);
  }
  .primary-background-disabled {
    background: var(--primary-theme-color-light);
  }

  .secondary-background {
    background: var(--secondary-theme-color);
  }
  .secondary-background-dark {
    background: var(--secondary-theme-color-dark);
  }
  .secondary-background-disabled {
    background: var(--secondary-theme-color-light);
  }

.heading-primary {
  color: var(--primary-black-color)
}

.error-primary {
  color: var(--primary-error-color)
}

Base Styles

This is where you define styles related to HTML & Body tags, like app background, overflow or default margins.

// _base.scss
html,
body {
  height: 100%;
}
body {
  margin: 0;
  font-family: "Your font";
  background-color: var(--secondary-theme-color);
}

div {
  color: var(--primary-black-color);
}

Layout Styles

This is where you define set margins and padding used across the app.

For padding around content:

// _layouts.scss
.layout-sm {
  padding: 1rem;
}

.layout-md {
  padding: 1.5rem;
}

.layout-lg {
  padding: 2rem;
}

.layout-xl {
  padding: 4rem;
}

.layout-all-center {
  display: flex;
  justify-content: center;
  align-items: center;
  text-align: center;
}

And for margins:

// _layouts.scss

.layout-gap-sm {
  margin-bottom: 2rem;
}

.layout-gap-md {
  margin-bottom: 4rem;
}

.layout-gap-lg {
  margin-bottom: 6rem;
}

Typography

This is where you set font sizes and thickness.

// _typography.scss

/* font-weight */
$font-weight-light: 300;
$font-weight-semi-bold: 500;
$font-weight-bold: 600;

/* font-size */
$heading-title-size: 3rem;
$heading-subtitle-size: 2rem;
$heading-caption-size: 1.5rem;
$heading-default-size: 1.2rem;
...

To make fonts easily accessible through the app, define classes that wrap font styles.

// _typography.scss

.heading-title {
  font-size: $heading-title-size;
  font-weight: $font-weight-bold;
  margin: 0.5rem;
}

.heading-subtitle {
  font-size: $heading-subtitle-size;
  font-weight: $font-weight-light;
  margin: 0.5rem;
}

.heading-subtitle-bold {
  font-size: $heading-subtitle-size;
  font-weight: $font-weight-bold;
  margin: 0.5rem;
}

.heading-subtitle-semi-bold {
  font-size: $heading-subtitle-size;
  font-weight: $font-weight-semi-bold;
  margin: 0.5rem;
}

...

Forms

This file is used when styling common form elements.

// _forms.scss
.form-group {
  /* styles */
}

.form-label {
  /* styles */
}

.form-input {
  /* styles */ 
}

Buttons

Finally, the stylekit for buttons.

// _buttons.scss
.default-button-styles {
  height: ...
  box-sizing: border-box;
  border-radius: ...;
  padding: ...;

}

.button-primary {
  //Other classes inherit the default
  @extend .default-button-styles;
  background: var(--primary-theme-color);
  color: var(--primary-white-color);
  cursor: pointer;
  /* styles */

  &:hover {
      /* styles */
  }
}

.button-primary-disabled {
  @extend .default-button-styles;
  cursor: default;
  background: var(--primary-theme-color-light);
  color: var(--primary-white-color);
  /* styles */
}

.button-secondary {
  @extend .default-button-styles;
  background: var(--secondary-theme-color);
  color: var(--primary-black-color);
  /* styles */
}

Wrapping up

Building an app from scratch is a difficult process. That's why creating a proper style kit from the get-go and following the guidelines is important. It's a big first step, but it will surely make things easier in further development.

That's all I have for today. Don't forget to hit the follow button. Also, follow me on Twitter to stay up to date with my upcoming content.

Bye for now 👋

Node.js PM2 Orchestration Explained

Mirza Leka — Wed, 24 Apr 2024 20:56:47 +0000

Meet Joe.
Joe is a Node.js developer who has just created an awesome Web application. He hosted a virtual machine (on AWS EC2, Digital Ocean, Linode, etc.), started an app (using node app.js), made himself a drink, and sat back to welcome the hordes of happy fans.

A few hours go by and customers begin to complain. The server seems to be struck by a lighting. It's no longer responding.
Joe opens up a VM, and Node.js is no longer running. No biggie, run node app.js again and the app is up and running again.

A few more hours go by and the same issue occurs again. It was all running well in localhost, but the high traffic is causing the server to behave unexpectedly in production. What can Joe do?

Enter PM2, the process manager for Node.js.

Process Managers enhance Node.js applications by allowing:

monitoring the running services locally and in production
running system administration tasks like (starting and stopping applications, without downtime) aka orchestration,
logging metrics
load balancing, etc.

Getting Started with PM2

To get started, create a simple server using Express.js:

$ npm init -y
...\Mirza\first-pm2-app\package.json:

{
  "name": "first-pm2-app",
  "version": "1.0.0",
  "description": "",
  "main": "app.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

$ npm install express

With basic packages set up, create an app.js file and paste the following code:

// app.js
const app = require('express')();

app.get('/', (req, res) => {
  res.send('hello world');
});

app.listen(3000, () => {
 console.log('Server started on port 3000!');
});

PM2 is an NPM package installed globally on the system

npm install -g pm2

and is then used to run the JavaScript projects on your system, just like using the node command:

pm2 start app.js

Notice that we didn't get the log "Server started on port 3000!" printed as would normally happen when running node app.js.
Moreover, PM2 kicked us out of the long-running loop. If you go to the localhost:3000, you can verify that the server is up.

The server is up and running in the back.

How Can PM2 Fix Joe's Problems?

Process Management

PM2 lets you manually start, list, and stop active processes.

You can list out the running PM2 servers: pm2 list

You can stop a single server: pm2 stop app.js or via index pm2 stop 0

Or all at once: pm2 stop all.

You can delete a saved (cached) server configuration: pm2 delete app or pm2 delete 0.

Or all at once: pm2 delete all.

Just like with Nodemon, you can reload the server on changes: pm2 app.js --watch.

Self-Recovery

Instead of running the Node.js application via node app.js, use pm2 start app.js. By running the app like this, PM2 will automatically recover the app from crashes - simply put, it automatically restarts the server if it fails.

Scaling & Loadbalancing

By default, even if you're running the app on a multi-core CPU (server), Node.js runs an application on a single CPU core.
If you have high traffic it means that all requests are going to the single CPU instance while the rest are doing nothing.

The idea behind load balancing is to distribute the traffic across multiple cores:

2 pm2 start app.js -i 2
4 pm2 start app.js -i 4
8 pm2 start app.js -i 8
all of them pm2 start app.js -i max

Node.js uses a specific pattern for load balancing where all requests go to one core (master process) and if get occupied, it will automatically distribute the requests to other cores (processes). If the request count drops, so do the occupied cores.

The result is an app that can handle large traffic.

Monitoring & Logging

Running pm2 monit app.js lets you monitor the stats of your application (CPU & Memory Usage) as well as display logs in real time.

Additionally, you can display logs per process or application:

pm2 logs <processname> or
pm2 logs <app-name>

PM2 Main App

PM2 lets you monitor metrics on their main website.

Start by registering the app using the official guide.

Once linked with the official PM2 Keymetrics site, you should see your app metrics displayed.

Final Words

PM2 is a powerful process manager that helps you orchestrate your applications using a few commands, while you, like Joe, are resting on the beach somewhere in Hawaii. For more on PM2, be sure to check the official docs.

For everything else awesome, hit the follow button. Also, follow me on Twitter to stay up to date with my upcoming content.

Bye for now 👋