DynamoDB isn't a relational database, it's a NoSQL key-value and document store. You don't write arbitrary queries against your data. Instead, you design your tables around the specific access patterns your application needs.

DynamoDB is driven by your queries, not your data.

There's no need for joins or heavy normalisation. To get the performance DynamoDB is built for, model your data so it can be retrieved efficiently using keys – partition keys and sort keys – rather than relying on table scans or complex query logic.

If you try to use DynamoDB like SQL, it will fight you — and you will lose.

Prerequisites

There are a few things you'll need and some general knowledge that you should have to follow along most effectively here:

AWS

• An active AWS account with permissions to create and modify DynamoDB

• Basic familiarity with the AWS Console (navigating services, not deep expertise)

C# / .NET

• Comfortable with C#

• Dependency injection

• NuGet package management — you'll need to install AWSSDK.DynamoDBv2

Databases (Conceptual)

• (Optional) A working understanding of relational databases / SQL is actually helpful here — the article explicitly addresses readers coming from that background and explains the mental shift required

What you don't need

• Prior DynamoDB experience — the article covers core concepts from scratch

• Deep AWS infrastructure knowledge — IAM, VPCs, and so on aren't covered

Optional but useful

• AWS CLI installed locally if you want to follow the AWS CLI examples directly

• Terraform experience if following the infrastructure-as-code example (Terraform section can be skipped without losing context)

Table Of Contents

• Core DynamoDB Concepts

  • Partition Key

  • Sort Key (Optional)

  • Global Secondary Index (GSI)

• Synthetic Keys — The Old Way

• Multi-Attribute GSIs — The New Way

  • Defining a Multi-Attribute GSI

  • Query Rules You Must Follow

• C# SDK Options

  • Low-Level Client

  • Document Model

  • Object Persistence Model

  • Setting Up the Context

• Querying a Multi-Attribute GSI from C

• Query vs Scan

  • Query

  • Scan

  • When Is A Scan Acceptable?

• Filter Expressions

• Paging Results and User Interfaces

  • How It Works in DynamoDB

  • How This Works In The DynamoDB C# SDK

  • Manual Pagination — The Right Approach For UIs

  • What About "go to to page 7" Navigation?

  • The FilterExpression Trap

• Final Thoughts & Conclusion

Core DynamoDB Concepts

DynamoDB is built around a few core concepts that directly influence how you query and structure your data.

Remember: DynamoDB is driven by how you retrieve your data, not by the shape of the data itself.

Partition Key

• Required for every query

• Required to create a table – each table must have a partition key

• Determines data distribution and how items are stored

Data in DynamoDB is physically distributed across partitions. The partition key decides where a given item lives, which is why it's critical for both performance and scalability.

You can think of a partition key like a filing cabinet drawer label: it tells DynamoDB which drawer to open so it can go straight to your data without searching every drawer.

Partition keys are typically strings or numbers.

Sort Key (Optional)

Also known as the Range Key.

• Enables range queries (between, begins_with, and so on)

When you add a sort key, items with the same partition key are grouped together and ordered by the sort key. For string sort keys, ordering is lexicographical (dictionary order). For numeric sort keys, ordering is numeric (ascending).

This has an important effect when working with dates. If you store dates as strings in a non-ISO format (for example, DD/MM/YYYY), they won't sort in chronological order. For example, the resulting sorted items would look like this:

01/01/2026
01/02/2026
01/03/2026
08/01/2026
15/02/2026

Here, all dates starting with 01 are grouped together, even though they span different months. This breaks range queries and ordering.

To avoid this, use either:

• ISO 8601 format (YYYY-MM-DD), which sorts correctly as a string

• Unix timestamps (typically milliseconds since January 1st, 1970), which sort numerically and correctly

Both approaches ensure your data is ordered correctly and can be queried efficiently. This is commonly used for timestamps, versioning, or logical groupings (for example, ORDER#2024-01).

Global Secondary Index (GSI)

A Global Secondary Index (GSI) allows you to query your data using a different partition key and optional sort key than your base table. This is how you support additional access patterns without redesigning your primary key schema.

For example, if your base table is keyed by UserId, but you also need to query by OrderId, a GSI makes that possible.

Projection Types

A GSI doesn't have to include all attributes from the base table. When configuring your GSI you can choose:

• ALL — all attributes are projected

• KEYS_ONLY — only index and primary keys

• INCLUDE — a subset of selected attributes

Choosing the right projection helps reduce storage and read costs. For example, for an orders view you could project only orderNumber, dateOrdered, and cost rather than all other attributes which aren't needed.

Important Considerations

Additional cost: GSIs consume their own read/write capacity and storage in addition to your base table's costs. Using ProjectionType = INCLUDE or KEYS_ONLY instead of ALL reduces the storage cost of the GSI since less data is duplicated into the index, which can offset the additional read/write cost.

Eventual consistency: In DynamoDB, when you write directly to the base table you have the option to perform a strongly consistent read immediately after — meaning you're guaranteed to get the latest data. GSIs don'r support this. GSI reads are always eventually consistent.

When a customer places an order, DynamoDB writes that order to your main Orders table. It then replicates that change to any GSIs asynchronously in the background. During that brief window (typically milliseconds), a query against a GSI may not return the newly written order yet.

A real-world example of where this can catch you out:

1. Customer places an order which is written to the Orders table

2. User is redirected to the "Your Orders" page

3. "Your Orders" page queries a GSI for all orders by this customer

4. New order doesn't appear yet — GSI replication is still in progress

5. Customer refreshes the page 50ms later

6. Order now appears

For most queries — browsing a product catalogue, viewing order history, filtering by status — this is completely acceptable and unnoticeable to the user. Where it matters is when your application writes a record and immediately queries a GSI for that same record. In this scenario you have a couple of options:

• Query the base table directly after a write using a strongly consistent read, rather than the GSI

• Pass the order data directly to the UI from the write response, without a follow-up query at all — the cleanest solution in most cases

Write amplification: Every write to the base table may also write to one or more GSIs. GSIs are powerful, but they're not free. Overusing them is often a sign that your primary access patterns weren't well defined upfront.

Note: DynamoDB allows a maximum of 20 GSIs per table by default, though this can be increased via an AWS service limit request.

Synthetic Keys — The Old Way

Before we look at multi-attribute GSIs, it's worth understanding the pattern they replace — because you'll encounter it in existing DynamoDB codebases.

Imagine you want to query orders by both status and date — for example, all "pending" orders placed in the last 30 days. Previously, DynamoDB GSIs only supported a single attribute as the partition key and a single attribute as the sort key. To filter on multiple attributes you had to combine them into a single synthetic attribute:

[DynamoDBTable("Orders")]
public class OrderDto
{
    [DynamoDBHashKey("customerId")]
    public string CustomerId { get; set; }

    [DynamoDBRangeKey("createdAt")]
    public long CreatedAt { get; set; }

    [DynamoDBProperty("orderId")]
    public string OrderId { get; set; }

    [DynamoDBProperty("status")]
    public string Status { get; set; }

    // Synthetic key — manually constructed before saving
    [DynamoDBProperty("statusDate")]
    public string StatusDate { get; set; } // e.g. "PENDING#2025-11-01"
}

Constructing this value before saving the record:

order.StatusDate = $"{order.Status}#{order.CreatedAt:yyyy-MM-dd}";

Then create a GSI on statusDate as the partition key, allowing you to query:

var results = await _context.QueryAsync<OrderDto>(
    "PENDING#2025-11-01",
    config // IndexName = "statusDate-index"
).GetRemainingAsync();

This worked, but came with real downsides:

• Brittle — every developer writing to the table must know about and correctly format the synthetic key

• Hard to query ranges — filtering all pending orders across a date range required careful begins_with or between conditions on a concatenated string

• Maintenance overhead — if status values change, every existing record needs updating

• Invisible in the schema — a new developer has no idea what statusDate means without documentation

• Backfilling — adding a new synthetic-key GSI to an existing table meant updating every existing record to populate the new attribute via a script re-processing the existing items.

Multi-Attribute GSIs — The New Way

On November 19, 2025, AWS announced multi-attribute composite keys for GSIs. You can now define a GSI partition key or sort key comprised of up to 4 attributes each — 8 attributes in total across the partition and sort key combined.

A few important things to note:

• GSIs only: This applies to GSIs only — your base table primary key structure is unchanged, still a single partition key and an optional single sort key.

• DynamoDB handles composition internally: You don't concatenate values yourself. DynamoDB hashes the partition key attributes together for data distribution, and maintains hierarchical sort order across the sort key attributes.

• Strict query rules still apply: You must supply all partition key attributes with equality conditions when querying. Sort key attributes must be queried left-to-right in the order they were defined — you can't skip attributes.

• No backfilling required. When you add a multi-attribute GSI to an existing table, DynamoDB automatically indexes all existing items using their natural attributes.

• No additional cost beyond standard GSI pricing.

The model stays clean — no synthetic attributes needed:

[DynamoDBTable("Orders")]
public class OrderDto
{
    [DynamoDBHashKey("customerId")]
    public string CustomerId { get; set; }

    [DynamoDBRangeKey("createdAt")]
    public long CreatedAt { get; set; }

    [DynamoDBProperty("orderId")]
    public string OrderId { get; set; }

    [DynamoDBProperty("status")]
    public string Status { get; set; }

    [DynamoDBProperty("total")]
    public decimal Total { get; set; }
}

Defining a Multi-Attribute GSI

You can create the GSI via the AWS Console (select the attributes you want in order), via Terraform (requires AWS provider v6.29.0+), or via the AWS CLI.

The key concept to understand: you provide multiple HASH entries for the composite partition key and multiple RANGE entries for the composite sort key, in the exact order they should be evaluated. DynamoDB treats them internally as one composite partition key and one composite sort key.

Here's an AWS CLI example — a GSI on Orders with a composite partition key (customerId + status) and a single-attribute sort key (createdAt):

aws dynamodb update-table \
  --table-name Orders \
  --attribute-definitions \
    AttributeName=customerId,AttributeType=S \
    AttributeName=status,AttributeType=S \
    AttributeName=createdAt,AttributeType=N \
  --global-secondary-index-updates \
  "[{\"Create\":{
    \"IndexName\":\"customerStatus-createdAt-index\",
    \"KeySchema\":[
      {\"AttributeName\":\"customerId\",\"KeyType\":\"HASH\"},
      {\"AttributeName\":\"status\",\"KeyType\":\"HASH\"},
      {\"AttributeName\":\"createdAt\",\"KeyType\":\"RANGE\"}
    ],
    \"Projection\":{\"ProjectionType\":\"ALL\"}
  }}]"

The two HASH entries here are valid. They define a composite partition key of (customerId, status). This is the syntax AWS introduced specifically for multi-attribute GSIs. It would have been rejected before November 2025.

Here's a Terraform example (AWS provider v6.29.0+):

global_secondary_index {
  name            = "customerStatus-createdAt-index"
  projection_type = "ALL"

  key_schema {
    attribute_name = "customerId"
    key_type       = "HASH"
  }

  key_schema {
    attribute_name = "status"
    key_type       = "HASH"
  }

  key_schema {
    attribute_name = "createdAt"
    key_type       = "RANGE"
  }
}

Query Rules You Must Follow

The flexibility gain with multi-attribute GSIs is real, but the query constraints are not the same as SQL. Two rules matter most:

1. Partition key attributes must all be supplied, with equality only.

For a partition key of (customerId, status):

Valid:

customerId = 'C123' AND status = 'PENDING'

Invalid — missing status:

customerId = 'C123'

Invalid — inequality on a partition key attribute:

customerId = 'C123' AND status > 'P'

2. Sort key attributes must be queried left-to-right, with inequality only as the final condition.

For a sort key of (tournamentRound, rank, matchId):

Valid:

tournamentRound = 'SEMIFINALS'

tournamentRound = 'SEMIFINALS' AND rank = 'UPPER'

tournamentRound = 'SEMIFINALS' AND rank = 'UPPER' AND matchId = 'match-002'

tournamentRound = 'SEMIFINALS' AND rank = 'UPPER' AND matchId > 'match-001'

tournamentRound BETWEEN 'QUARTERFINALS' AND 'SEMIFINALS'

Invalid — skipping the first attribute:

rank = 'UPPER'

Invalid — leaving a gap (skipping bracket)

tournamentRound = 'SEMIFINALS' AND matchId = 'match-002'

Invalid — adding a condition after an inequality:

tournamentRound > 'QUARTERFINALS' AND rank = 'UPPER'

Design tip: Order your sort key attributes from most general to most specific for example, tournamentRound → rank → matchId). This maximises query flexibility, since each left-to-right prefix becomes a valid query pattern.

Going deeper:

AWS publishes a detailed design pattern guide with worked examples for time-series data, e-commerce orders, hierarchical organisation data, and multi-tenant SaaS platforms. The examples use the JavaScript SDK, but the schema design principles apply regardless of language. The article can be found here.

C# SDK Options

When working with DynamoDB in C#, the AWSSDK.DynamoDBv2 NuGet package gives you three different ways to interact with your tables, each with different levels of abstraction.

Low-Level Client

var client = new AmazonDynamoDBClient();

The AmazonDynamoDBClient gives you full control over every aspect of your DynamoDB interactions. You construct requests manually, specifying every attribute, condition, and configuration explicitly.

var request = new QueryRequest
{
    TableName = "Orders",
    KeyConditionExpression = "customerId = :customerId",
    ExpressionAttributeValues = new Dictionary<string, AttributeValue>
    {
        { ":customerId", new AttributeValue { S = "customer-123" } }
    }
};

var response = await client.QueryAsync(request);

This is the most verbose approach, but nothing is hidden from you. You can see exactly what's being sent to DynamoDB, which makes it easier to debug, optimise, and understand exactly what Read Capacity Units (RCUs) you're consuming. It's also the most flexible — anything DynamoDB supports, you can do here.

When to use it:
When you need fine-grained control, are doing something complex, or want full visibility into your queries.

Document Model

var client = new AmazonDynamoDBClient();
var table = Table.LoadTable(client, "Orders");

The Document Model sits a level above the low-level client. Rather than working with raw AttributeValue types, you work with Document objects which feel more like JSON — familiar to most .NET developers.

var filter = new QueryFilter("customerId", QueryOperator.Equal, "customer-123");
var search = table.Query(filter);
var documents = await search.GetRemainingAsync();

// access the data
foreach (var doc in documents)
{
    Console.WriteLine(doc["orderId"].AsString());
    Console.WriteLine(doc["total"].AsDecimal());
}

Less boilerplate than the low-level client, but you're still working with loosely typed Document objects rather than your own C# classes. There's no mapping to strongly typed models out of the box.

When to use it:
Useful for dynamic or loosely structured data where you don't want to define a fixed model, or for quick tooling and scripts.

Object Persistence Model

The Object Persistence Model is the highest level of abstraction and the most natural fit for typical .NET development.

You decorate your C# classes with attributes, and the DynamoDBContext handles serialisation and deserialisation automatically — similar to an ORM like Entity Framework.

[DynamoDBTable("Orders")]
public class OrderRecord
{
    [DynamoDBHashKey("customerId")]
    public string CustomerId { get; set; }

    [DynamoDBRangeKey("createdAt")]
    public long CreatedAt { get; set; }

    [DynamoDBProperty("orderId")]
    public string OrderId { get; set; }

    [DynamoDBProperty("total")]
    public decimal Total { get; set; }

    [DynamoDBProperty("status")]
    public string Status { get; set; }
}

Querying feels clean and strongly typed:

var orders = await dbContext
    .QueryAsync<OrderRecord>("customer-123")
    .GetRemainingAsync();

The trade-off is that the abstraction hides some important details: you don't always see exactly what's being sent to DynamoDB under the hood, which can make debugging and performance optimisation harder.

Setting Up the Context

When creating the db context there are a couple of options:

Option 1 — using Dependency Injection:

// Program.cs
builder.Services.AddSingleton<IAmazonDynamoDB, AmazonDynamoDBClient>();

builder.Services.AddSingleton<IDynamoDBContext>(sp =>
{
    var client = sp.GetRequiredService<IAmazonDynamoDB>();
    return new DynamoDBContext(client);
});

// Then in repository / service, inject IDynamoDBContext
public class OrderRepository
{
    private readonly IDynamoDBContext _context;

    public OrderRepository(IDynamoDBContext context)
    {
        _context = context;
    }
}

Option 2 — register AmazonDynamoDBClient only, and instantiate the context per operation:

// Program.cs
builder.Services.AddSingleton<IAmazonDynamoDB, AmazonDynamoDBClient>();

Then:

public class OrderRepository
{
    private readonly IAmazonDynamoDB _client;

    public OrderRepository(IAmazonDynamoDB client)
    {
        _client = client;
    }

    public async Task<List<OrderDto>> GetOrdersAsync(string customerId)
    {
        var context = new DynamoDBContext(_client); // lightweight to instantiate
        return await context.QueryAsync<OrderDto>(customerId).GetRemainingAsync();
    }
}

Which is better? Option 1 is cleaner and more testable — you can mock IDynamoDBContext in unit tests easily. Option 2 is also valid since DynamoDBContext is lightweight to instantiate, but you lose the ability to mock it cleanly.

When to use Object Persistence: the recommended approach for most .NET applications. Clean, strongly typed, and fits naturally into existing C# codebases.

Querying a Multi-Attribute GSI From C#

At the time of writing, the DynamoDBContext.QueryAsync<T> convenience overloads don't support multi-attribute GSI key conditions directly — you need to use the low-level client (IAmazonDynamoDB) and pass a KeyConditionExpression. The good news is the deserialisation back to your typed model is still straightforward.

Here's a query against a GSI with a composite partition key of (customerId, status) and a sort key of createdAt, returning all pending orders for a customer since a given date:

public async Task<List<OrderDto>> GetOrdersByStatusSinceAsync(
    string customerId,
    string status,
    long fromDate)
{
    var request = new QueryRequest
    {
        TableName = "Orders",
        IndexName = "customerStatus-createdAt-index",
        KeyConditionExpression =
            "customerId = :customerId " +
            "AND #status = :status " +           // #status because 'status' is a reserved word
            "AND createdAt > :fromDate",
        ExpressionAttributeNames = new Dictionary<string, string>
        {
            { "#status", "status" }
        },
        ExpressionAttributeValues = new Dictionary<string, AttributeValue>
        {
            { ":customerId", new AttributeValue { S = customerId } },
            { ":status",     new AttributeValue { S = status } },
            { ":fromDate",   new AttributeValue { N = fromDate.ToString() } }
        },
        ScanIndexForward = false // reverse sort key order — newest first, since sort key is a timestamp
    };

    var response = await _client.QueryAsync(request);

    // manually deserialise back to OrderDto using the DynamoDBContext
    return _context.FromDocuments<OrderDto>(
        response.Items.Select(Document.FromAttributeMap)
    ).ToList();
}

Looking at the code above, notice that:

• Both partition key attributes (customerId and status) are supplied with equality — this is required.

• The sort key (createdAt) uses an inequality > (greater than) as the final condition, which is allowed.

• No synthetic string construction, no brittle formatting conventions, no backfilling existing records.

If you're working on an existing codebase that uses synthetic keys, it's worth evaluating whether migrating to multi-attribute GSIs makes sense. The backfilling problem that made migrations painful before is gone, DynamoDb multi-attribute GSIs handle it automatically.

Query vs Scan

This is one of the most important concepts to understand when working with DynamoDB — and one of the most common sources of performance and cost problems.

Query

A Query retrieves items using the partition key, and optionally narrows results using the sort key. DynamoDB knows exactly which partition to look in, reads only the relevant items, and returns them efficiently.

// Get all orders for a customer
var orders = await _context
    .QueryAsync<OrderDto>("customer-123")
    .GetRemainingAsync();

You can narrow further using a sort key condition — for example, all orders placed in the last 30 days:

var thirtyDaysAgo = DateTimeOffset.UtcNow.AddDays(-30).ToUnixTimeMilliseconds();

var orders = await _context.QueryAsync<OrderDto>(
    "customer-123",
    QueryOperator.GreaterThan,
    new List<object> { thirtyDaysAgo }
).GetRemainingAsync();

Queries are fast and cheap — you only pay RCUs for the records actually read.

Scan

A Scan reads every single item in the table, then filters the results. It doesn't use keys or indexes — it brute-forces through everything.

var conditions = new List<ScanCondition>
{
    new ScanCondition("status", ScanOperator.Equal, "pending")
};

var orders = await _context
    .ScanAsync<OrderDto>(conditions)
    .GetRemainingAsync();

This works — but on a table with 10 million orders, DynamoDB reads all 10 million records and then filters down to the pending ones. You pay RCUs for every single record read, not just the ones returned.

Important: Scans should be avoided in production for large tables. They're slow, expensive, and get worse as your table grows.

The difference visualised:

Query:
Table [■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■]
       └── Jump straight to partition "customer-123"
               └── Read only these items — cheap

Scan:
Table [■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■]
       └── Read every single item — expensive
               └── Then discard non-matching items

When Is A Scan Acceptable?

Scans aren't always wrong — there are legitimate use cases:

• Small tables — a lookup table with 50 items, a scan is perfectly fine

• One-off data migrations or admin scripts — not user-facing, run occasionally

• Development and debugging — scanning locally or against a small dataset

Rule of thumb: if it's a user-facing query on a growing table, it should be a Query, not a Scan.

Coming from SQL, developers often reach for a Scan because it feels like:

SELECT * FROM orders WHERE status = 'pending'

In SQL with a good index, that's fine. In DynamoDB, without a GSI on status, that's a full table scan every time. The solution is to design a GSI for the access patterns you need — exactly what we covered in the GSI section earlier.

Filter Expressions

Both Query and Scan support an optional FilterExpression — a condition applied after DynamoDB has read the records but before they're returned to you. It looks superficially like a SQL WHERE clause, and that's exactly the trap.

var request = new QueryRequest
{
    TableName = "Orders",
    KeyConditionExpression = "customerId = :customerId",
    FilterExpression = "#status = :status",
    ExpressionAttributeNames = new Dictionary<string, string>
    {
        { "#status", "status" }
    },
    ExpressionAttributeValues = new Dictionary<string, AttributeValue>
    {
        { ":customerId", new AttributeValue { S = "customer-123" } },
        { ":status",     new AttributeValue { S = "pending" } }
    }
};

The critical thing to understand: FilterExpression does not reduce the cost of the query. DynamoDB still reads every record first, charges you RCUs for all of them, and only then discards the ones that don't match the filter.

For a Query, that means every record matched by the KeyConditionExpression. For a Scan, that means every record in the table.

It's a convenience for trimming the response payload, not a tool for efficient querying. If you find yourself reaching for FilterExpression to support a real access pattern, that's a signal you need a GSI instead.

Paging Results and User Interfaces

Pagination is one of the most misunderstood aspects of DynamoDB, especially if you're coming from a SQL background.

In SQL you might write:

SELECT * FROM orders LIMIT 10 OFFSET 20

DynamoDB doesn't work like this. There is no concept of OFFSET or page numbers. Instead, DynamoDB uses cursor-based pagination via a LastEvaluatedKey.

How It Works In DynamoDB

DynamoDB returns a maximum of 1MB of data per request. If your results exceed 1MB, DynamoDB returns a LastEvaluatedKey — a pointer to where it stopped reading. Pass this back in to the next request to continue from that position. When no LastEvaluatedKey is returned, you've reached the end of the data.

How This Works In The DynamoDB C# SDK

The SDK's GetRemainingAsync() method handles pagination automatically, it keeps making requests until there is no LastEvaluatedKey left, returning everything as a single list:

// Handles all pages automatically — but loads everything into memory
var orders = await _context
    .QueryAsync<OrderDto>("customer-123")
    .GetRemainingAsync();

This is convenient but dangerous on large datasets. If a customer has 50,000 orders, you're loading all 50,000 into memory in one go.

Manual Pagination — The Right Approach For UIs

For a UI with "load more" or "next/previous" navigation, control pagination manually using GetNextSetAsync():

// ---- Paging Model ----
public class PagedResult<T>
{
    public List<T> Items { get; set; }
    public string? PaginationToken { get; set; }
}

// ---- Repository Method ----
public async Task<PagedResult<OrderDto>> GetOrdersPageAsync(
    string customerId,
    string? paginationToken = null)
{
    var config = new DynamoDBOperationConfig
    {
        BackwardQuery = true // reverse sort key order — newest first if sort key is a timestamp
    };

    var search = _context.QueryAsync<OrderDto>(customerId, config);

    if (paginationToken != null)
        search.PaginationToken = paginationToken;

    var items = await search.GetNextSetAsync(25); // fetch exactly 25 records

    return new PagedResult<OrderDto>
    {
        Items = items,
        PaginationToken = search.PaginationToken // null if no more pages
    };
}

The PaginationToken is the SDK's serialised representation of the LastEvaluatedKey — pass it directly to the client as a string and receive it back on the next request.

What About "go to to page 7" Navigation?

This isn't possible in DynamoDB. The LastEvaluatedKey is a position cursor, to reach page 7 you'd have to paginate through pages 1 to 6 first to obtain the correct cursor placement.

For most modern UIs this isn't a problem. Infinite scroll and "load more" patterns map naturally to cursor-based pagination.

The FilterExpression Trap

We've already seen that FilterExpression is a poor substitute for a well-designed GSI. Pagination is where it goes from "wasteful" to actively broken.

DynamoDB's pagination works in two stages when a FilterExpression is involved:

1. Read records until the 1MB limit is reached

2. Apply the FilterExpression, discarding non-matching records

The LastEvaluatedKey is generated after step 1 — before filtering. So DynamoDB can return a LastEvaluatedKey implying there are more results, even if the filtered page returned only a handful of records.

With 1,000 orders where only 50 are "pending":

Page 1: Read 200 records → filter applied → 3 "pending" returned + LastEvaluatedKey

Page 2: Read 200 records → filter applied → 1 "pending" returned + LastEvaluatedKey

Page 3: Read 200 records → filter applied → 0 "pending" returned + LastEvaluatedKey

...and so on until all 1,000 records are read

Important: You pay RCUs for every record read, NOT every record returned.

The Limit parameter doesn't rescue you here. GetNextSetAsync(25) caps the records read before filtering, not the records returned. You can read 25, filter down to 3, and still get a LastEvaluatedKey back, meaning your "page size of 25" actually returns somewhere between 0 and 25 results, unpredictably.

The real fix isn't a smarter pagination strategy, it's removing the FilterExpression entirely. Design a GSI keyed on the attribute you're filtering by (here, status, or a multi-attribute GSI with status in the partition key). DynamoDB then reads only the matching records directly, Limit caps what you actually want, and pagination behaves predictably.

Final Thoughts & Conclusion

DynamoDB rewards you for designing around your access patterns up front, and punishes you for pretending it's SQL. The two biggest shifts from a relational mindset are:

1. Queries are the schema. You model tables, keys, and GSIs around the queries you need to run. You don't normalise and figure out queries later.

2. Keys do the work. The Query operation is fast and cheap precisely because it uses the partition key to jump straight to the right data. Scans read everything, and they get worse as your data grows.

The November 2025 multi-attribute GSI release is a genuinely welcome change, and is a huge improvement to the AWS resource. It removes one of the most painful ergonomic issues with DynamoDB, synthetic key construction and backfilling, without loosening the constraints that make DynamoDB fast.

The query rules (all partition-key attributes supplied, sort-key attributes queried left-to-right) stay exactly the same. What you gain is cleaner, typed, natural data models and the ability to add new access patterns to existing tables without a data migration.

For new projects, my recommendation is to use multi-attribute GSIs by default. For existing codebases built on synthetic keys, evaluate whether a migration makes sense, the painful part of such migrations is now gone.

As always if you want to discuss this further, or hear about my other articles drop me a follow on 'X'.

Dapper stands out as a lightweight and high-performance ORM tool with numerous advantages. But where Dapper really excels is in its speed and control. Here, we'll explore Dapper's suitability for performance-critical .NET projects with simpler database relationships utilising raw SQL queries.

The article guides you in building a lightweight .NET Web API for a social media application with Dapper using a Postgres database.

Prerequisites

• Latest .Net SDK and runtime (at time of writing, it's .Net 10).

• Knowledge of the C# programming language and how Dependency Injection works

• A running PostgreSQL instance

• DB Viewer software, for example DBeaver, pgAdmin, or the PostgreSQL extension for VS Code

Table of Contents

• What Is Dapper?

• Challenges and Advantages of Dapper

• Getting Started – Installation

• Querying Data With Dapper

• QuerySingle vs QueryFirst

• Writing Data With Dapper

• Updating Data With Dapper

• Deleting Records With Dapper

• Batch Processing With Dapper

• Transactions With Dapper

• Multi-mapping / Splits

• What Comes Next – Possible Additions

• Final Thoughts

What Is Dapper?

Dapper is a "micro ORM", providing lightweight, high-performance data access with minimal abstraction. It relies on SQL queries (these are the queries you use when interacting with an SQL database) for example:

SELECT * FROM influencers WHERE ID = 1, mapping the results to objects directly.

Here's how Dapper's README describes what it does:

This [Dapper] provides a simple and efficient API for invoking SQL, with support for both synchronous and asynchronous data access, and allows both buffered and non-buffered queries. – Dapper github repository README

An ORM (Object-Relational Mapper) is like a translator between a programming language and a database, allowing software to interact with databases using familiar programming objects (instead of direct SQL queries), making it easier to manage and manipulate data in applications.

As Dapper is a "Micro-ORM", it acts a middle-ground between direct SQL and a full fledged ORM like that of the Entity Framework (EF) which you may have heard of before. It has a lot of the basic features, but doesn't come with all the "bloat," making it a secure and faster database tool.

Challenges and Advantages of Dapper

Challenges of Dapper

Advantages of Dapper

But let’s not dwell on the negatives. Now let's concentrate on the advantages, as these far outweigh the challenges.

Getting Started – Installation

You’re going to use the CLI (Command Line Interface) to install Dapper in your project. I've chosen this method, as it’s not only quicker, but will help build confidence with the CLI.

Cloning the Repo:

In your terminal app, navigate to the folder where you want the repository to be located and run the following command to clone the public tutorial repository:

git clone https://github.com/grant-dot-dev/dapper_tutorial.git

You then need to add Dapper and the Postgres support to your project. You can do this with the following command:

cd FCC.DapperTutorial

# add Dapper nuget package
dotnet add package Dapper

# add Postgres driver
dotnet add package Npgsql

Update your defaultConnection connection string within appsettings.json with the location of your Postgres instance.

"ConnectionStrings": {
  "DefaultConnection": "Host=localhost;Port=5432;Database=social_media;Username=postgres;Password=yourpassword"
}

Create Seeding File

Create a folder in your project called Infrastructure. Then within this folder create a file called DbUtilities.cs and populate it with the following code:

using Dapper;
using Npgsql;
using Microsoft.Extensions.Configuration;

namespace DapperTutorial.Infrastructure;

public static class DBUtilities
{
    private const string CreateUserSql = @"
        CREATE TABLE IF NOT EXISTS ""User"" (
            UserId TEXT PRIMARY KEY,
            Username TEXT,
            FirstName TEXT,
            LastName TEXT,
            Avatar TEXT,
            Email TEXT,
            DOB DATE
        );";

    private const string CreatePostSql = @"
        CREATE TABLE IF NOT EXISTS Post (
            PostId TEXT PRIMARY KEY,
            Likes INTEGER,
            Content TEXT,
            Timestamp TIMESTAMP,
            UserId TEXT,
            FOREIGN KEY(UserId) REFERENCES ""User""(UserId)
        );";

    private const string InsertUsersSql = @"
        INSERT INTO ""User"" (UserId, Username, FirstName, LastName, Avatar, Email, DOB) VALUES
            ('1', 'iron_man', 'Tony', 'Stark', NULL, 'tony.stark@example.com', '1970-05-29'),
            ('2', 'batman', 'Bruce', 'Wayne', NULL, 'bruce.wayne@example.com', '1972-11-11'),
            ('3', 'spiderman', 'Peter', 'Parker', NULL, 'peter.parker@example.com', '1995-08-10'),
            ('4', 'wonderwoman', 'Diana', 'Prince', NULL, 'diana.prince@example.com', '1985-04-02'),
            ('5', 'superman', 'Clark', 'Kent', NULL, 'clark.kent@example.com', '1980-07-18'),
            ('6', 'black-widow', 'Natasha', 'Romanoff', NULL, 'natasha.romanoff@example.com', '1983-06-25'),
            ('7', 'deadpool', 'Wade', 'Wilson', NULL, 'wade.wilson@example.com', '1977-02-19'),
            ('8', 'green-lantern', 'Hal', 'Jordan', NULL, 'hal.jordan@example.com', '1988-09-05'),
            ('9', 'captain-america', 'Steve', 'Rogers', NULL, 'steve.rogers@example.com', '1920-07-04'),
            ('10', 'catwoman', 'Selina', 'Kyle', NULL, 'selina.kyle@example.com', '1982-12-08')
        ON CONFLICT (UserId) DO NOTHING;";

    private const string InsertPostsSql = @"
        INSERT INTO Post (PostId, Likes, Content, Timestamp, UserId) VALUES
            ('p1', 10, 'Hello, world!', '2025-10-12 10:00:00', '1'),
            ('p2', 5, 'My first post!', '2025-10-12 11:00:00', '2'),
            ('p3', 7, 'Excited to join!', '2025-10-12 12:00:00', '3'),
            ('p4', 3, 'What a great day!', '2025-10-12 13:00:00', '4'),
            ('p5', 15, 'Superhero meetup!', '2025-10-12 14:00:00', '5')
        ON CONFLICT (PostId) DO NOTHING;";

    public static async Task SeedDatabaseAsync(IConfiguration configuration)
    {
        var connectionString = configuration.GetConnectionString("DefaultConnection");

        await using var connection = new NpgsqlConnection(connectionString);
        await connection.OpenAsync();

        await using var transaction = await connection.BeginTransactionAsync();

        try
        {
            await connection.ExecuteAsync(CreateUserSql, transaction: transaction);
            await connection.ExecuteAsync(CreatePostSql, transaction: transaction);

            var userCount = await connection.QuerySingleAsync<int>(
                @"SELECT COUNT(*) FROM ""User"";", transaction: transaction);

            var postCount = await connection.QuerySingleAsync<int>(
                "SELECT COUNT(*) FROM Post;", transaction: transaction);

            if (userCount > 0 && postCount > 0)
            {
                await transaction.CommitAsync();
                return;
            }

            await connection.ExecuteAsync(InsertUsersSql, transaction: transaction);
            await connection.ExecuteAsync(InsertPostsSql, transaction: transaction);

            await transaction.CommitAsync();
        }
        catch (Exception)
        {
            await transaction.RollbackAsync();
            throw;
        }
    }
}

Add a seed endpoint to your API within the Program.cs file as normal:

// add the using statement
using DapperTutorial.Infrastructure;

// add the seed endpoint
app.MapPost("/seed", async (IConfiguration configuration) =>
{
	try
	{
		await DBUtilities.SeedDatabaseAsync(configuration);
		return Results.Ok("Database seeded successfully.");
	}
	catch (Exception ex)
	{
		return Results.Problem($"An error occurred while seeding the database: {ex.Message}");
	}
});

In your terminal, run the app with dotnet run, call the /seed endpoint, and this will initiate the database. Check the records have seeded correctly by viewing your database within your preferred database tool.

Querying Data With Dapper

This section of the tutorial will focus on the basics of using the Dapper library to query the database. We'll explore the basics of loading, saving, and protecting your SQL database.

Firstly, we'll implement the repository pattern, a commonly used pattern in development. A repository acts as one stop place for all your database functions. Using a repository which implements an interface allows you to easily test and mock your database functionality.

Start by creating the models for your data within a Models folder.

// User.cs Model
public sealed class User
{
	public string UserId { get; init; } = string.Empty;
	public string Username { get; init; } = string.Empty;
	public string FirstName { get; init; } = string.Empty;
	public string LastName { get; init; } = string.Empty;
	public string? Avatar { get; init; }
	public string Email { get; init; } = string.Empty;
	public DateOnly? DOB { get; init; }
}

// Post.cs Model
public sealed class Post
{
	public string PostId { get; init; } = string.Empty;
	public int Likes { get; init; }
	public string Content { get; init; } = string.Empty;
	public DateTime Timestamp { get; init; }
	public string UserId { get; init; } = string.Empty;
}

Following best practice, create anIRepository.cs file within an Application folder, and paste the following code which defines your querying functions:

using DapperTutorial.Models;

namespace DapperTutorial.Application;

public interface IRepository
{
    Task<IReadOnlyList<User>> GetUsersAsync();
    Task<User?> GetUserByIdAsync(string userId);
    Task<IReadOnlyList<Post>> GetPostsAsync();
    Task<Post?> GetPostByIdAsync(string postId);
    Task<IReadOnlyList<Post>> GetPostsByUser(string userId);
}

You now have a base interface, which can be mocked for unit testing purposes within a wider application. This is one of the many perks of implementing this pattern.

Now, create the concrete implementation of the repository like so:

using Dapper;
using DapperTutorial.Application;
using DapperTutorial.Models;
using Npgsql;

namespace DapperTutorial.Infrastructure;

public class Repository(IConfiguration configuration) : IRepository
{
	private readonly string _connectionString = configuration.GetConnectionString("DefaultConnection") ?? throw new InvalidOperationException("Missing connection string: ConnectionStrings:DefaultConnection");

	public async Task<IReadOnlyList<User>> GetUsersAsync()
	{
		const string sql = @"
			SELECT
				UserId,
				Username,
				FirstName,
				LastName,
				Avatar,
				Email,
				DOB
			FROM ""User""
			ORDER BY Username;";

		await using var connection = CreateConnection();
		var users = await connection.QueryAsync<User>(sql);
		return users.AsList();
	}

	public async Task<User?> GetUserByIdAsync(string userId)
	{
		const string sql = @"
			SELECT
				UserId,
				Username,
				FirstName,
				LastName,
				Avatar,
				Email,
				DOB
			FROM ""User""
			WHERE UserId = @UserId;";

		await using var connection = CreateConnection();
		return await connection.QuerySingleOrDefaultAsync<User>(sql, new { UserId = userId });
	}

	public async Task<IReadOnlyList<Post>> GetPostsAsync()
	{
		const string sql = @"
			SELECT
				PostId,
				Likes,
				Content,
				Timestamp,
				UserId
			FROM Post
			ORDER BY Timestamp DESC;";

		await using var connection = CreateConnection();
		var posts = await connection.QueryAsync<Post>(sql);
		return posts.AsList();
	}

	public async Task<IReadOnlyList<Post>> GetPostsByUser(string userId)
	{
		const string sql = @"
			SELECT
				PostId,
				Likes,
				Content,
				Timestamp,
				UserId
			FROM Post
			WHERE UserId = @UserId
			ORDER BY Timestamp DESC;";

		await using var connection = CreateConnection();
		var posts = await connection.QueryAsync<Post>(sql, new { UserId = userId });
		return posts.AsList();
	}

	public async Task<Post?> GetPostByIdAsync(string postId)
	{
		var sql = @"
			SELECT * FROM Post
			WHERE PostId = @PostId;";

		await using var connection = CreateConnection();
		return await connection.QuerySingleOrDefaultAsync<Post>(sql, new { PostId = postId });
	}

	private NpgsqlConnection CreateConnection() => new(_connectionString);
}

Unpacking the Repository:

The primary constructor injects IConfiguration, which is automatically provided by ASP.Net Core's built-in dependency injection system. This means you don't need to instantiate it yourself – the framework handles that for you. This allows access to the connection string defined in appsettings.json, which Dapper needs in order to connect to the database.

You'll also notice the null-coalescing ?? operator. This is a defensive pattern that throws a clear, descriptive error immediately if the connection string is missing, rather than letting a cryptic NullReferenceException surface somewhere further down the line when trying to use the connection string's value, if not provided.

Each method contains a SQL string prefixed with the @ character, making it a verbatim string literal. This allows the string to span multiple lines without needing \n escape characters or string concatenation, so we can format our SQL the same way we would in a query editor. This makes it much easier to read.

User is a reserved word in PostgreSQL, hence the double quotes around "User".

If you're familiar with SQL, you can easily use Dapper's query methods. This is the key strength of Dapper: it gives you the flexibility of plain SQL, with the added benefits of an ORM.

• QueryAsync(): Use this method when your query could return zero or more results. It will always return a collection, never null, so you don't need to worry about null checks when no rows are found.

• QuerySingleOrDefaultAsync(): Use this method when you expect at most one result. This is useful for methods like GetByIdAsync, or fetching a user's profile. If no matching row is found, it returns the default value for that type – null for reference types like User?.

QuerySingle vs QueryFirst

Both QuerySingleOrDefaultAsync and QueryFirstOrDefaultAsync are used when you want to return a single result, and both return the default value for the type of null for reference types, when no rows are found.

The difference is in how they behave when more than one row is returned.

QuerySingleOrDefaultAsync will throw an exception, which makes it the safer choice when querying by primary key, as if you ever get two results back, something has gone seriously wrong and you want to know about it immediately rather than silently returning the wrong record, such as incorrect duplicate.

QueryFirstOrDefaultAsync, on the other hand, takes the first result and ignores the rest. This makes it the better fit for scenarios such as "give me the most recent post by this user", where multiple results are expected yet you just want the top one, typically driven by an ORDER BY in your query.

Writing Data With Dapper

You have successfully created methods for querying and returning data from the repository, but you're going to require methods for inserting and updating existing records.

Insert Method

Add a CreateUserAsync() method definition to the IRepository interface, and then copy the below implementation into your Repository.cs:

public async Task<bool> CreateUserAsync(User user)
{
    const string sql = @"
        INSERT INTO ""User"" (
            UserId,
            Username,
            FirstName,
            LastName,
            Avatar,
            Email,
            DOB
        ) VALUES (
            @UserId,
            @Username,
            @FirstName,
            @LastName,
            @Avatar,
            @Email,
            @DOB
        );";

    await using var connection = CreateConnection();
    var rowsAffected = await connection.ExecuteAsync(sql, user);
    return rowsAffected > 0;
}

As before, state the SQL for inserting a record into the User table, with the parameters needed to assign the values.

A few things worth noting:

• Dapper maps the user object's properties directly to the @ parameters by name, so you can just pass user rather than constructing an anonymous object.

• ExecuteAsync() returns the number of rows affected, so returning rowsAffected > 0 gives the caller a simple success/failure bool.

• Avatar and DOB are nullable on the model, and Dapper handles this gracefully: it will insert NULL into the database when those values are null.

Protecting Your Database – Parameterisation and SQL Injection

You may have noticed that throughout this tutorial, values are never inserted directly into the SQL string. Instead, we use placeholders like @UserId and @Username, with the actual values passed separately. This is called parameterisation, and it's one of the most important habits you can build as a developer.

To understand why, consider what happens without it. If you were to build a query using string interpolation:

// Never do this
var sql = $"SELECT * FROM \"User\" WHERE Username = '{username}'";


//A malicious user could pass the following as their username:
```
' OR '1'='1

Which would turn your query into:

SELECT * FROM "User" WHERE Username = '' OR '1'='1'

Since '1'='1' is always true, this query returns every user in the database. With a more destructive payload, an attacker could drop tables, delete records, or extract sensitive data entirely. This is known as a SQL injection attack, and it remains one of the most common and damaging vulnerabilities in web applications.

Dapper protects you from this automatically. When you write:

const string sql = @"SELECT * FROM ""User"" WHERE Username = @Username";
var user = await connection.QuerySingleOrDefaultAsync<User>(sql, new { Username = username });

Dapper sends the SQL and the values to the database separately. The database receives the query structure first, compiles it, and then applies the value as pure data – it can never be interpreted as SQL. No matter what a user passes in, it will always be treated as a value, never as an instruction.

This is why throughout this tutorial, you will always see:

• @ParameterName placeholders in the SQL string

• Values passed as an anonymous object, a model, or DynamicParameters

But never string interpolation or concatenation inside a SQL string.

Updating Data With Dapper

You don't always want to create new records. Sometimes, you would rather update records instead. Below is the code required to do this. Add this method to your repository, not forgetting to add the definition to the repository interface:

public async Task<bool> UpdateUserAsync(User user)
	{
        const string sql = @"
        UPDATE ""User"" SET
            Username = @Username,
            FirstName = @FirstName,
            LastName = @LastName,
            Avatar = @Avatar,
            Email = @Email,
            DOB = @DOB
        WHERE UserId = @UserId;";

		await using var connection = CreateConnection();
		var affectedRows = await connection.ExecuteAsync(sql, user);
		return affectedRows > 0;
	}

Like all other queries / actions with Dapper, an SQL command is written and passed to ExecuteAsync() along with the object to be updated, and Dapper will automatically map the properties based on name.

Deleting Records With Dapper

Just like before, add the following code to your repository. Add your delete SQL command, and pass to the ExecuteAsync() method. Below, instead of passing the user object, you're manually mapping the userId to the SQL `@UserId` parameter.

public async Task<bool> DeleteUserAsync(string userId)
	{
		const string sql = @"
			DELETE FROM ""User""
			WHERE UserId = @UserId;";

		await using var connection = CreateConnection();
		var affectedRows = await connection.ExecuteAsync(sql, new { UserId = userId });
		return affectedRows > 0;
	}

There may be a time where you don't want to delete one record at a time, and instead would like to delete multiple in one go. This can be achieved by Dapper's internal mechanics, and passing a list of items to the ExecuteAsync() method, like so:

public async Task<bool> DeleteUsersBatchAsync(IEnumerable<string> userIds)
{
    const string sql = @"
        DELETE FROM ""User""
        WHERE UserId = @UserId;";

    await using var connection = CreateConnection();
    var affectedRows = await connection.ExecuteAsync(sql, userIds.Select(id => new { UserId = id }));

    return affectedRows > 0;
}

Dapper will iterate over the collection and execute the statement once per item. It's not a single batch query under the hood it's multiple executions, so for large datasets you'd want to consider a different approach – but for typical use cases it's clean and convenient.

Batch Processing With Dapper

For true batch processing in a single round trip, you would need to lean on SQL rather than Dapper itself. Dapper is just the messenger here, and the batching logic lives in the query.

The most common approach is using In / Any (depending on SQL database flavour):

public async Task<bool> DeleteUsersAsync(IEnumerable<string> userIds)
{
    const string sql = @"
        DELETE FROM ""User""
        WHERE UserId = ANY(@UserIds);";

    await using var connection = CreateConnection();
    var affectedRows = await connection.ExecuteAsync(sql, new { UserIds = userIds.ToArray() });
    return affectedRows > 0;
}

This sends a single query to the database with all the IDs, rather than one query per ID. Npgsql supports passing an array directly to ANY(), which is the PostgreSQL idiom for this.

Note: ANY(@UserIds) is PostgreSQL-specific syntax. If you were using SQL Server you'd use WHERE UserId IN @UserIds instead – Dapper has built-in support for expanding IN parameters when passed an IEnumerable.

In summary:

• Multiple executions: one round trip per item, simple but inefficient at scale, especially when deleting a lot of users, or their posts.

• ANY / IN: single round trip regardless of list size, much more efficient for larger datasets.

For most everyday use cases, the difference won't matter. But it's a good habit to reach for the single query approach when you know you're dealing with a collection.

Transactions With Dapper

If you cast your mind back to the seeding utility, you may have noticed a transaction was already being used there. Now it's time to understand what they are and why they matter.

A transaction guarantees that either all operations succeed, or none of them do. This is the atomicity principle: the database will never be left in a half-finished state.

Imagine the scenario where a new user signs up to the social media application, and you ask them to write their first post, during the registration process – meaning their account and their first post is stored in the same operation.

Without a transaction, if the user insert succeeds but the post insert fails, you're left with an orphaned user record in the database – an account with no post, and no way to know something went wrong.

If you're familiar with SQL, you may have written transactions directly like so:

BEGIN TRANSACTION;
    INSERT INTO "User" (UserId, Username ...) VALUES (...);
    INSERT INTO Post (PostId, ...) VALUES (...);
COMMIT;

With Dapper, rather than writing the transaction logic inside the SQL itself, you manage it from your C# code instead. Each SQL statement stays as its own focused block, and you wrap them together in a transaction at the application level. This gives you the same atomicity guarantee, but with the added benefit of being able to use C#'s try/catch to handle failures and trigger a rollback cleanly.

public async Task<bool> CreateUserWithPostAsync(User user, Post post)
{
    const string insertUserSql = @"
        INSERT INTO ""User"" (UserId, Username, FirstName, LastName, Avatar, Email, DOB)
        VALUES (@UserId, @Username, @FirstName, @LastName, @Avatar, @Email, @DOB);";

    const string insertPostSql = @"
        INSERT INTO Post (PostId, Likes, Content, Timestamp, UserId)
        VALUES (@PostId, @Likes, @Content, @Timestamp, @UserId);";

    await using var connection = CreateConnection();
    await connection.OpenAsync();
    await using var transaction = await connection.BeginTransactionAsync();

    try
    {
        await connection.ExecuteAsync(insertUserSql, user, transaction);
        await connection.ExecuteAsync(insertPostSql, post, transaction);
        await transaction.CommitAsync();
        return true;
    }
    catch (Exception)
    {
        await transaction.RollbackAsync();
        return false;
    }
}

It also means you can write some useful methods, which run particular SQL blocks conditionally. Take the below example: there are 3 different SQL blocks which can be run as part of the transaction insertUserSql, insertPostSql and logActivitySql.

For the below example, imagine you have an ActivityLog table that tracks user actions across the application. All three blocks are part of the same transaction, but only two of them are guaranteed to run. If the flag is inactive, the activity log is skipped entirely, and the transaction commits with just the user and post. If anything fails, all of it rolls back regardless.

public async Task<bool> CreateUserWithPostAndLogAsync(User user, Post post, bool logActivity)
{
    const string insertUserSql = @"
        INSERT INTO ""User"" (UserId, Username, FirstName, LastName, Avatar, Email, DOB)
        VALUES (@UserId, @Username, @FirstName, @LastName, @Avatar, @Email, @DOB);";

    const string insertPostSql = @"
        INSERT INTO Post (PostId, Likes, Content, Timestamp, UserId)
        VALUES (@PostId, @Likes, @Content, @Timestamp, @UserId);";

    const string logActivitySql = @"
        INSERT INTO ActivityLog (UserId, Action, Timestamp)
        VALUES (@UserId, 'SIGNUP', @Timestamp);";

    await using var connection = CreateConnection();
    await connection.OpenAsync();
    await using var transaction = await connection.BeginTransactionAsync();

    try
    {
        await connection.ExecuteAsync(insertUserSql, user, transaction);
        await connection.ExecuteAsync(insertPostSql, post, transaction);

        if (logActivity)
        {
            await connection.ExecuteAsync(logActivitySql, new { user.UserId, Timestamp = DateTime.UtcNow }, transaction);
        }

        await transaction.CommitAsync();
        return true;
    }
    catch (Exception)
    {
        await transaction.RollbackAsync();
        return false;
    }
}

Multi-mapping / Splits

So far, every query has returned data from a single table, mapped to a single object. But real applications rarely work that way. Data is relational, and you'll frequently need to query across multiple tables at once using a JOIN.

Dapper handles this through multi-mapping, which allows a single query to map results across multiple objects simultaneously. To demonstrate this, you're going to return a list of posts with their associated author's details populated (rather than just a UserId foreign key reference).

First, create the model used to store the combined data in your Models folder.

public sealed class PostWithAuthor
{
    public Post Post { get; init; } = null!;
    public User Author { get; init; } = null!;
}

Now add the following method to your repository (not forgetting to always add the method definition to your interface too).

public async Task<IReadOnlyList<PostWithAuthor>> GetPostsWithAuthorsAsync()
{
    const string sql = @"
        SELECT
            p.PostId,
            p.Likes,
            p.Content,
            p.Timestamp,
            p.UserId,
            u.UserId,
            u.Username,
            u.FirstName,
            u.LastName,
            u.Avatar,
            u.Email,
            u.DOB
        FROM Post p
        INNER JOIN ""User"" u ON p.UserId = u.UserId
        ORDER BY p.Timestamp DESC;";

    await using var connection = CreateConnection();

    var results = await connection.QueryAsync<Post, User, PostWithAuthor>(
        sql,
        (post, user) => new PostWithAuthor { Post = post, Author = user },
        splitOn: "UserId"
    );

    return results.AsList();
}

There is quite a bit going on here compared to the queries you have written so far, so let's unpack it.

SELECT Statement

Unlike previous queries where you could rely on SELECT *, column order matters here. Dapper needs to know where the Post columns end and the User columns begin in the result set. You're explicitly listing every column, with all Post columns first and all User columns second.

QueryAsync<Post, User, PostWithAuthor>

Rather than a single generic type, you are now passing three: the first two are the objects you want to map to, and the third is the return type. Dapper will split the result set into a Post and a User, and hand both to you to combine however you like.

The Mapping Function

(post, user) => new PostWithAuthor { Post = post, Author = user }

This is where you stitch the two objects together. Dapper passes you the mapped Post and User for each row, and you return the combined PostWithAuthor. This is also where you have full control: if you wanted to flatten the result into a single object rather than a nested one, you could do that here instead.

splitOn: "UserId"

This is the most important part to understand. The splitOn parameter tells Dapper the name of the column where the first object ends and the second begins. In this case, when Dapper encounters UserId for the second time in the result set, it knows everything from that point onwards belongs to the User object.

It defaults to Id – so if your split column were named Id, you wouldn't need to specify it at all. Since both Post and User share UserId as their identifier, you must specify it explicitly here.

A Common Mistake

Because splitOn works by column position, the column you split on must be the first column of the second object in your SELECT. If u.UserId were not the first User column listed, Dapper would split in the wrong place and you'd end up with incorrectly mapped data. It's the kind of bug that can be tricky to spot because no exception is thrown, the data is just wrong.

What Comes Next – Possible Additions

Use this tutorial as a base to build upon. The next steps are to look at how you could structure your project to make your repository tidier. For example, you could move your SQL commands into files of their own, and import them in to your repository, making your repository code slimmer.

To avoid this tutorial becoming too bloated, I tried to cover the key features of Dapper. Now you know the fundamentals, you could push your learning further to cover:

• QueryMultiple: execute several SQL statements in a single round trip. This is ideal for dashboard-style endpoints.

• Dynamic parameters: build queries conditionally using DynamicParameters, which is useful for search and filter scenarios.

• Endpoint implementation: add API endpoints to call your repository methods, injecting the IRepository into your minimal endpoints.

  For example:

app.MapPost("/insert-user", async (IRepository repository, User newUser) =>
{
	var success = await repository.InsertUserAsync(newUser);
	return success
		? Results.Ok($"User {newUser.Username} inserted successfully.")
		: Results.Problem("Failed to insert user.");
});

Final Thoughts

Dapper won't be the right tool for every project. If you're working with complex entity relationships, frequent schema changes, or a team heavily invested in LINQ, Entity Framework may be the better fit. And there's nothing wrong with that.

But when performance matters, when you need precise control over what's hitting your database, or when you're working with a schema you don't own, Dapper's transparency is hard to beat. You always know exactly what query is being executed, because you wrote it yourself.

The trade-off is straightforward: Entity Framework gives you speed of development, Dapper gives you speed of execution. Understanding both makes you a more well-rounded .NET developer – and knowing when to reach for each one is a skill in itself.

If you already know SQL, Dapper's learning curve is remarkably shallow. There's no magic, no conventions to memorise, no generated queries to second-guess. Just SQL, mapped cleanly to your C# objects, and as this tutorial has hopefully shown, that doesn't have to mean unsafe or hard to maintain.

Again, thanks for reading and I hope you have found this tutorial useful. If you'd like to chat about anything in this tutorial or hear about future articles, you can follow me on X/Twitter.

In C#, we typically solve this with inheritance hierarchies, marker interfaces, or wrapper objects – all of which add complexity and reduce type safety. But luckily, there's a better way: discriminated unions using the OneOf library.

You may be familiar with union types if you’ve programmed with TypeScript before, as they’re one of the pivotal features of the language. Union types are not a concept which can be found natively within C#, but they are planned for a future release. Until then, you can use the OneOf<T1,T2..> library.

In this article, I'll show you how OneOf brings F#-like discriminated unions to C#, enabling you to write cleaner, more expressive, and type-safe code across a variety of scenarios – from polymorphic return types to state machines, even elegant error handling.

Table of Contents

• What is OneOf?

• Installing OneOf

• Core Concepts

• Real-World Use Cases

• Other Use Cases

• Key Benefits of OneOf

• Conclusion

What is OneOf?

The OneOf package offers discriminated unions for C#, allowing you to return one of several predefined types from a single method. Unlike a Tuple, which bundles multiple values together (A and B), OneOf represents a choice (A or B or C).

Think of it as a type-safe way to say: "This method returns either type A, or type B, or type C" – and the compiler enforces that you handle all possibilities.

// Instead of this (returns both, whether you need them or not)
public (User user, Error error) GetUser(int id) { ...  }

// You can do this (returns one OR the other)
public OneOf<User, NotFound, DatabaseError> GetUser(int id) { ... }

Why OneOf Matters

• Type safety: The compiler ensures you handle every possible return type

• Self-documenting: Method signatures clearly show all possible outcomes

• No inheritance required: Returns different types without forcing them into a class hierarchy

• Pattern matching: Uses .Match() to handle each case exhaustively

• Flexibility: Supports 2, 3, 4+ different return types as needed

Installing OneOf

Option 1 (Recommended):

Using the terminal, navigate to your project folder and run the below command:

dotnet add package OneOf

Option 2:

Using your IDE (Visual Studio, Rider, or VS Code):

1. Right-click your project file

2. Select "Manage NuGet Packages"

3. Search for "OneOf"

4. Click Install

Core Concepts And Functionality

There are multiple core concepts you’ll need to understand to get the most out of the OneOf library and understand its real benefits. These are:

Union Types: One of Many

At its heart, OneOf represents a union type. A value that can be one of several predefined types at any given time. Think of it as a type-safe container that holds exactly one value, but that value could be any of the types you specify.

// This variable can hold a string OR an int OR a bool
// but only ONE at a time
OneOf<string, int, bool> myValue;

myValue = "hello";     // Currently holds a string
myValue = 42;          // Now holds an int
myValue = true;        // Now holds a bool

This is fundamentally different from a C# Tuple type, which holds multiple values simultaneously:

// Tuple: Holds ALL values at once (AND) 
var tuple = ("hello", 42, true); // Has string AND int AND bool

// OneOf: Holds ONE value at a time (OR) 
OneOf<string, int, bool> union = "hello"; // Has string OR int OR bool

Type Safety and Exhaustive Handling

OneOf isn't just convenient, it's compiler-enforced. When you work with a OneOf value, the compiler ensures that you handle every possible type within your .Match() method. This eliminates entire categories of bugs where you forget to handle a case.

For example:

OneOf<Success, Failure, Pending> result = GetResult();

// Compiler forces you to handle all three
result.Match(
    success => HandleSuccess(success),
    failure => HandleFailure(failure),
);

// Missing a case? Won't compile!

You’ll get a compiler warning and if you hover over it in your IDE or code editor, you’ll see a hint like so:

The .Match() Method

The .Match() method is one of OneOf's killer features. It requires you to provide a handler function for each possible type in your union, ensuring you never forget to handle a case.

Think of it like a type-safe switch statement that the compiler enforces:

OneOf<CreditCardInfo,PayPalUser,CryptoAccount> result = GetPaymentMethod(); // MasterCard

result.Match(
    creditCard => ProcessCreditCard(creditCard),
    paypal => ProcessPayPal(paypal),
    crypto => ProcessCrypto(crypto)
);

How .Match() works:

1. OneOf determines which type the value currently holds

2. It executes the corresponding handler function for that type

3. It passes the actual value (with the correct type) to your handler

4. It returns the result from whichever handler executed

The generic type ordering matters, especially in relation to the .Match() method and the defined handlers.

• Generic typing order: If you declare OneOf<CreditCard, PayPal, CryptoWallet>, then CreditCard is T0, PayPal is T1, and CryptoWallet is T2. That order determines which handler in .Match(...) will be executed, not its type.

• Handler parameter names are arbitrary: You can name them option1, foo, or creditCard. The name doesn’t determine the type, position does. The compiler binds the first handler to CreditCard, the second to PayPal, and third to CryptoWallet.

• Each handler receives a strongly-typed parameter corresponding to its position. When the first handler runs, its parameter is a CreditCard object (with full IntelliSense and compile-time checks).

• For readability, prefer meaningful names (for example, creditCard, payPal, crypto) rather than option1/2/3, as this was only for demonstration purposes.

Accessing Values

While .Match() is the recommended approach, OneOf also provides direct type checking and access, albeit quite cumbersome and not as intuitive.

OneOf<string, int> example = "hello";

// Check which type it contains
if (example.IsT0)  // Is it the first type (string)?
{
    string str = example.AsT0;  // Get it as a string
    Console.WriteLine(str);
}
else if (example.IsT1)  // Is it the second type (int)?
{
    int num = example.AsT1;  // Get it as an int
    Console.WriteLine(num);
}

You should avoid this approach in most cases for several reasons:

Firstly, you lose the compiler enforcement that makes .Match() so powerful. Want to add a third type later? The compiler won't remind you to handle it here, and your code could become brittle and be more prone to failure.

Secondly, it's verbose and cluttered. Instead of one clean .Match() call, you need multiple if-else blocks that make your code harder to read and maintain.

Thirdly, the T0, T1, T2 naming convention is positional and confusing. Which type was T0 again? You have to constantly refer back to the method signature to remember the order, which can become frustrating for yourself and development team.

Finally, it's error-prone. Nothing prevents you from forgetting to check IsT2 when dealing with three or more types.

Use .Match() whenever possible. Only resort to IsT0/AsT0 when you have a specific reason to check for just one type, and the others are irrelevant in the current code flow.

A Solution to Exception-Driven Control Flow

Many codebases overuse exceptions for control flow, making code harder to follow and debug. When you see a method call, there's no indication in the signature whether it might throw an exception or what type of errors to expect. This leads to several issues:

Hidden Control Flow:

// What can go wrong here? The signature doesn't tell you.
public User GetUser(int id)
{
    var user = _dbContext.Users.Find(id);
    if (user == null)
        throw new UserNotFoundException();  // Hidden jump in control flow!

    return user;
}

// Caller has no idea this can throw an exception
var user = _userService.GetUser(123);  // Might explode!
Console.WriteLine(user.Name);

Exceptions As Expected Outcomes

When a user enters an invalid email or a record isn't found, these aren't truly exceptional circumstances –they're expected, predictable outcomes that should be part of your normal business logic. Using exceptions for these scenarios treats routine validation as a crisis.

Performance Impact in Hot Paths

While not always significant, throwing exceptions involves stack unwinding which can be hundreds of times slower than returning a value. In tight loops or high-throughput APIs, this overhead accumulates quickly.

// Which exceptions should I catch? All of them? Specific ones?
try
{
    var user = _userService.GetUser(id);
    var order = _orderService.CreateOrder(user);
    var payment = _paymentService.ProcessPayment(order);
}
catch (Exception ex)  // Too broad? Catching things we shouldn't?
{
    // Which operation failed? Hard to tell.
    return StatusCode(500, "Something went wrong");
}

OneOf Provides a Cleaner Alternative

OneOf makes failures explicit, type-safe, and part of the method signature. When you see a method that returns OneOf<Success<T>, Failure>, you immediately know:

1. This method can fail

2. You must handle both success and failure cases

3. The compiler will enforce this

The following code shows how to implement it:

// Define your result types
public record Success<T>(T Value);
public record Failure(ErrorType Type, string[] Messages);

public enum ErrorType 
{
    Validation,
    NotFound,
    Database,
    Conflict,
}

// The signature now TELLS you this can fail
public OneOf<Success<User>, Failure> GetUser(int id)
{
    try
    {
        var user = _dbContext.Users.Find(id);

        if (user == null)
            return new Failure(ErrorType.NotFound, new[] { $"User {id} not found" });

        return new Success<User>(user);
    }
    catch (DbException ex)
    {
        return new Failure(ErrorType.Database, new[] { "Database error", ex.Message });
    }
}

// Usage: Now the caller MUST handle both cases - compiler enforces it
public IActionResult GetUserEndpoint(int id)
{
    var result = _userService.GetUser(id);

    return result.Match(
        success => Ok(success.Value),
        failure => failure.Type switch
        {
            ErrorType.NotFound => NotFound(new { errors = failure.Messages }),
            ErrorType.Database => StatusCode(500, new { errors = failure.Messages }),
            ErrorType.Validation => BadRequest(new { errors = failure.Messages }),
            ErrorType.Conflict => Conflict(new { errors = failure.Messages }),
            _ => StatusCode(500, new { errors = failure.Messages })
        }
    );
}

What makes this better?

• It’s self-documenting: The method signature explicitly states "this returns a User OR a Failure" – no hidden surprises.

• There’s compiler-enforced handling: Forget to handle the failure case? Compilation error. The compiler won't let you ignore potential failures.

• There’s clear intent: When you call a method returning OneOf<Success<T>, Failure>, you know immediately you need to handle both paths. No guessing about which exceptions might be thrown.

When to Still Use Exceptions:

The goal isn't to eliminate exceptions entirely, but to reserve them for truly exceptional circumstances while using OneOf for predictable, business-logic failures. You could still use exceptions in these scenarios:

• Truly unexpected failures (out-of-memory, hardware failures)

• Framework/library boundaries that expect exceptions

• Constructor failures (constructors can't return Result types)

• Third-party code contracts

Other OneOf Use Cases

Use Case 1: Polymorphic Return Types (Without Inheritance)

When you need to return different types based on logic but don't want to force inheritance:

// Different payment methods - no shared base class needed
public OneOf<CreditCardPayment, PayPalPayment, CryptoPayment> GetPaymentMethod(PaymentRequest request)
{
    return request.Method switch
    {
        "card" => new CreditCardPayment(request.CardNumber, request.CVV),
        "paypal" => new PayPalPayment(request.Email),
        "crypto" => new CryptoPayment(request.WalletAddress),
        _ => throw new ArgumentException("Unknown payment method")
    };
}
// Usage - compiler enforces handling all types
var payment = GetPaymentMethod(request);
payment.Match(
    card => ChargeCard(card),
    paypal => ProcessPayPal(paypal),
    crypto => ProcessCrypto(crypto)
);

Why this is better than inheritance:

• No artificial base class needed

• Each payment type can have completely different properties

• Clear, explicit handling of each case

• Easy to add new payment types (compiler will tell you everywhere to update)

Use Case 2: State Machines With Rich Data

Representing different states in a workflow where each state carries different information:

public class Order
{
    public OneOf<Pending, Processing, Shipped, Delivered, Cancelled> Status { get; set; }
}

public record Pending(DateTime OrderedAt);
public record Processing(DateTime StartedAt, string WarehouseId);
public record Shipped(DateTime ShippedAt, string TrackingNumber, string Carrier);
public record Delivered(DateTime DeliveredAt, string SignedBy);
public record Cancelled(DateTime CancelledAt, string Reason);

// Each state carries relevant data
var statusMessage = order.Status. Match(
    pending => $"Order placed on {pending.OrderedAt:d}",
    processing => $"Processing in warehouse {processing.WarehouseId}",
    shipped => $"Shipped via {shipped.Carrier}, tracking:  {shipped.TrackingNumber}",
    delivered => $"Delivered on {delivered.DeliveredAt:d}, signed by {delivered.SignedBy}",
    cancelled => $"Cancelled: {cancelled.Reason}"
);

Why not just use an enum?

• Enums only store the state – they can't carry additional data

• With OneOf, Processing knows which warehouse, and Shipped knows the tracking number offering more functionality and potential other logic to be carried out easily

• Type-safe access to state-specific data

• Impossible to access wrong data for a state (compiler prevents it)

Use Case 3: Multi-Channel Notifications

Sending notifications through different channels, each with different requirements:

public record EmailNotification(string To, string Subject, string Body);
public record SmsNotification(string PhoneNumber, string Message);
public record PushNotification(string DeviceToken, string Title, string Body);
public record InAppNotification(int UserId, string Message);

public async Task SendNotification(
    OneOf<EmailNotification, SmsNotification, PushNotification, InAppNotification> notification)
{
    await notification.Match(
        async email => await _emailService.SendAsync(email.To, email.Subject, email.Body),
        async sms => await _smsService.SendAsync(sms.PhoneNumber, sms.Message),
        async push => await _pushService.SendAsync(push.DeviceToken, push.Title, push.Body),
        async inApp => await _notificationRepo.CreateAsync(inApp.UserId, inApp.Message)
    );
}

// Usage
await SendNotification(new EmailNotification("user@example.com", "Welcome", "Hello! "));
await SendNotification(new SmsNotification("+1234567890", "Your code is 123456"));

Benefits:

• Could have a single, unified notification interface

• Each channel has exactly the parameters it needs

• No optional/nullable properties for irrelevant fields

• Clear routing logic

Use Case 4: File Format Handling

Handling different file types and data formats:

public record CsvData(string[] Lines);
public record JsonData(string Content);
public record ExcelData(IWorkbook Workbook);

public OneOf<CsvData, JsonData, ExcelData> LoadDataFile(string path)
{
    var extension = Path.GetExtension(path).ToLower();

    return extension switch
    {
        ". csv" => new CsvData(File.ReadAllLines(path)),
        ".json" => new JsonData(File.ReadAllText(path)),
        ".xlsx" => new ExcelData(LoadExcelFile(path)),
        _ => throw new UnsupportedFileFormatException(extension)
    };
}

// Process different formats uniformly
var data = LoadDataFile(filePath);
var records = data.Match(
    csv => ParseCsv(csv.Lines),
    json => ParseJson(json.Content),
    excel => ParseExcel(excel.Workbook)
);

This is perfect for:

• APIs that offer multiple export formats

• Import wizards that accept various file types

• Configuration loaders supporting multiple formats

Key Benefits of OneOf

OneOf shines when you have:

• Multiple valid return types that don't share a common base class

• Different data shapes for different scenarios

• Type-safe branching where you want the compiler to enforce handling all cases

• Domain modeling where different states carry different information

• Explicit outcomes that should be part of the method signature

It's essentially a way to say "this method returns A or B or C" in a type-safe way, forcing consumers to explicitly handle each possibility. This leads to more robust, self-documenting code that's harder to misuse.

Conclusion

OneOf brings the power of discriminated unions to C#, enabling more expressive and type-safe code across numerous scenarios. Whether you're modeling payment methods, order states, notification channels, or error handling, OneOf provides a clean, compiler-enforced way to handle multiple return types.

Start incorporating OneOf into your projects, and you'll find your code becomes more intentional, easier to maintain, and less error-prone.

As always, if you’ve enjoyed reading this article feel free to reach out on Twitter.

This is where loops come in. In this article, you’ll learn:

• How to create your first loop

• Benefits and caveats of using loops

• The different types of loops in C# and how to use them

• When it’s best to use each one

Table of Contents

• How to Use a For Loop in C

• How to Use a ForEach Loop in C

• How to Use a Do..While Loop in C

• How to Use a While Loop in C

• Final Thoughts: Choosing the Right Loop

Let’s get started. Open your preferred IDE or coding editor and create a new Console Application in .Net 8+.

How to Use a For Loop in C

A for loop repeats a block of code a set number of times by:

• Initialising a loop variable.

• Checking a condition before each iteration.

• Updating the loop variable after each iteration.

You can create a for loop with the code below:

// number of iterations
var totalIterations = 5

// the loop
for(int i = 0; i <= totalIterations; i++){
   Console.Write($"{i},");
}

// Output
0,1,2,3,4,5,

Breaking it down:

• for — declares the loop

• int i = 0; — sets the starting point for the loop variable i

• i <= totalIterations; — the condition to keep looping. The code inside the loop runs only if this is true.

• i++ — shorthand for “increase i by 1” after each iteration

Iterations and Zero

Why does the example print six numbers when totalIterations is 5? C# uses zero-based indexing. Counting from 0 → 5 includes six numbers: 0,1,2,3,4,5.

If you want to print 1 → 5 instead, start i at 1:

var totalIterations = 5;
for (int i = 1; i <= totalIterations; i++)
{
    Console.Write($"{i},");
}
// Output: 1,2,3,4,5

Tip:
In general, for loops are used for indexing/accessing elements in collections, so it’s common practice to start your loop variable at 0 and use < (less than) a given number or length of the collection.

Reversal of Direction

You can reverse a for loop by starting at the end and decrementing i:

for (int i = 5; i > 0; i--)
{
    Console.Write($"{i},");
}
// Output: 5,4,3,2,1

The loop checks if i > 0. After each iteration, i decreases by 1, printing numbers in descending order.

Other Uses of For Loops

Let’s say you want to access every other item in a list. This is where the power of for loops come in, and we can maximise our loop variable, using it as an index accessor.

public class Address
{
    public string Name { get; set; } = string.Empty;
    public string AddressLineOne { get; set; } = string.Empty;
    public int HouseNumber { get; set; } = default;
    public string PostCode { get; set; } = string.Empty;
    public string Telephone { get; set; } = string.Empty;
}

internal class Program
{
    public static void Main()
    {
        var addressBook = new List<Address>
        {
            new Address
            {
                Name = "Grant", AddressLineOne = "Developer Avenue", HouseNumber = 1, PostCode = "DV19 8EP",
                Telephone = "0102919 93020-92019"
            },
            new Address
            {
                Name = "Bill", AddressLineOne = "Developer Avenue", HouseNumber = 19, PostCode = "DV19 8EP",
                Telephone = "0102919 93020-92019"
            },
            new Address
            {
                Name = "Rebecca", AddressLineOne = "Developer Avenue", HouseNumber = 4, PostCode = "DV19 8EP",
                Telephone = "0102919 93020-92019"
            },
            new Address
            {
                Name = "Amy", AddressLineOne = "Rower Avenue", HouseNumber = 1, PostCode = "DV19 8EP",
                Telephone = "0102919 93020-92019"
            },
            new Address
            {
                Name = "Joe", AddressLineOne = "Olympic Drive", HouseNumber = 1, PostCode = "DV19 10E",
                Telephone = "0102919 93020-92019"
            }
        };

        for (var i = 0; i < addressBook.Count; i += 2)
        {
            Console.WriteLine($"Name: {addressBook[i].Name}, PostCode: {addressBook[i].PostCode}");
        }
    }
}

/* Ouput:
Name: Grant, PostCode: DV19 8EP
Name: Rebecca, PostCode: DV19 8EP
Name: Joe, PostCode: DV19 10E
*/

What’s Happening:

• i starts at 0 and increases by 2 (i += 2) each iteration

• addressBook[i] now accesses every other item

• This shows the power of using i as an index

So far we’ve seen how for loops give control over indexes and step sizes.

But sometimes you just want to loop through every item in a collection, without worrying about indexes. That’s where the foreach loop shines.

How to Use a ForEach Loop in C

A foreach loop iterates over any object that inherits from IEnumerable (lists, arrays, collections). It automatically accesses each item in order, so you don’t need an index.

How To Write a ForEach Loop

var characters = new List<string>{"Batman", "CatWoman", "The Joker","Harley Quinn"};

foreach(var character in characters){
    Console.WriteLine(character);
}

/* Output:
Batman
CatWoman
The Joker
Harley Quinn
*/

Key points:

• No need for indexes

• Works with any enumerable collection

• Cleaner, more expressive code

Caveats of ForEach Loop

No Indexing

You can’t directly access items with addressBook[i] inside a foreach. That’s because foreach works on IEnumerable, which doesn’t expose indexes.

Performance

A foreach loop has a small overhead compared to a for loop. In most cases this won’t matter, but in performance-critical code, a for loop may be faster.

Modifying Items

foreach gives you a copy of the current item, not a direct reference. That means you can’t reassign values to the list items inside the loop.

• You can read properties.

• You can’t update the items themselves (use a for loop for that).

foreach is ideal when you want to visit every item, but not control the number of iterations.

How to Use a Do..While Loop in C

do..while loops run code at least once, then repeat while a condition is true:

int num;
do {
    Console.Write("Enter a positive number: ");
    num = int.Parse(Console.ReadLine());
} while (num <= 0);

Console.WriteLine(num);

The above code requests a number to be entered within the console application if the condition is met. That is, if a positive number is provided, the code will not ask for another, exiting the loop.

Should the user enter a negative number, it would continue to loop, requesting a positive number to be entered.

What if you didn’t want the code to run at least once, and only if a condition is met? This where you can use a while loop.

How to Use a While Loop in C

while loops repeat code as long as a condition is true, but the body may never run if the condition is initially false:

We can use an example of a darts score board:

var sum = 0;
var dartsThrown = 0;
var random = new Random();

while (sum < 180 && dartsThrown < 3)
{
    var dartScore = random.Next(61); // 0–60
    sum += dartScore;
    dartsThrown++;
}

Console.WriteLine("Your score is " + sum);

While the player has darts to throw, the code will pick a number at random and increase their score.

Tip: Always include code that changes the condition, or you risk creating an infinite loop. An infinite loop, is a loop which never stops, and causes your application to break.

You’ve seen four different ways to repeat code in C#: for, foreach, do..while, and while. Let’s summarise when to use each one.

Final Thoughts: Choosing the Right Loop

C# gives us several types of loops. Choosing the right one makes your code readable, efficient, and intentional.

• For Loop: Use when you know how many times to run something, or when you need an index, like using arrays, skipping items. Use a for loop when you need more control over the iterative nature of the loop.

• ForEach Loop: Use when you want to iterate through every item in a collection without worrying about indexes.

• While Loop: Use when you don’t know in advance how many times to run the code, but a condition drives the loop.

• Do..While Loop: Use when the loop body must run at least once, such as for user input or retry logic.

By matching the loop type to your intent, your code will be correct, readable, and maintainable.

I hope this tutorial was useful, and as always I’d love to hear your thoughts and discuss further on social media. You can find me on twitter/x.

Micro frontends also allow large teams to share common components – such as headers, footers, and logins – across multiple applications, ensuring consistency and keeping their projects DRY (Don’t Repeat Yourself).

In this article, you will learn:

• How to set up a project and folder structure that implements a Micro Frontend (MFE) Infrastructure

• How to use and configure the @originjs/vite-plugin-federation to allow Module Federation (MF) usage with Vite projects.

• How to share and consume React components between apps.

• How to run and test your app with shared components locally

Table of Contents

• Pre-Requisites

• What Is Module Federation?

• Benefits of Module Federation

• Project Structure

• How to Create the Projects

• How to Install Dependencies

• How to Configure the Remote App

• The Vite Module Federation Plugin

• Key Constraints On Exported Modules

• How to Create the Remote Components

• How to Consume the Remote Components Within the Host

• How to Handle TypeScript Errors

• How to Add RemoteWrapperComponent to App.tsx

• How to Serve the Remote App and Run Your Host

• The True Power of Micro Frontends

• Final Thoughts

Pre-Requisites

• Node installed on your machine – you can get your download of Node here

• Familiarity with JS / TS and React

• Familiarity with Command Line / Terminal

What Is Module Federation?

Before we go any further, let’s talk about Module Federation (MF).

Module Federation is a technique in web development that allows multiple separate builds to work together as a single application. It enables the sharing of code between different, independent applications at runtime, rather than at build time. This means a host application can dynamically load and execute code from a remote application.

At its core, Module Federation uses a "host" and "remote" architecture. A host application is the main app that consumes shared code / components. A remote application is the one that exposes code to be consumed.

The remote app specifies which parts of its code, or "modules," are available for others to use. The host then references these modules and loads them as needed.

Benefits of Module Federation

Independent Deployment

Module Federation lets teams build and deploy their micro-frontends separately. This eliminates the need for full application redeployments, accelerating development and reducing risk.

Efficient Code Sharing

MF provides a native way to share code and dependencies between micro-frontends. This prevents code duplication, reducing bloat and ensuring consistency.

Performance Gains

By sharing dependencies, Module Federation reduces the overall bundle size and improves initial load times, as each micro-frontend doesn't download its own copy of common libraries.

Scalability and Maintainability

MF enables a scalable architecture by breaking down large applications into smaller, manageable micro-frontends. This makes the codebase easier to maintain and allows teams to work independently.

Analogy

Imagine building an online store. Traditionally, you’d create the entire site – homepage, product pages, cart, user profile – as one big application. A small cart change would require rebuilding and redeploying everything.

With Micro Frontends and Module Federation, the shopping cart can be its own app, built and maintained by a dedicated team. The main site simply imports it, allowing the cart team to release updates independently, speeding up development and improving focus.

This also works for organisations with multiple sites that need a consistent look. Shared components like a header, footer, or product card can be reused across sites with different purposes, such as hiring vehicles or selling furniture, ensuring visual consistency while keeping functionality unique.

Project Structure

You will need to create two projects:

• host – this will act as your host application

• remote – this will expose the components you want to share

How to Create the Projects

Run the following commands in your terminal to create your root project folder and your two Vite projects:

# create micro-frontends directory for two vite projects, and navigate to folder
mkdir micro-frontends; cd micro-frontends

Create a Git Repository (Optional)

Using the below command you can create a Git repository for source control.

# initiate git repo
git init

# create host application vite app
npm create vite@latest host-app

# once submitted the command, select React and press Enter, 
Select a framework:
│  ○ Vanilla
│  ○ Vue
│  ● React
│  ○ Preact
│  ○ Lit
│  ○ Svelte
│  ○ Solid
│  ○ Qwik
│  ○ Angular
│  ○ Marko
│  ○ Others

# select Typescript + SWC and again press Enter
Select a variant:
│  ○ TypeScript
│  ● TypeScript + SWC
│  ○ JavaScript
│  ○ JavaScript + SWC
│  ○ React Router v7 
│  ○ TanStack Router
│  ○ RedwoodSDK 
│  ○ RSC

Once this is done, navigate back to the root project folder (micro-frontends):

# navigate back
cd ../

# create remote-app 
npm create vite@latest remote-app

# follow instructions as before to select React, Typescript + SWC

You now have your two projects, host-app and remote-app.

How to Install Dependencies

Open the micro-frontends folder in your preferred IDE / Code Editor. In this tutorial I’ll be using VS Code.

Tip: You can open the current folder in VS Code via your terminal using the following command code . if you’ve already added code to you PATH.

Once you’ve opened VS Code, open the terminal and run the following command:

cd host-app && npm install -D @originjs/vite-plugin-federation

and then run:

cd ../remote-app && npm install -D @originjs/vite-plugin-federation

Styling

To see styling like my examples, you need to add Tailwind CSS to both your remote and host applications. You can find instructions on how to do so here

How to Configure the Remote App

In order to be able to utilise modules and components from your remote applications, you need to configure your application to expose those modules, and your host app to consume them.

Use the following configurations in your apps to allow your components to be exposed and consumed – don’t worry about the components just yet, you’ll create them soon.

Host App – Vite.config.ts

In the host app, open vite.config.js and add the following configuration:

//host - vote.config.js
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import federation from "@originjs/vite-plugin-federation";


export default defineConfig({
  plugins: [
    react(),
    federation({
      name: "host_app",
      remotes: {
        remote_app: "http://localhost:5001/assets/remoteEntry.js",
      },
      shared: ["react", "react-dom"],
    }),
  ],
  build: {
    modulePreload: false,
    target: "esnext",
    minify: false,
    cssCodeSplit: false,
  },
});

Remote App – Vite.config.ts

In the remote app, open vite.config.js and add the following configuration:

// remote - vite.config.js
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import federation from "@originjs/vite-plugin-federation";

export default defineConfig({
  plugins: [
    react(),
    federation({
      name: "remote_app",
      filename: "remoteEntry.js",
      exposes: {
        "./Button": "./src/components/Button",
        "./Header": "./src/components/Header",
      },
      shared: ["react", "react-dom"],
    }),
  ],
  build: {
    modulePreload: false,
    target: "esnext",
    minify: false,
    cssCodeSplit: false,
  },
  preview: {
    port: 5001,
    strictPort: true,
    cors: true,
  },
});

Explanation of Vite Configuration:

1. plugins: array where you tell Vite which plugins to use when it:

• Runs your dev server

• Builds your production bundle

Each plugin is basically a little (or big) piece of code that hooks into Vite’s build pipeline to add extra features – for example:

• Adding React JSX/TSX support (@vitejs/plugin-react)

• Enabling Module Federation (@originjs/vite-plugin-federation)

2. build: Controls how Vite produces the production build. You don’t need to worry too much about this for the purpose of this tutorial.

3. preview: Controls how the application is served / previewed:

• Useful in microfrontend setups where a fixed port and CORS enabled are needed so other apps can fetch your remote modules.

• strictPort: true ensures predictable networking – avoids “it works on my machine” issues with random ports.

The Vite Module Federation Plugin

You need to configure your Vite Module Federation plugin to inform it what components are to be consumed and exposed. Let’s take a look at the configured properties:

• name: The unique identifier for your remote application in a Module Federation setup. This is the name other applications (hosts) will use when they declare your app as a remote.

• filename: This is the name of the file that your host will load when it tries to retrieve your exposed modules.

• exposes: A mapping of public module names → local file paths. This is how you decide which parts of your code are available to be consumed remotely.

exposes: {
  "./Button": "./src/components/Button",
  "./Header": "./src/components/Header"
}

The key ("./Button") is the public module name – the name that other apps (the host) will use when importing the module from your remote.

How It Works:

• Key ("./Button") is the exposed identifier other apps can request.

• Value ("./src/components/Button") is the actual file path inside your project.

For example, if your remote’s name is "remote_app", the host can import like this:

import Button from "remote_app/Button";

Under the hood, "remote_app" matches the remote’s name in its federation() config and Button matches the "./Button" key in exposes.

• shared: dependencies that should be shared between the host and remote. It avoids shipping duplicate copies of large libraries (like React), ensuring the host and remote use the same instance – you can read more here about the possible configurations.

• remotes: A mapping of remote app names → the URL to their remoteEntry.js file. This tells the host where to fetch the exposed modules at runtime.

remotes: { remote_app: "http://localhost:5001/assets/remoteEntry.js" }

The key remote_app must match the name in the remote’s config.

The value is the full URL to the remote’s entry file (served in dev or deployed in prod). Remember we set strictPort:true earlier – this is why. We need to ensure we’re pointing at the correct domain & port.

Key Constraints On Exported Modules

Naming constraints and rules

The key in exposes ("./Button"):

• Must start with ./ (per Module Federation spec).

• Must be unique within the remote.

• Is case-sensitive.

• This is the public module path the host will request.

• Doesn’t have to match the filename, but matching is a good convention for ease of reading

The file you point to ("./src/components/Button"):

• Can export default, named exports, or both.

• The host can import default or named exports, same as any ES module:

    // Default export
    import MyButton from 'remote_app/Button';
  
    // Named export
    import { SpecialButton } from 'remote_app/Button';
  

The import name:

• Completely up to the host developer when importing a default export.

• Must match exactly for named exports.

How to Create the Remote Components

Ok, so you’ve created your project structure, and you’ve setup your vite.config.ts file to allow for exposing and consuming your shared assets. Next you will create the remote components.

Button Component

Let’s say you want to create a button component which will be shared across all your host applications, as you want to keep consistency. You can do this as below:

Navigate to the remote-app folder and create a new file called Button.tsx in src/components this will ensure it matches the configured federation plugin.

// remote - ./src/components/Button.tsx
import React from "react";

interface ButtonProps {
  text: string;
  onClick?: () => void;
}

const Button: React.FC<ButtonProps> = ({ text, onClick }) => {
  return (
    <button
      onClick={onClick}
      className="px-4 py-2 bg-green-500 text-white rounded hover:bg-green-600 hover:cursor-pointer"
    >
      {text}
    </button>
  );
};

export default Button;

You now have a re-usable Button component which has some base styling but allows for configuration of what the button does by passing in a onClick() argument.

Header Component

Sticking with the theme of consistency, you want to create a <header/> component which you can use on all your organisation’s websites, ensuring a themed appearance on all applications.

Like before, create a Header.tsx file within src/components/, and paste in the following code:

// remote - .src/components/Header.tsx
import React from "react";

const Header: React.FC = () => {
  return (
    <header className="bg-gray-800 text-white p-4">
      <h1 className="text-2xl">Remote App Header</h1>
      <p className="text-white">Hi, Grant</p>
    </header>
  );
};

export default Header;

I’ve kept it simple, as this tutorial is for proof of concept purposes rather than aesthetic / real-world components.

How to Consume the Remote Components Within the Host

You have your remote components created, so next you need to get them into your host application and begin using them. This is quite simple now that you’ve already setup your vite.config.ts.

You could import the components into your App.tsx, but this is not best practice as it can bloat your App.tsx (entry point component). I’ve opted to create a RemoteWrapperComponent which pulls in the remote components and handles the business logic.

RemoteComponentWrapper:

Create a file called RemoteComponentWrapper.tsx in src/components, pasting the following code:

// host - ./src/components/RemoteComponentWrapper.tsx
import React, { Suspense } from "react";

const RemoteHeader = React.lazy(() => import("remote_app/Header"));
const RemoteButton = React.lazy(() => import("remote_app/Button"));

const LoadingSpinner = () => (
  <div className="flex justify-center p-4">
    <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-gray-900"></div>
  </div>
);

export const RemoteComponentWrapper = () => {
  return (
    <div className="p-4">
      <Suspense fallback={<LoadingSpinner />}>
        <RemoteHeader />
      </Suspense>

      <div className="mt-4">
        <Suspense fallback={<LoadingSpinner />}>
          <RemoteButton
            text="Remote Button"
            onClick={() =>
              alert(
                "Well done you've imported the MF remote component successfully"
              )
            }
          />
        </Suspense>
      </div>
    </div>
  );
};

This component acts as a wrapper, handling some very simple business logic such as loading your remote components, handling a loading spinner whilst waiting for the remote, and passing your onClick event to the remote button.

Why Use React.lazy()?

The import with React.lazy isn’t required for Module Federation components – it’s more of a best practice for React apps when the remote module is:

• Loaded asynchronously at runtime, which Module Federation remotes almost always are

• You want React to handle the loading state and code-splitting gracefully – shown using the Suspense component

React.lazy + <Suspense> gives React a built-in way to pause rendering until the component is ready. Without it, you’d need manual loading state handling.

It also keeps your components looking “normal.” With React.Lazy, <RemoteHeader/> is just another component in your JSX.

Without it, you’d need something like:

const [Header, setHeader] = useState(null);

useEffect(() => {
  import("remote_app/Header").then(m => setHeader(() => m.default));
}, []);

return Header ? <Header /> : <LoadingSpinner />;

…which is messier and repeats for every remote component.

How to Handle TypeScript Errors

Inside your RemoteWrapperComponent you’re going to see the following error on your Button and Header imports.

Cannot find module 'remote_app/Button' or its corresponding type declarations.ts (2307)

You get this error because the remote modules are not defined with types, so both your remote and your host doesn’t know what this imported component is, nor does it know its structure (a key part to TypeScript development).

To fix this you will need to provide your host app with custom types.

Add a Type Declaration File

A type declaration file (if you’re unaware of them) has a .d.ts suffix.

Within your host app, create a file in src/types called remote-app.d.ts. Naming the file in this way lets us know the declarations within are related to the remote-app. This is useful especially when consuming multiple remotes.

Copy and paste the following declarations into your remote-app.d.ts file:

// host - ./src/types/remote.d.ts
declare module "remote_app/Button" {
  const Button: React.FC<{
    text: string;
    onClick?: () => void;
  }>;
  export default Button;
}

declare module "remote_app/Header" {
  const Header: React.FC;
  export default Header;
}

Now if you return to your RemoteWrapperComponent your errors should be gone. If they aren’t, restart your IDE (in VS Code you can open your command palette and select Restart Typescript Server).

How to Add RemoteWrapperComponent to App.tsx

Import the RemoteWrapperComponent into App.tsx.

I’ve removed all the boilerplate code and replaced with some basic styling to allow us to easily see what is the host, and what are the remote components.

Copy and paste the following code into your host App.tsx:

// host - ./src/App.tsx
import viteLogo from "/vite.svg";
import "./App.css";
import "./index.css";
import { RemoteComponentWrapper } from "./components/RemoteComponentWrapper";

function App() {
  return (
    <>
      <div className="px-6 border-2">
        <div className="flex justify-center items-center">
          <img src={viteLogo} alt="Example" />
        </div>
        <h1 className="text-2xl">Host Application</h1>
        <p>
          {" "}
          Welcome to the Host application, below are the components pulled from
          the remote application
        </p>
        <RemoteComponentWrapper />
      </div>
    </>
  );
}

export default App;

How to Serve the Remote App and Run Your Host

Due to how Vite works, you need to build the application before you preview / serve the application.

Make sure that your package.json file’s scripts block looks like this:

# remote-app
"scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "lint": "eslint .",
    "preview": "vite preview --port 5001 --strictPort",
    "serve": "npm run build && npm run preview"
  },

# host-app
"scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "lint": "eslint .",
    "preview": "vite preview --port 5000 --strictPort",
    "serve": "npm run build && npm run preview"
  },

In your terminal run:

cd ./remote-app

# run a build, and run / load the app on port 5000
npm run serve

You should see something like this:

Now you can run the host application by doing the same:

# change to the host-app in another terminal 
cd ../host-app

# build and run the application
npm run serve

If you open the localhost:5000 you should now see your host application with the remote components:

Next, if you click the button, you can see that it shows the message you configured from within the RemoteWrapperComponent:

The True Power of Micro Frontends

The true power of micro frontends lies in their ability to update the remote components, without the need to rebuild the host. To fully demonstrate this, keep the host running, and update the Button component on your remote-app.

Let’s update the remote components. Use the below code to update both the Button and Header components:

// remote - ./src/components/Header.tsx
import React from "react";

const Header: React.FC = () => {
  return (
    <header className="bg-gray-800 text-white p-4">
      <h1 className="text-2xl">Updated Remote App Header</h1>
      <p className="text-white">Hi, Grant</p>
    </header>
  );
};

export default Header;

// remote - ./src/components/Button.tsx
import React from "react";

interface ButtonProps {
  text: string;
  onClick?: () => void;
}

const Button: React.FC<ButtonProps> = ({ text, onClick }) => {
  return (
    <button
      onClick={onClick}
      className="px-4 py-2 bg-red-500 text-white rounded hover:bg-red-600 hover:cursor-pointer"
    >
      {text}
    </button>
  );
};

export default Button;

Once you’ve updated the remote components, run the following command in your remote-app folder:

npm run serve

Next, refresh your host app in the browser and you will see the updated app:

The update to the remote components is visible immediately, without restarting or rebuilding the host app. This highlights a key benefit of micro frontends: shared components are fetched from their own server via the remote.js file, enabling independent updates.

Final Thoughts

You've successfully built and deployed a micro frontend architecture – congrats! This basic implementation demonstrates the true power of Module Federation and the ability to update shared components without needing to rebuild and redeploy the entire host application.

This independence can dramatically accelerate development cycles and empower teams to work more autonomously.

I hope you’ve learned something from this article, and as always for more tutorials and discussions, connect with me on twitter/x.

In this article, you'll learn about:

• What a JSON Web Token (JWT) is

• How JWTs are structured and created

• Different JWT signing techniques and algorithms (Symmetric vs. Asymmetric)

• How JWTs are used in real-world authentication flows

• Important security best practices for using JWTs

Table of Contents

• What is a JWT?

  • JSON Web Tokens Are Made Of Three Elements

  • Asymmetric Signing (RS256) Explained

  • Analogy: The Lock and Key for Asymmetric Signatures

• Symmetric Signing: HS256 (HMAC with SHA-256)

  • How HS256 Verification Works

• JWTs in Action: A Typical Authentication Flow

• JWT Security Best Practices & Considerations

What Is a JWT?

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.
— Introduction to JWT by jwt.io

While accurate, this definition can be a bit dense at first glance. Imagine you want to send someone a sealed, tamper-proof message. That's essentially what a JSON Web Token (JWT) is. It's a secure message, a special kind of message designed to be sent between two parties which can be assured it came from an expected sender.

Each JWT is digitally signed using either a secret code (for symmetric algorithms like HMAC) or a private key (for asymmetric algorithms like RSA or ECDSA).

This secret code or private key is known only to the system that issues the JWT (often called an authentication provider, like Auth0, AWS Cognito, or Firebase Auth, which handles user logins and identity).

This signature proves two things:

1. Authenticity: It proves the message really came from who it claims to be from.

2. Integrity: It proves that the message hasn't been changed or tampered with since it was signed. If even one character is altered, the signature won't match, and you'll know something is wrong, meaning the contents of the JWT can't be trusted.

JSON Web Tokens Are Made of Three Elements

JWTs are made up of 3 key parts:

1. Header

2. Payload

3. Signature

Header

The header contains metadata information about the token. Think of it like a label on a package – it tells you what’s inside and how it was prepared.

Typically, the header contains:

alg: This specifies the algorithm used to sign the JWT. Common algorithms are HS256 (HMAC with SHA-256) or RS256 (RSA with SHA-256).

typ: This specifies the type of token, which is almost always JWT for standard JSON Web Tokens.

Example (decoded):

{ 
  "alg": "RS256",
  "typ": "JWT" 
}

Payload

This is the second part of the JWT, and it's where the real data or "claims" are stored. Claims are statements about an entity (usually a user) and any other additional data. Using the previous analogy of a package, think of it as the “contents” of the package.

There are three types of claims:

1. Registered Claims: These are predefined claims that are recommended for common use cases. They are not mandatory but are very useful for interoperability. These include:

• iss – issuer, who issued the token (for example, your application’s domain)

• sub – subject, the subject of the token (for example, a User’s ID)

• aud – audience, the audience of the token (that is, who the token is intended for – for example, a specific API)

• exp – expiration, the expiry date as a timestamp

• iat – issued at, when the token was issued as a timestamp

• nbf – not before, when the token becomes valid (that is, the token cannot be used or deemed valid before this timestamp)

• jti – JWT ID, a unique identifier for the token, useful for preventing replay attacks or blacklisting

2. Public Claims: These can be defined by anyone using JWTs. To avoid naming conflicts, it's a good practice to register them or define them using a unique identifier like a URI.

3. Private Claims: These are custom claims created to share specific information between parties who agree on using them. They are entirely up to you and your application's needs.

Example payload:

{
  "sub": "1234567890", //  subject
  "name": "John Doe", // private claim
  "admin": true, // private claim / role
  "iat": 1678886400, // Issued at a specific timestamp
  "exp": 1678890000  // Expires at a specific timestamp
}

Like the header, this JSON object is also Base64Url encoded (a URL-safe variant of Base64 encoding) to form the second part of the JWT string.

Important Note: The payload is encoded*, not encrypted.* This means that anyone can easily decode the JWT and read its contents. Never put sensitive information (like passwords) directly into the payload unless the entire JWT itself is encrypted (which is a separate process called JWE - JSON Web Encryption). The security of a standard JWT comes entirely from the signature, which prevents tampering.

Signature

The signature, as we've already discussed, is the most important part of the JWT. Without it, there's no protection applied to the JWT, meaning no way to validate the origin of the token or its integrity.

The signature is created by taking the encoded header, the encoded payload, and a secret key (or a private key if using asymmetric algorithms like RSA). These are then run through the cryptographic algorithm specified in the header (alg field). For HS256, a shared secret key is used. For RS256, a private key is used to sign, and a corresponding public key is used to verify. We’ll get on to verification soon.

Think of it like a tamper-proof seal on your package, or even better, a wax seal on a letter. If you receive your letter and the wax seal has been broken, you'd naturally believe the contents of the letter may not be original and therefore can't be trusted.

In pseudo-code it would look like this:

Signature = Algorithm( Base64Url(Header) + "." + Base64Url(Payload), SecretKey )

The result of this signing process is the signature, which is also Base64Url encoded to form the third part of the JWT string.

At the end of the whole process your JWT would look like this:

base64EncodedHeader.base64EncodedPayload.base64EncodedSignature

Asymmetric Signing (RS256) Explained

When a JWT uses an algorithm like RS256 (RSA Signature with SHA-256), it employs an asymmetric cryptographic process involving a public and private key pair. This is where the core magic of proving authenticity and integrity happens without needing to share a secret.

The Signing Process (by the Issuer)

The sender (the server that issues the JWT, like Auth0) possesses the private key. This key is kept absolutely secret and secure. Here are the steps:

1. Prepare the data: The server takes the header (which includes the algorithm) and the payload. It Base64Url-encodes them, and then concatenates them with a dot: Base64Url(Header) + "." + Base64Url(Payload).

   For example, with this header:

    {
      "typ": "JWT",
      "alg": "RS256"
    }
   

   And this payload:

    {
      "sub": "1234567890",
      "name": "John Doe",
      "admin": true,
      "iat": 1751494086,
      "exp": 1751497686
    }
   

   This would create a Base64Url-encoded header.payload string like the animated example below:

   

2. Calculate the hash: It then calculates a hash (using SHA-256 in this case) of this combined header and payload string.

3. Sign the hash: Finally, it signs this hash using its private key. This cryptographically transformed hash is the signature part of the JWT.

The JWT is then formed by concatenating the Base64Url-encoded header, the Base64Url-encoded payload, and the Base64Url-encoded signature, separated by dots: header.payload.signature.

The top segment below shows the full JWT token (header.payload.signature):

The Verification Process

This is where the magic happens, and it's often a point of confusion. The public key doesn't "decrypt" the original data like a symmetric key does. Instead, it performs a unique verification process.

The receiver (the client or another server that needs to verify the JWT) possesses the public key. This key does not need to be kept secret – it can be freely distributed.

Here's a step-by-step explanation:

1. Separate the parts: The first thing the receiver does is split the incoming JWT string into its three Base64Url-encoded components: the Header, the Payload, and the Signature.

2. Obtain the public key: The verifier needs the public key that corresponds to the private key used by the issuer. Public keys are often available via a JWKS (JSON Web Key Set) endpoint (for example, your-domain.com/.well-known/jwks.json).

3. Re-create the data to be hashed: The receiver takes the received, Base64Url-encoded Header and the received, Base64Url-encoded Payload. It then combines them exactly as the issuer did: EncodedHeader.EncodedPayload.

4. Compute a local hash (Hash A): This combined string is then put through the same hashing algorithm (for example, SHA-256) that was specified in the JWT's header. This produces a new, locally computed hash (let's call this "Hash A"). This local hash represents what the content should look like if it hasn't been tampered with.

5. "Unsign" the received signature with the public key to get the original signed hash (Hash B): This is the core cryptographic step. The verifier uses the public key (obtained in step 2) to perform a mathematical operation on the received signature. This operation does not create a new signature for comparison. Instead, it effectively "unsigns" or "decrypts" the signature to reveal the original hash ("Hash B") that was produced by the issuer's private key.

   • Crucial Point: This process is for verifying authenticity, not decrypting confidential data. The public key confirms that the signature was indeed created by the corresponding private key, and as part of that confirmation, it returns the original hash that was signed.

6. Compare the hashes: The verifier now has two hashes:

   • Hash A: The hash it computed locally from the received header and payload (from step 4).

   • Hash B: The original hash that was extracted from the received Signature using the public key (from step 5)

7. If Hash A matches Hash B: It proves two critical things:

   1. Authenticity: The token was indeed signed by the legitimate holder of the corresponding private key (for example, Auth0).

   2. Integrity: The content of the header and payload has not been tampered with since it was originally signed. If even a single character in the header or payload were changed, Hash A would be different, and it would not match Hash B. In this case, the JWT is considered valid and its contents can be trusted.

8. If the hashes do NOT match: The token is considered invalid and must be rejected. This indicates either that the JWT was signed by an unauthorised party (a forged token) or that its header or payload has been altered after it was signed.

Analogy: The Lock and Key for Asymmetric Signatures

Private Key: A special, unique key that can lock a box (create a signature). Only the owner has this key.

Public Key: A widely distributed key that can test if a box was locked by the corresponding private key. It can't lock a new box, but it can confirm if an existing lock is authentic.

You don't re-lock the box with the public key. You use the public key to check if the existing lock (the signature) is genuine and corresponds to the contents of the box.

Symmetric Signing: HS256 (HMAC With SHA-256)

While RS256 uses a pair of keys (private for signing, public for verifying), many JWTs you'll encounter are signed symmetrically, most commonly with the HS256 algorithm. HS256 stands for HMAC (Hash-based Message Authentication Code) with SHA-256.

The fundamental difference here is the use of a single, shared secret key for both signing and verification.

How HS256 Signing Works

1. Shared secret key: The issuer (for example, your authentication provider) possesses a single, confidential secret key. This key is known only to the issuer and any parties (like your API) that need to verify the token.

2. Combine header and payload: Just like with asymmetric signing, the issuer takes the Base64Url-encoded Header (which specifies "alg": "HS256") and the Base64Url-encoded Payload, and joins them with a dot.

3. Apply HMAC-SHA256: This combined string is then fed into the HMAC-SHA256 algorithm along with the secret key. The HMAC algorithm uses the secret key to create a unique hash (the signature) of the data. In pseudo-code, it looks like this:

   Signature = HMAC-SHA256( Base64Url(Header) + "." + Base64Url(Payload), SecretKey )

4. Form the JWT: The resulting signature (which is also Base64Url-encoded) is appended to the header and payload with a dot, forming the complete JWT: base64EncodedHeader.base64EncodedPayload.base64EncodedSignature.

How HS256 Verification Works

When a receiver gets an HS256-signed JWT, it goes through a verification process.

First, it separates the parts. The JWT is split into its three Base64Url-encoded components: Header, Payload, and Signature, as we did with asymmetric JWTs.

Then, it obtains the shared secret key. The receiver must also possess the exact same secret key that the issuer used to sign the token. This key is not publicly distributed like a public key – it must be securely provisioned to any entity that needs to verify tokens.

Next, it re-calculates the signature. The receiver does this by taking the received Base64Url-encoded Header and Payload, combining them, and then re-applying the HMAC-SHA256 algorithm using the same secret key. This produces a new, locally computed signature.

Finally, the receiver compares the signature it just calculated locally with the signature it received as part of the JWT.

• If the two signatures match: The token is considered valid. This confirms its authenticity (it came from someone who knows the secret) and integrity (it hasn't been tampered with).

• If the signatures do NOT match: The token is invalid and must be rejected. This indicates either tampering or that it was signed with a different, unknown secret key.

Key Differences and Considerations:

• Key management: With HS256, the secret key must be securely shared and kept confidential by all parties involved in both signing and verifying. This can be more challenging to manage securely at scale compared to the public/private key model, where only the private key needs strict secrecy.

• Performance: HS256 is generally faster to compute than asymmetric algorithms like RS256, making it suitable for high-volume scenarios where the secret key can be securely distributed.

JWTs in Action: A Typical Authentication Flow

Now that you understand how JWTs are structured and signed, let's look at how they're typically used in a real-world web application. This authentication flow is a common pattern you'd encounter.

Step 1: User Logs In:

A user opens a client application (for example, a web browser, mobile app) and enters their login credentials (username and password).

The client sends these credentials securely (always over HTTPS!) to an authentication server (like Auth0, AWS Cognito, or your own backend's authentication endpoint).

Step 2: Authentication Server Issues JWT:

Then the authentication server verifies the user's credentials. If valid, it generates a new JWT. This JWT contains claims (like the user's ID, roles, expiration time) in its payload and is digitally signed by the server's private key (for asymmetric algorithms like RS256) or secret key (for symmetric algorithms like HS256).

The server then sends this signed JWT back to the client.

Step 3: Client Stores JWT:

The client receives the JWT and typically stores it in a secure location, such as browser memory storage, session storage, or an HTTP-only cookie. The method of storage depends on the client type and security considerations.

Step 4: Client Makes API Calls:

When the user wants to access a protected resource on a backend API (for example, their profile data, a private feed), the client includes the JWT in the request.

The standard way to do this is by sending the token in the Authorization header of the HTTP request, prefixed with the word Bearer:

Authorization: Bearer <your_jwt_here>

Step 5: API Verifies JWT & Authorises Request:

Now, the backend API receives the request and extracts the JWT from the Authorization header. The API then performs the JWT verification process depending on the algorithm:

• It checks the token's claims, especially the exp (expiration) claim, to ensure it's still valid.

• If the token is valid, the API trusts the claims within the payload (for example, the user's ID) and proceeds to fulfill the request, potentially using the user's roles to determine if they have permission to access the requested resource.

• If the token is invalid (bad signature, expired, and so on), the API rejects the request, typically with an HTTP 401 Unauthorised status.

This flow is powerful because JWTs are stateless: once issued, the authentication server doesn't need to keep a record of active sessions. The API can verify the token independently, which simplifies scaling and reduces server load.

JWT Security Best Practices and Considerations

While JWTs offer powerful authentication capabilities, using them securely requires careful attention to best practices. Misconfigurations or oversight can lead to significant vulnerabilities.

Always Use HTTPS/TLS:

Crucial: JWTs are encoded, not encrypted, by default. This means anyone who intercepts the token during transmission can easily read its payload. Therefore, JWTs (and all authentication traffic) must always be transmitted over HTTPS (TLS) to encrypt the communication channel itself and prevent eavesdropping.

Protect Your Signing Keys:

Whether it's a private key (for RS256) or a shared secret key (for HS256), these keys are paramount. If an attacker gains access to your signing key, they can forge valid JWTs, impersonate users, and compromise your system. Store these keys securely, preferably in dedicated key management services.

Keep Access Tokens Short-Lived (exp claim):

You should always set short expiration times (for example, 5-15 minutes) for your JWTs used as access tokens. This minimises the window of opportunity for an attacker if a token is compromised.

Since JWTs are stateless, they are hard to revoke immediately once issued. A short lifespan is your primary defense against compromised tokens.

Implement Refresh Tokens (for Longer Sessions):

To maintain user experience with short-lived access tokens, use refresh tokens. A refresh token is a separate, longer-lived token (usually stored more securely) that can be exchanged for a new, short-lived access token when the current one expires, without requiring the user to re-authenticate. Refresh tokens can be revoked by the server, offering better control.

Never Put Sensitive Data in the Payload:

Reiterating this crucial point: the JWT payload is Base64Url encoded, which is easily reversible. Do not put passwords, highly sensitive PII (Personally Identifiable Information), or confidential business data directly into the JWT payload. Only include non-sensitive or publicly available information, or data that's already encrypted by other means.

Validate ALL Claims on Verification:

When verifying a JWT, don't just check the signature. Always validate all relevant claims, including:

• exp (Expiration): Ensure the token hasn't expired.

• iss (Issuer): Verify the token came from the expected authentication server.

• aud (Audience): Ensure the token is intended for your specific API/application.

• nbf (Not Before): Check if the token is active yet.

Consider Token Revocation (for critical cases):

For situations requiring immediate revocation (for example, user password change, account deactivation), typical stateless JWTs are challenging. Strategies include:

• Short expiration times (as above).

• A blacklist/revocation list: Store the jti (JWT ID) of revoked tokens in a database, checking this list on every request. This adds a stateful lookup but provides immediate revocation.

Thanks for reading!

I hope you’ve found this tutorial useful, and as always if you want to ask any questions or hear about upcoming articles, you can always follow me on ‘X’, my handle is @grantdotdev and follow by clicking here.

In this article, I’ll teach you about the React Hook Form library, HTML attributes, and development considerations to make sure your site’s available for all, focusing on:

• blind or visually impaired users, who may use a screen reader

• better user feedback

• visual queues for all

• design considerations for all

Whilst following along with this tutorial, you can either pull down the code from the GitHub repo (by visiting this page), or you can use the inline code snippets within the article.

Pre-requisites for this article:

• Knowledge of React

• Knowledge of writing TypeScript and HTML / JSX.

• Familiarity with Tailwind CSS (not required in order to follow this tutorial)

Table of Contents

• The Initial Basic Form

• Error Handling With React-Hook-Form

• Hooking Up The useForm Methods To Our Form

• Showing Error Messages

• Adding aria-required

• Adding fieldset and legend

• Adding Labels and Using htmlFor

• Do Not Rely on Placeholders Only!

• Give Additional Information With aria-describedBy

• Avoid Tooltips for Critical Information

• Tell Me Something Important

• Focus States and Colouring

• Make Buttons Descriptive

• Final Thoughts

The Initial Basic Form

So if we take a look at the form in its current state, you may think it looks fine. But it’s actually not very accessible, nor does it offer a great user experience.

import { TvIcon } from "@heroicons/react/24/outline";

type FormData = {
    fullName: string;
    email: string;
    password: string;
    confirmPassword: string;
    agreeToTerms: boolean;
};

export const RegistrationForm = () => {
    const onSubmit = () => {
        alert(`Form submitted`);
    };

    return (
        <div className="flex justify-center items-center w-screen h-screen bg-gray-900">
            <div className="w-full max-w-md p-8 bg-black bg-opacity-75 rounded-lg">
                <div className="flex flex-row justify-center items-center gap-x-4">
                    <TvIcon className="h-12 w-12 text-white" />
                    <h1 className="text-7xl font-bold text-center text-red-600 mb-4">Getflix</h1>
                </div>
                <h2 className="text-3xl font-bold text-white mb-6 text-center">
                    Sign Up
                </h2>

                <form onSubmit={onSubmit} className="space-y-6">

                    {/* Full Name */}
                    <div>
                        <input
                            type="text"
                            placeholder="Full Name"
                            className="w-full p-3 rounded bg-gray-700 text-white placeholder-gray-400 "
                        />

                    </div>

                    {/* Email */}
                    <div>
                        <input
                            type="email"
                            placeholder="Email Address"
                            className="w-full p-3 rounded bg-gray-700 text-white placeholder-gray-400 "
                        />

                    </div>

                    {/* Password */}
                    <div>
                        <input
                            type="password"
                            placeholder="Password"
                            className="w-full p-3 rounded bg-gray-700 text-white placeholder-gray-400"
                        />

                    </div>

                    {/* Confirm Password */}
                    <div>
                        <input
                            type="password"
                            placeholder="Confirm Password"
                            className="w-full p-3 rounded bg-gray-700 text-white placeholder-gray-400 "
                        />

                    </div>

                    {/* Agree to Terms */}
                    <div className="flex items-center text-gray-400 text-sm">
                        <input

                            type="checkbox"
                            id="agreeToTerms"
                            className="mr-2"
                        />
                        <label htmlFor="agreeToTerms" className="select-none">
                            I agree to the Terms and Conditions
                        </label>
                    </div>


                    {/* Submit */}
                    <button
                        type="submit"
                        className="w-full py-3 bg-red-600 hover:bg-red-700 text-white rounded font-semibold transition"
                    >
                        Sign Up
                    </button>


                </form>
            </div>
        </div>
    );
};

What’s Wrong With The Form?

• Lack of action feedback – no user feedback means that users can become confused as to whether an action has happened or not. No error messages or feedback offers the user no insight into what they need to do to correct the form.

• No labels for form inputs – No labels for form inputs prevent screen readers from understanding their purpose. Some screen readers may miss placeholders, and once a user types within the input, the placeholder is replaced, losing context and making it hard to return to erroneous inputs.

• Lack of accessibility markup to make the form optimised for screen readers and accessibility tools.

So how do we make this better? Let’s jump right in.

Error Handling With React-Hook-Form

Error handling on forms is a critical aspect of any form submission flow. Without it, the process becomes both chaotic and frustrating for the user. We can alleviate this frustration by adding some useful error messages which explain the issues.

A popular library for working with forms in React is the react-hook-form library. It’s used by over 1.4 million people according to their GitHub statistics.

Go ahead and install it if you don’t have it already:

npm install react-hook-form

We will then implement the basic required functions from the react-hook-form package, using the useForm() hook like so:

// define our type structure to use within the form
type FormData = {
    fullName: string;
    email: string;
    password: string;
    confirmPassword: string;
    agreeToTerms: boolean;
};

// basic usage of `useForm()`
const {
    register,
    handleSubmit,
    watch,
    formState: { errors },
  } = useForm<Inputs>()

Quick Explanation:

• register: One of the key concepts in React Hook Form is to “register” your component / HTML element. This means you can access value of the element for both form validation and when submitting the form.

• handleSubmit: This is the key function needed to submit the form, run validation, and any other configured checks. It can take up to two arguments:

  1. handleSubmit(onSuccess) – called when the submission of the form is valid and can submit ok.

  2. handleSubmit(onSuccess, onFail) – here you can pass the handleSubmit() method two functions: the first will be run when React Hook Form deems the form to be valid, and allows you to continue. The second will be called when the form sees an error. This could be from validation, or another stipulation.

• watch: Watch is a function that monitors a specified element for changes and returns its value. For instance, if you’re watching an input element, you can output the user’s typing in real-time or have another element validate it against a predefined value. A good example is a confirm password matching the previous password field.

• formState: this is an object which holds information about your form. The formState object keeps track of the state of the form, like:

  1. isDirty – true if the user has changed any input.

  2. isValid – true if the form passes all validations.

  3. errors – an object holding any validation errors per field.

  4. isSubmitting – true while the form is being submitted (useful for showing loading spinners)

  5. isSubmitted – true after the form has been submitted.

  6. touchedFields – which fields the user has interacted with.

  7. dirtyFields – which fields the user has modified.

We can use any of these properties by including them in our form state object. We are destructing the errors property so we can use the errors later in our form to either show error messages, or validate that there no errors on the page.

Hooking Up the useForm Methods to Our Form

Now that we know more about the useForm() method and react-hook-form, we need to integrate this with our existing <form/> element. Doing so will allow us to use all the react-hook-form features we’ve discussed so far in our form.

import { TvIcon } from "@heroicons/react/24/outline";
import { useState } from "react";
import { useForm } from "react-hook-form";

type FormData = {
    fullName: string;
    email: string;
    password: string;
    confirmPassword: string;
    agreeToTerms: boolean;
};

export const RegistrationForm = () => {
    const {
        register,
        handleSubmit,
        formState: { errors },
        watch,
    } = useForm<FormData>();

    const onSubmit = () => {
        alert(`Form submitted`);
    };

    return (
        <div className="flex justify-center items-center w-screen h-screen bg-gray-900">
            <div className="w-full max-w-md p-8 bg-black bg-opacity-75 rounded-lg">
                <div className="flex flex-row justify-center items-center gap-x-4">
                    <TvIcon className="h-12 w-12 text-red-500" />
                    <h1 className="text-7xl font-bold text-center text-white mb-4">Getflix</h1>
                </div>
                <h2 className="text-3xl font-bold text-white mb-6 text-center">
                    Sign Up
                </h2>


                <form onSubmit={handleSubmit(onSubmit)} className="space-y-6">

                    {/* Full Name */}
                    <div>
                        <input
                            {...register("fullName", {
                                required: "Full Name is required"
                            })}
                            aria-required
                            type="text"
                            placeholder="Full name"
                            className="w-full p-3 rounded bg-gray-700 text-white placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-red-500"
                        />
                        {errors.fullName && (
                            <p className="text-red-500 text-sm mt-1">{errors.fullName.message}</p>
                        )}
                    </div>

                    {/* Email */}
                    <div>
                        <input
                            {...register("email", {
                                required: "Email is required",
                                pattern: {
                                    value: /^\S+@\S+$/i,
                                    message: "Invalid email address",
                                },
                            })}
                            type="email"
                            placeholder="Email Address"
                            className="w-full p-3 rounded bg-gray-700 text-white placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-red-500"
                        />
                        {errors.email && (
                            <p className="text-red-500 text-sm mt-1">{errors.email.message}</p>
                        )}

                    </div>

                    {/* Password */}
                    <div>
                        <input
                            {...register("password", {
                                required: "Please enter your password",
                            })}
                            type="password"
                            placeholder="Password"
                            className="w-full p-3 rounded bg-gray-700 text-white placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-red-500"
                        />
                        {errors.password && (
                            <p className="text-red-500 text-sm mt-1">{errors.password.message}</p>
                        )}
                    </div>

                    {/* Confirm Password */}
                    <div>
                        <input
                            {...register("confirmPassword", {
                                required: "Please enter your password",
                                validate: (value) =>
                                    value === watch("password") || "Passwords do not match",
                            })}
                            type="password"
                            placeholder="Confirm Password"
                            className="w-full p-3 rounded bg-gray-700 text-white placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-red-500"
                        />
                        {errors.confirmPassword && (
                            <p className="text-red-500 text-sm mt-1">{errors.confirmPassword.message}</p>
                        )}
                    </div>

                    {/* Agree to Terms */}
                    <div className="flex items-center text-gray-400 text-sm">
                        <input
                            {...register("agreeToTerms", {
                                required: "You must agree to the terms and conditions"
                            })}
                            type="checkbox"
                            id="agreeToTerms"
                            className="mr-2"
                        />
                        <label className="select-none">
                            I agree to the Terms and Conditions
                        </label>

                    </div>
                    {errors.agreeToTerms && (
                        <p className="text-red-500 text-sm mt-1">{errors.agreeToTerms.message}</p>
                    )}


                    {/* Submit */}
                    <button
                        type="submit"
                        className="w-full py-3 bg-red-600 hover:bg-red-700 text-white rounded font-semibold transition"
                    >
                        Sign Up
                    </button>

                    {/* Already have account */}
                    <p className="text-center text-gray-400 text-sm mt-4">
                        Already have an account?{" "}
                        <a href="#" className="text-red-500 hover:underline">
                            Sign In
                        </a>
                    </p>
                </form>
            </div>
        </div >
    );
};

So in the updated form code, we’ve made a few adjustments:

Registered Each Our Elements

For each of our elements we’ve added the register object, and configuring some overrides.

We added the required property to all input fields, which checks if the element has a value. If not, it records the provided name and marks the error as erroneous, updating the errors object with our name and the provided required message.

 {...register("fullName", {
    required: "Full Name is required"
  })}

We’ve added a pattern property on the email’s register object. This allows us to specify a criteria for the value of the input – perfect for passwords, email fields, and other inputs which may have value restrictions, or requirements.

// valid email pattern
pattern: {
    value: /^\S+@\S+$/i,
    message: "Invalid email address",
},

We have also added the validate property to the confirm password element. This is a given function that will run as the user types.

validate: (value) => value === watch("password") || "Passwords do not match"

The validate function inside register is run automatically based on the field's validationMode setting.

By default (if you do not specify the validationMode), React Hook Form runs validation on onChange and onBlur events. This means that:

• When the user types into the input → it triggers validate.

• When the user leaves (blurs) the input → it triggers validate again.

If you wanted to update the custom validation mode, you can override this using the mode setting within useForm() like so:

 const { register, handleSubmit, formState, trigger } = useForm({
    mode: "onSubmit",
  });

If you then want to go an extra step and update the mode per element, overriding the mode setting you just globally set for your form, you can use the trigger() method from useForm like so:

<input
  {...register("email", { required: "Email is required" })}
  onBlur={() => trigger("email")} // validate this field onBlur manually
/>

This allows you to have onSubmit validation set via mode, and then email is triggered via onBlur() too.

Just adding these simple settings within the react-hook-form library already gives us a much better user experience than before – but it isn’t everything. Let’s explore more settings, HTML, and attributes we can add to increase accessibility and user experience.

Showing Error Messages

Form errors can be stored within the formState object we mentioned earlier, but they’re no good there – we need to display them to our users. We can achieve this simply by accessing the destructed errors object, like below:

{errors.password && (
    <p className="text-red-500 text-sm mt-1">{errors.password.message}</p>
)}

The code uses conditional syntax to show the <p> tag only if the errors.password object has a value, indicating an error associated with the password field from useForm() checks. We can then display the error message from errors.password.message, combined with a commonly used erroneous colour like red, to highlight the form’s problems. This can then been applied to all other input fields as per the code above.

Adding aria-required

So we’ve informed the form that certain elements are required and these should be checked when submitting the form. But this alone doesn’t inform visually impaired users that the element is required.

To aid with screen-readers, we can add an aria attribute to our element which will be read by the screen-reader. This property is the aria-required property. This means that when the screen-reader reads out information about the element it will inform the user that this value is required for successful submission.

 <input
    {...register("fullName", {
        required: "Full Name is required"
    })}
    aria-required
    type="text"
    placeholder="Full name"
    className="w-full p-3 rounded bg-gray-700 text-white placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-red-500"
/>

Adding fieldset and legend

Fieldset elements group <form> controls together, while legend elements provide a description for the grouped controls.

Imagine you have one big form, but it spans two "sections" – for example, a "User Details" section for username, email, and passwords, and an "Address Details" section asking for your shipping and billing information.

In this tutorial, we’re using TailwindCSS, which provides a utility class called sr-only. You can apply sr-only to your legends so they are only visible to screen readers, and not actually visible on the page.

This way, the legend will be read aloud when users navigate into a section of the form, making it clear which part of the form they are interacting with.

Important Note: Legends must be placed inside fieldsets. You need to wrap your legends within a <fieldset> element for your HTML to be valid and accessible.

Here's an unrelated example (to keep it brief and simple):

  <fieldset>
    <legend>Payment Method</legend>    
    <label>
      <input type="radio" name="payment" value="card" />
      Credit Card
    </label>

    <label>
      <input type="radio" name="payment" value="paypal" />
      PayPal
    </label>
  </fieldset>

You can see that the payment option inputs have been grouped within a fieldset, and then described by the legend element, informing the user that these elements relate to “Payment Method”. You as the developer can then decide if you would like this shown to everyone, or if it’s only for visually impaired users.

For screen readers, they’d hear something like:

"Group: Payment Method. Credit Card radio button. PayPal radio button."

Do Not Rely on Placeholders Only!

Placeholders are a great addition to make it clear to the user what the input elements are used for, and show helpful information. But they aren’t that user friendly, especially in regards to screen-readers.

The main reasons for this are:

• Placeholders disappear when typing, meaning that if a user begins to type “Grant”, and then tabs away from the input when they go back, without a label it will simply read the value of the input, not what it relates to.

• Often developers utilise a grey-like colour for their placeholders, with a low opacity. This can mean it’s difficult for users to sometimes see the placeholder, especially those who are colour blind or visually impaired.

So what can we do instead ? Well this leads me onto our next point – we can use a common HTML element, the <label/>.

Adding Labels and Using htmlFor

Another accessibility feature we can add to boost our accessibility and user experience for all, is the htmlFor attribute combined with the <label/> element.

Labels are highly important for both sighted and visually impaired users. It offers clarity as to what the input is associated with, as well as a navigational tool for those using screen-readers.

The htmlFor attribute is used to link <label/> elements with their input.

Note: htmlFor attributes can only be used on labels and are not valid on any other element.

<label htmlFor="fullname" className="text-white">Full Name</label>
<input
    {...register("fullName", {
        required: "Full Name is required"
    })}
    id="fullname"
    aria-required
    type="text"
    placeholder="Full name"
    className="w-full p-3 rounded bg-gray-700 text-white placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-red-500"
/>

Why this is important for accessibility:

1. Screen readers:

When a screen reader lands on the <input>, it automatically reads the associated label ("Full Name"). Even if the label is not visually right next to the input, the screen reader still knows which text describes the input, giving you some freedom when designing your forms.

2. Click behaviour:

When you click the <label>, it automatically focuses the <input> when using htmlFor.

Users don’t have to click exactly on the tiny input field – and this can certainly be useful when dealing with checkboxes or radio buttons, for example.

In short, big click targets = better usability and faster form filling.

This is also very helpful for mobile users where precision tapping is hard, especially on smaller screens.

Give Additional Information With aria-describedBy

Now that we’ve added clear labels to our form fields, we can take accessibility a step further by providing additional guidance for users when errors occur. By using aria-describedby and aria-invalid, we can link helpful error messages to the input fields and ensure screen readers communicate validation issues clearly. Let’s look at how to implement this:

<div>
  <label htmlFor="email" className="text-white">Email</label>
  <input
    {...register("email", {
          required: "You must enter an email address",
      pattern: {
        value: /^\S+@\S+$/i,
        message: "Invalid email address",
      },
    })}
    id="email"
    type="email"
    aria-invalid={errors.email ? "true" : "false"}
    aria-describedby={errors.email ? "email-error" : undefined}
    placeholder="Enter your email address"
    className="w-full p-3 rounded bg-gray-700 text-white placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-red-500"
  />
  {errors.email && (
    <p id="email-error" className="text-red-500 text-sm mt-1">
      {errors.email.message}
    </p>
  )}
</div>

Notice the two new attributes we’ve added:

• aria-describedBy – this attribute links our error message with our input. Screen readers will therefore read out the error message whilst reading out other information when the input is focused.

• aria-invalid – this attribute again aids with screen readers, informing the user that the input’s value is invalid and they need to correct it. This combined with the describedBy attribute gives visually impaired users all the information they need in order to correct their mistake.

Avoid Tooltips for Critical Information

When developing your form, try to avoid tooltips (those little elements that show when you hover over another element for a period of time like below).

The problems with using tooltips are:

1. They often require mouse hover, which doesn't work on touch devices (for example mobile phones, or tablets).

2. They aren’t announced reliably by screen readers if proper aria labels aren’t added.

3. They disappear too quickly

Instead, we can use inline helper text or descriptions combined with aria-describedby like below:

<p id="passwordHint" className="text-xs text-gray-500">
  Must be at least 8 characters and include a number.
</p>

We can then reference this within our input using the aria-describedBy attribute. But wait, we already have a describedBy pointing at the error message – well, that’s ok! We can link multiple elements, like the brief example below:

// now references both passwordHint and the password error (we seperate the ids with a space)
<input 
  id="password"
  aria-describedby="passwordHint passwordError"
/>

<div id="passwordHint">
  Must be at least 8 characters long.
</div>

<div id="passwordError">
  Passwords do not match!
</div>

Tell Me Something Important

aria-live is an aria attribute you can add to an element to tell screen readers:

"Hey, if the content inside me changes, announce it automatically."

It makes dynamic content updates audible without needing the user to re-focus anything.

A basic example could look something like below, where a message which is updated upon submission is updated, it could contain something like:

“Loading” → “Hurray, registration complete”

or

““Pending” → “Registration failed due to many errors”

<p aria-live="polite">
  {formSubmissionResultMessage}
</p>

When formSubmissionResultMessage changes, screen readers will automatically announce the updated message.

The timing of when it is read out depends on the value of the aria-live attribute – with polite, the announcement waits for a natural pause. With assertive, it interrupts immediately.

Real-World Examples

Polite update: good for passive notifications

<p aria-live="polite" className="mt-2 text-green-500">
  Form saved successfully.
</p>

The screen reader waits for a good moment to say it.

Assertive update: good for urgent errors

<p aria-live="assertive" className="mt-2 text-red-500">
  Passwords do not match!
</p>

The screen reader immediately interrupts and announces it.

Good things to know:

• The element needs to already exist in the DOM when the update happens. So it’s smart to always render the <p aria-live> – just update its content.

• Don’t overuse assertive, or you’ll annoy users and make apps feel super noisy and overwhelming.

Focus States and Colouring

You may have noticed on the input elements that I have added some custom colouring with TailwindCSS classes focus:. But what is this doing?

Well, this allows us to control the focus colour of the inputs. Without this, the browser will apply its own default styling which may not be as accessible to our users, especially those with colour-blindness.

For example, within our form, without the styling the input with focus looks like this:

Here you can see it has applied a subtle white and blue outline – but its not that clear it’s being focused. You can argue it is different enough to other input elements, but for some users this may not be enough.

To combat this and improve usability, we can override this with our own custom colouring. When using TailwindCSS, we can apply the following class names:

focus:outline-none focus:ring-2 focus:ring-red-500

What Does This Do?

This now applies a much thicker red line (encompassing brand colours) as well as making it clearer against the darker background

If you’re not using TailwindCSS, you can accomplish the same with plain CSS like so:

input:focus {
  outline: none; /* no default browser outline */
  box-shadow: 0 0 0 2px #ef4444; /* 2px red ring around input */
}

Make Buttons Descriptive

A super simple way to level up your form’s user experience is to make sure your buttons use clear, descriptive text.

Let’s take a look at a few examples of buttons that don’t quite achieve this:

The above buttons are examples of poor input buttons because:

• “Click Here” doesn’t give any context. Screen reader users, and even sighted users, have no idea what "click here" does without reading nearby text.

• Icon Only: Sighted users might guess what the icon means, but screen readers see nothing unless you add aria-label. The point is, it is ambiguous and unclear as to what the button does. You may see websites that just use an icon, not surrounded by a button, which can be even more confusing.

• “Submit”: If you have several "Submit" buttons (for example, one for payment, one for contact form), users don't know which "submit" is doing what.

Improvements

Instead, we can improve those buttons to be more accessible and user-friendly by doing the following:

• Use descriptive button text – for example: "Pay Now", "Sign Up", or "Save Changes".

• Use both an icon and text – combining an icon with text can be the perfect blend for both accessibility and design.

• Use aria-label – if you really must use an icon-only button (like a basket or home icon in a navigation bar), make sure to add an aria-label attribute to clearly describe the button’s purpose, like so:

<button 
    type="submit"
    className="w-full py-3 px-6 rounded-lg bg-red-600 hover:bg-red-700 focus:outline-none focus:ring-2 focus:ring-red-500 text-white text-lg font-semibold transition"
> Pay Now <button>

<button
    type="submit"
    className="w-full py-3 px-6 rounded-lg bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 text-white text-lg font-semibold flex justify-center items-center gap-2 transition">
        <HomeIcon className="h-6 w-6" />
        Home
</button>

<button
    type="submit"
    aria-label="Go to homepage"
    className="w-full py-3 px-6 rounded-lg bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 text-white text-lg font-semibold flex justify-center items-center transition">
        <HomeIcon className="h-6 w-6" />
</button>

That code would generate the following:

Final Thoughts

In this tutorial, we’ve covered various ways to make your forms more accessible and user-friendly. From simple things like making button text clearer and using more user-friendly colours, to more complex HTML attributes like aria-describedBy and aria-live, you should be covered.

I hope you found this tutorial helpful, and now you’re ready to take your development skills to the next level. Making these simple changes can have a big impact on your users’ experience, and they’ll definitely stick around longer and be less frustrated.

As always, if you’d like to share feedback on the article, discuss it further, or just hear about future articles or content, you can drop me a follow on X (Twitter) via my handle @grantdotdev.

In this article, I’ll teach you how to use the TestContainers library to make running integration tests much easier and more manageable.

Table of Contents

• Prerequisites

• What Is TestContainers?

• How Does It All Work?

• How to Set Up Your First Test

• Key Behaviors of IAsyncLifetime in a Test Class

• How to Improve Performance

• Explanation of Differences

• How to Share Your Container Across Multiple Test Classes

• Summary of Approaches:

• How to Create Multiple Containers

• How to Make Your Setup Easier With Custom Images

• Final Thoughts

Prerequisites

• Understanding of Docker

• Understanding of xUnit and testing

• Installation of the following packages:

  • TestContainers

  • TestContainers.MsSql

  • xUnit

  • >= .Net 8

  • FluentAssertions

  • Microsoft.Data.SqlClient

What Is TestContainers?

TestContainers is an open source library that provides you with easily disposable container instances for things like database hosting, message brokers, browsers and more – basically anything that can run in a Docker container.

It removes the necessity to maintain hosted environments for testing in the cloud or on local machines. As long as the user’s machine and CI/CD host supports Docker, the testContainer tests can easily be run.

How Does It All Work?

You define the image you’re wanting to utilise, and specify a configuration.

The TestContainer library spins up a Docker Container with the configured image.

Provides Connection Details

After starting the container, TestContainers exposes connection strings (for example, a database connection URL), so your tests can use the real service, rather than having to configure this yourself.

Cleans Up Automatically

When the test finishes, TestContainers removes the container automatically, ensuring no leftover resources. This is one of the best things about using TestContainers: all the creation, tear down, and container setup is handled within the library itself, making it perfect for use within delivery pipelines.

How to Set Up Your First Test

For the purpose of this tutorial, we’re going to keep things simple, and only use a MS Sql Server image.

The first thing we’re going to do is configure our Microsoft SQL Server Docker container via the TestContainer fluid API.

Create your test class like below:

public class IntegrationTests: IAsyncLifetime 
{
    private MsSqlContainer _container;
    private FakeLogger _logger

    public async Task InitializeAsync()
    {
           _container = new MsSqlBuilder()
                .WithImage("mcr.microsoft.com/mssql/server:2022-latest")
                .WithPassword("P@ssw0rd123")
                .WithPortBinding(1443)
                .WithWaitStrategy(Wait.ForUnixContainer().UntilPortIsAvailable(1433))
                .Build();

            _logger = new FakeLogger();
    }

    public async Task DisposeAsync() => await _container.DisposeAsync();
}

Here we’re using xUnit’s IAsyncLifetime interface. It’s an interface in xUnit that provides a way to handle async setup and teardown for test classes. It's useful when you need to initialise and clean up resources asynchronously. We’re using the InitializeAsync() to setup and define our Microsoft SQL Database container as well as starting the container, then using the DisposeAsync() method to stop and dispose of our container.

Explanation of Builder Methods

• WithImage(): this allows us to specify the image we want Docker to pull down and run. We’ve opted for the latest version of SQL Server 2022.

• WithPassword(): This allows us to specify the password for the database (when creating most databases, a password is normally required).

• WithPortBinding(): This allows us to specify both the hosting port number on your machine, as well as the container port number

• WithWaitStrategy(): Here we can specify a wait strategy, which informs our container to wait for a condition before the container is ready to use. This is important because some services (like databases or APIs) take time to fully start up.

• Build()" This is the command that builds the test container based on the configuration. This does not run or start the container – you can do this using the container.StartAsync() method as mentioned previously.

Why Is WithWaitStrategy() Needed?

By default, TestContainers assumes the container is ready as soon as it starts running. But some services might:

• Take time to initialize.

• Require a specific log message before they are ready.

• Need a port to be accessible before you can connect.

Using WithWaitStrategy(), you can customise how TestContainers waits before considering the container "ready."

Adding the Test

public class IntegrationTests: IAsyncLifetime 
{
    private MsSqlContainer _container;
    private FakeLoger _logger;

    public async Task InitializeAsync()
    {
           _container = new MsSqlBuilder()
                .WithImage("mcr.microsoft.com/mssql/server:2022-latest")
                .WithPassword("P@ssw0rd123")
                .WithPortBinding(1443)
                .WithWaitStrategy(Wait.ForUnixContainer().UntilPortIsAvailable(1433))
                .Build();

            await _container.StartAsync();
            _logger = new FakeLogger();
    }

    public async Task DisposeAsync() => await _container.DisposeAsync();

    [Fact]
    public async Task Test_Database_Connection()
    {
        var connectionString = _container.GetConnectionString();
        using var conn = new SqlConnection(connectionString);
        await conn.OpenAsync();

        Assert.True(conn.State == System.Data.ConnectionState.Open);
    }
}

The above test, although it’s simple, illustrates how easy it is to spin up a container and create a simple test. The above test will work, but it can lead to low performing tests and high usage of machine resource when not used correctly. Let me explain:

Using IAsyncLifetime is necessary, as we’re calling async setup methods (StartAsync), for example. But the InitializeAsync() / DisposeAsync() methods when situated in a test class are run before and after every test (Fact in xUnit).

This means that every time a test begins, it is:

• creating a brand new Docker container,

• pulling the MS Sql image,

• creating the DB,

• running the tests, and

• tearing down the container.

You can test this by copying and pasting the above Test_Database_Connection() test multiple times, adding a number to each duplicate test (to keep the compiler happy), and opening Docker Desktop. Running all the tests, you will see a new container (with a different name) being created for each test run.

Now, this can be acceptable if you have a limited number of tests in your test class. But it can have negative outcomes on test classes with a larger number of tests, meaning test maintenance and planning is key. It’s useful, though, when you want to make sure that the database is in a completely clean state before each test, ensuring no data contamination from other tests running.

Key Behaviors of IAsyncLifetime in a Test Class

When your test class implements IAsyncLifetime, xUnit's default behaviour is:

1. Creates a new instance of the test class for each test method.
2. Calls InitializeAsync() before each test.
3. Calls DisposeAsync() after each test.

What Does This Mean for TestContainers?

• In our case, since InitializeAsync() sets up a new container, a new container is created for each test.

• DisposeAsync() stops the container after each test finishes.

• Ensures a completely fresh database state for every test, avoiding data contamination.

• Is slow and resource-intensive, especially if you have many test methods.

A more visual look on a test class could look like this:

🟢 InitializeAsync() -> New Container Created (For Test_1)

🧪 Running Test_1

🛑 DisposeAsync() -> Container Stopped (After Test_1)

🟢 InitializeAsync() -> New Container Created (For Test_2)

🧪 Running Test_2

🛑 DisposeAsync() -> Container Stopped (After Test_2)

When Is This Useful?

• You need a completely fresh database state or container for each test.

• Avoids test data contamination.

• Each test starts from a clean slate.

When Is This a Problem?

• It results in slow execution – a new container is started for every test.

• It’s resource-heavy – multiple containers run sequentially.

• And it’s not scalable – hundreds of tests will take a long time to complete.

How to Improve Performance

Ok, so we’ve seen how to create containers once per test, and explored scenarios where this would be useful, but what if performance and cost are a concern?

Here we can combine IClassFixture and IAsyncLiftetime to achieve a Once per test class approach, where we create one container and one database, and its lifecycle is the full length of the test class (that is, all tests run against the same DB).

How to Write This

We can utilise a TestFixture class which inherits the IAsyncLifetime interface, exposing the InitializeAsync() and DisposeAsync() methods as before.

using DotNet.Testcontainers.Builders;
using Microsoft.Extensions.Logging.Testing;
using Testcontainers.MsSql;

namespace IntegrationTests;

public class TestClassFixture : IAsyncLifetime
{
    public MsSqlContainer Container { get; set; }
    private FakeLogger _logger;

    public async Task InitializeAsync()
    {
        Container = new MsSqlBuilder()
            .WithImage("mcr.microsoft.com/mssql/server:2022-latest")
            .WithPassword("P@ssw0rd123")
            .WithPortBinding(1443)
            .WithWaitStrategy(Wait.ForUnixContainer().UntilPortIsAvailable(1433))
            .Build();

        _logger = new FakeLogger();
        await Container.StartAsync();
    }

    public async Task DisposeAsync()
    {
        await Container.DisposeAsync();
    }
}

Using xUnit’s IClassFixture interface, we can pass our TestClassFixture and have our test class inherit from this. A test fixture is only run once per test class, making it perfect for our scenario.

public class IntegrationFixtureTests : IClassFixture<TestClassFixture>
{
    private readonly string _connectionString;

    public IntegrationFixtureTests(TestClassFixture testClassFixture)
    {
        _connectionString = testClassFixture.Container.GetConnectionString();

        // other test class specific setup goes here
    }

    [Fact]
    public async Task Test_Database_Connection()
    {
        await using var conn = new SqlConnection(_connectionString);
        await conn.OpenAsync();

        Assert.True(conn.State == System.Data.ConnectionState.Open);
    }
}

We now have a much cleaner test class, and all our container logic is handled by the IClassFixture instead. Should you need to add test class specific code, for example seeding the database prior to running, or the mocking of any resources, you can place this code within the constructor.

Explanation of Differences

We set our Container property as public, rather than private so that our test class can access the container. The test fixture is injected by xUnit's own internal dependency injection mechanics when you use IClassFixture<T>.

xUnit automatically creates an instance of the fixture class and passes it into the test class constructor.

The container is started within the InitializeAsync() method on the TestFixture now, rather than the test class, meaning it only gets started once and is readily available for all the tests. This improves performance and test speeds (no more waiting for each container to spin up before each test).

The test flow would look something more like this now:

🟢 InitializeAsync() → Container Created → Container Started

🧪 Running Test_1

🧪 Running Test_2

🛑 DisposeAsync() -> Container Stopped → Container Disposed of

Advantages and Disadvantages

✅ Faster Execution

Significantly reduces setup/teardown overhead, especially when using slow-starting services like databases.

✅ Lower Resource Usage

Running a container once per test class consumes far fewer system resources compared to one container per test. This is especially beneficial when running integration tests in CI/CD pipelines where resource usage needs to be optimised to keep costs low.

✅ More Realistic Testing

In real-world scenarios, applications don’t restart their databases between API calls, so why should your integration tests?

❌ Data Contamination

Effective test data management is essential for maintaining reliable tests. If test data is not properly isolated, it can lead to unintended interference between tests.

For example, a test that creates a new record might introduce unexpected data, causing a retrieval test to fail if it runs afterward. This type of data contamination is a common issue when all tests in a test class share the same database setup. But,with careful test design—such as proper data isolation, cleanup strategies, or using transactional rollbacks—these issues can be mitigated or entirely avoided.

❌ More Care Needs To Be Taken Around Indempotency

“Indempotency” refers to the ability to run any test on its own in any order. If the test class is accessing data from the same areas, the assertions may fail when ran in certain orders than others. For example:

• Test_1 inserts a record.

• Test_2 assumes the table is empty and asserts QueryByName() should return 1 record

• Test_2 fails because Test_1 has already inserted its own record

How to Share Your Container Across Multiple Test Classes

So we’ve covered a container per test and a container per test class. But what about sharing a container for multiple test classes? Well, it’s as simple as using the ICollectionFixture interface instead of IClassFixture, and it can be used like so:

[CollectionDefinition("Database collection")]
public class DatabaseCollection : ICollectionFixture<TestClassFixture>
{
    // This class has no code, 
    // it’s just used to apply the [Collection] attribute to test classes.
}

The ICollectionFixture<T> mechanism in xUnit automatically ties the fixture instance to all test classes marked with the [Collection("Collection Name")] attribute, for example:

using IntegrationTests;
using Microsoft.Data.SqlClient;

[Collection("Database collection")]
public class IntegrationFixtureTests
{
    private readonly string _connectionString;

    public IntegrationFixtureTests(TestClassFixture testClassFixture)
    {
        _connectionString = testClassFixture.Container.GetConnectionString();
    }

    [Fact]
    public async Task Test_Database_Connection()
    {
        await using var conn = new SqlConnection(_connectionString);
        await conn.OpenAsync();

        Assert.True(conn.State == System.Data.ConnectionState.Open);
    }
}

[Collection("Database collection")]
public class AnotherIntegrationTest
{
    private readonly string _connectionString;

    public AnotherIntegrationTest(TestClassFixture testClassFixture)
    {
        _connectionString = testClassFixture.Container.GetConnectionString();
    }

    [Fact]
    public async Task Another_Database_Test()
    {
        await using var conn = new SqlConnection(_connectionString);
        await conn.OpenAsync();

        Assert.True(conn.State == System.Data.ConnectionState.Open);
    }
}

Now you can group your integration tests, whether it be all read tests or all write tests – making your tests much more maintainable.

Summary of Approaches:

How to Create Multiple Containers

Yes, you can create multiple containers which can host different images, making it perfect for when you have multiple systems you need to integrate with – for example Microsoft SQL Server and a Redis instance.

You can do this by calling the constructor of the relevant TestContainer package like below:

public class TestContainersFixture : IAsyncLifetime
{
    public MsSqlContainer SqlContainer { get; private set; }
    public RedisContainer RedisContainer { get; private set; }

    public async Task InitializeAsync()
    {
        // SQL Server Container
        SqlContainer = new MsSqlBuilder()
            .WithImage("mcr.microsoft.com/mssql/server:2022-latest")
            .WithPassword("P@ssw0rd123")
            .WithPortBinding(1433)
            .WithWaitStrategy(Wait.ForUnixContainer().UntilPortIsAvailable(1433))
            .Build();

        // Redis Container
        RedisContainer = new RedisContainerBuilder()
            .WithImage("redis:latest")
            .WithPortBinding(6379)
            .WithWaitStrategy(Wait.ForUnixContainer().UntilPortIsAvailable(6379))
            .Build();

        await Task.WhenAll(SqlContainer.StartAsync(), RedisContainer.StartAsync());
    }

    public async Task DisposeAsync()
    {
        await Task.WhenAll(SqlContainer.DisposeAsync(), RedisContainer.DisposeAsync());
    }
}

And just like that, we have a SQL Server and a Redis instance ready to integrate test against.

How to Make Your Setup Easier With Custom Images

To make testing easier, and leverage the power of Docker and TestContainers, here’s a great tip. TestContainers fully supports using custom images, including pre-configured ones with seeded databases. Instead of defining everything in the test setup, you can build and use a custom Docker image that already contains the required schema and test data.

When creating your own custom package to use, you can:

1. Upload your custom image to DockerHub and reference from there:

 SqlContainer = new MsSqlBuilder()
            .WithImage("your-dockerhub-username/custom-sql-image") 
            .WithPassword("P@ssw0rd123")
            .WithPortBinding(1433)
            .WithWaitStrategy(Wait.ForUnixContainer().UntilPortIsAvailable(1433))
            .Build();

2. Build your Docker image locally - f you're using a local image in TestContainers, you can simply reference the image name (e.g., my-custom-sql-image) in your code. TestContainers will first check your local Docker Desktop for the image before attempting to pull it from a registry like Docker Hub.

SqlContainer = new MsSqlBuilder()
    .WithImage("custom-sql-image") // Reference your local image
    .WithPassword("P@ssw0rd123")
    .WithPortBinding(1433)
    .WithWaitStrategy(Wait.ForUnixContainer().UntilPortIsAvailable(1433))
    .Build();

Having a pre-built image can speed up your tests especially in CI/CD pipelines, not to mention make them more readable by removing the seeding code.

To access your custom image in a CI/CD pipeline, you can upload it to DockerHub or GitHub Container Registry (GHCR) and access it from your tests. Build your DockerFile and push it to either system before accessing it in your tests.

Final Thoughts

Using TestContainers in .NET is a game-changer for integration testing. It’s a lightweight and automated way to manage external dependencies like databases, caching systems, and more. By using test containers in a test class, TestFixture, or ICollectionFixture, you can create cleaner, more reliable tests with isolated environments.

TestContainers can also save you money by eliminating the need for dedicated testing environments with long-lived dependencies. You can create and destroy them on the fly, or even integrate them into your CI/CD pipelines, especially in GitHub where Docker can be easily used.

As always I hope you’ve found this article helpful, and if you have any questions don’t hesitate to reach out on X / Twitter - @grantdotdev

While ILogger itself is an interface and can be mocked, many of its commonly used logging methods (like LogInformation(), LogError(), and so on) are what’s called static or extension methods. Since static and extension methods can't be mocked directly, you often need a custom abstraction layer (LoggingService) or a decorator to pass to various other methods or services.

There is another much easier way though. In this article, I will show you how to use the relatively new feature available from .Net 8 upwards called FakeLogger.

Table of Contents

1. Tutorial Setup

2. How to Test the Logging Functionality

3. How to Use FakeLogger

   • Installing FakeLogger and FluentAssertions

   • Using the FakeLogger Class

   • What Is Collector?

   • Useful Collector Properties

4. How to Assert That Structured Log Arguments Are Passed Correctly

5. How to Verify that a Message Has Been Called at Any Time

6. Final Thoughts

Tutorial Setup

Let’s imagine you’ve created an online shopping ordering and invoicing service. The logical code tests have been completed, but you now need to test the logging functionality.

For this tutorial we’ll be using the OrderService and InvoiceService classes defined below. I’ve provided comments to illustrate where normally your logic would go, but as this isn’t relevant for the purpose of this tutorial, comments will suffice.

namespace FakeLogger_Tutorial;

public class OrderService(ILogger logger, IInvoiceService invoiceService)
{
    public void ProcessOrder(Order order)
    {
        logger.LogInformation("Processing order...");

        // Order processing code goes here

        logger.LogInformation("Order processed successfully.");

        invoiceService.SendInvoice(order);
    }
}

public class InvoiceService(ILogger logger) : IInvoiceService
{
    public void SendInvoice(Order order)
    {
        // Dispatch order to shipping service
        logger.LogInformation("Order dispatched: {OrderId}", order.ID);

        // Generate invoice code

        SendEmail();
    }

    private void SendEmail()
    {
        // Send email to customer
        logger.LogInformation("Sending invoice to customer");

        // Perform email sending logic...

        logger.LogInformation("Email sent successfully.");
    }
}

public interface IInvoiceService
{
    void SendInvoice(Order order);
}

As well as a very basic Order and Product classes:

public class Order
{
    public Guid ID { get; set; }
    public required Guid CustomerId { get; set; }

    public List<Product> Products = [];

    public decimal TotalPrice => Products.Sum(x => x.Price);

    public DateTime OrderDate { get; set; }
}

public class Product
{
    public Guid ID { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

How to Test the Logging Functionality

Like most aspects of coding, there are multiple ways to achieve this. The recommended approach is to mock the logger and assert against the mocked logger object rather than a concrete instance. This allows for controlled, isolated, and verifiable tests without relying on external dependencies or real logging behaviour – meaning cleaner and more maintainable tests.

You can do this using your preferred mocking library, such as Moq, FakeItEasy, or NSubstitute. You can learn more about these libraries and how to mock successfully in another tutorial I wrote, which you can find here.

Your initial thoughts may be to write tests like the below example using Moq and XUnit but this won’t work, and I’ll explain why.

using FakeLogger_Tutorial;
using Microsoft.Extensions.Logging;
using Moq;

namespace UnitTests;

public class FailingTestCases
{
    [Fact]
    public void LogError_Should_Call_LogError()
    {
        // Arrange
        var mockLogger = new Mock<ILogger>();

        // pass the mockedLogger to our service
        var orderService = new OrderService(
            mockLogger.Object, 
            new Mock<IInvoiceService>().Object
        );

        var customerId = Guid.NewGuid();
        var order = new Order
        {
            ID = Guid.NewGuid(),
            CustomerId = customerId,
            Products = [new Product { ID = Guid.NewGuid(), Name = "Ping pong balls", Price = 1.00M }],
            OrderDate = default,
        };

        // Act
        orderService.ProcessOrder(order);      

        // Assert
        mockLogger.Verify(x => x.LogInformation("Processing order..."), Times.Once);
        mockLogger.Verify(x => x.LogInformation("Order processed successfully."), Times.Once);
    }
}

When you run this code, it will fail with the following error:

System.NotSupportedException: 
Unsupported expression: x => x.LogInformation("Processing order...", new[] {  })

Why Does This Happen?

Mocking libraries struggle with static methods like LogInformation because they belong to the type itself, not an instance. Some tools, like JustMock, can handle this using advanced techniques like IL rewriting or shims, but these add complexity.

A common workaround is wrapping ILogger in a logging service for easier testing, along with benefits like abstraction and maintainability. But for a simpler approach, we’ll focus on the new FakeLogger class.

You could test ILogger using the Verify method in Moq, using some overly complicated, verbose methods like below. The test code will work, but it's a bit too complex and hard to read, especially at a glance.

using FakeLogger_Tutorial;
using Microsoft.Extensions.Logging;
using Moq;

namespace UnitTests;

public class FailingTestCases
{
    [Fact]
    public void LogError_Should_Call_Logger_LogError()
    {
        // Arrange
        var mockLogger = new Mock<ILogger>();
        var mockInvoiceService = new Mock<IInvoiceService>();

        var orderService = new OrderService(
            mockLogger.Object, 
            mockInvoice.Object           
        );

        var customerId = Guid.NewGuid();
        var order = new Order
        {
            ID = Guid.NewGuid(),
            CustomerId = customerId,
            Products = [new Product { ID = Guid.NewGuid(), Name = "Ping pong balls", Price = 1.00M }],
            OrderDate = default,
        };

        // Act
        orderService.ProcessOrder(order);

        // Assert
        mockLogger.Verify(logger => logger.Log(
                It.Is<LogLevel>(logLevel => logLevel == LogLevel.Information),
                It.Is<EventId>(eventId => eventId.Id == 0),
                It.Is<It.IsAnyType>((@object, @type) =>
                    @object.ToString() == "Processing order..."),
                It.IsAny<Exception>(),
                It.IsAny<Func<It.IsAnyType, Exception, string>>()),
            Times.Once);
    }
}

How to Use FakeLogger

With .NET 8, we can use the FakeLogger class to make tests clearer for other developers. If you haven’t upgraded yet, I highly recommend it—.NET 8 offers Long-Term Support (LTS) and unlocks many other useful features.

Microsoft defines the class as:

This type is intended for use in unit tests. It captures all the log state to memory and lets you inspect it to validate that your code is logging what it should.

In simple terms means that the FakeLogger acts as an in-memory collection of all the Logs and their associated data, meaning we can access these during out Unit Tests. It exposes all the extension methods we would find on the ILogger implementation, making it the perfect way to test our logging functionality.

Installing FakeLogger and FluentAssertions

FluentAssertions is a great testing library which makes your code easier to test and easier to read. It focuses on using clearly named assertion functions, like Should(), Have() / Be().

You can install using the Nuget Package Manager within your preferred IDE, or via the terminal with the following command:

dotnet add package FluentAssertions

IMPORTANT: Do not exceed version 7.x.x of FluentAssertions, as v8 comes with a cost, whereas anything prior is free to use.

Once installed, you will need to install Microsoft.Extensions.Diagnostics.Testing as before, using either the Package Console Manager, Terminal, or your preferred method.

dotnet add package Microsoft.Extensions.Diagnostics.Testing

Using the FakeLogger Class

It is as simple as using any other class in C#. We can instantiate it like so:

using Microsoft.Extensions.Diagnostics.Testing;

var fakeLogger = new FakeLogger();

Now, rather than passing the mockLogger.Object to our OrderService as before, we shall instead pass our new fakeLoger object like so:

var loggingService = new OrderService(fakeLogger);

Below is an example of how we can use FakeLogger to check if an Information message was logged.

    public void OrderService_ProcessOrder_ShouldLogProgress()
    {
        // Arrange
        var fakeLogger = new FakeLogger();
        var mockInvoiceService = new Mock<IInvoiceService>();

        var orderService = new OrderService(
            fakeLogger,
            mockInvoiceService.Object
        );

        var customerId = Guid.NewGuid();
        var order = new Order
        {
            ID = Guid.NewGuid(),
            CustomerId = customerId,
            Products = [new Product { ID = Guid.NewGuid(), Name = "Ping pong balls", Price = 1.00M }],
            OrderDate = default,
        };

        // Act
        orderService.ProcessOrder(order);

        // Assert
        fakeLogger.Collector.Count.Should().Be(2);
        fakeLogger.Collector.LatestRecord.Level.Should().Be(LogLevel.Information);
        fakeLogger.Collector.LatestRecord.Message.Should().Be("Order processed successfully.");
    }

As you can see, it is much easier to read than the previous Moq implementation. The FakeLogger solution combined with FluentAssertions is much more concise and humanly readable to developers of all skillsets.

What Is Collector?

The Collector property in FakeLogger is an instance of FakeLogCollector, which collects and stores log information. It stores the messages in the same order they were called, making it easy to assert later.

Purpose of the Collector Property

• It stores all log messages captured by the FakeLogger.

• You can access, filter, and assert against logs in your tests.

• Useful when verifying structured logs or ensuring correct log levels.

Useful Collector Properties

LatestRecord

There is more than one way in which you can access and assert logged messages. In the example above, we use the LatestRecord property. The LatestRecord property returns the last FakeLogRecord recorded. This comes from the internal property Records, returning the last record in the List.

The FakeLogRecord object has the following properties:

Level
Id 
State
Exception
Message
Scopes
Category
LevelEnabled
Timestamp

We can therefore check any one of these properties in our assertions.

GetSnapshot()

GetSnapshot() returns all log records collected.

• This method is useful when you want to inspect all logged messages, not just the most recent one.

• It returns an immutable collection, ensuring that logs are not modified unexpectedly.

As GetSnapshot() returns an immutable collection of messages. We can access these like any other collection of data, whilst also being able to use LINQ to filter, sort, and query the logs. This can be very useful when we would like to assert against the first, last, or any other logged message.

The following test utilises a concrete instance of InvoiceService as we wish to test the actual flow of logs, through both services.

    [Fact]
    public void ProcessOrder_ShouldLogMultipleMessages()
    {
        // Arrange
        var fakeLog = new FakeLogger();
        var invoiceService = new InvoiceService(fakeLog);
        var orderService = new OrderService(fakeLog, invoiceService);
        var testOrder = new Order
        {
            ID = Guid.NewGuid(),
            CustomerId = Guid.NewGuid(),
            Products =
            [
                new Product { ID = Guid.NewGuid(), Name = "Product 1", Price = 99.99m },
                new Product { ID = Guid.NewGuid(), Name = "Product 2", Price = 199.99m }
            ],
        };

        // Act
        orderService.ProcessOrder(testOrder);

        // Assert
        fakeLog.Collector.GetSnapshot()[0].Message.Should().Be("Processing order...");
        fakeLog.Collector.GetSnapshot()[0].Level.Should().Be(LogLevel.Information);

        fakeLog.Collector.GetSnapshot()[1].Message.Should().Be("Order processed successfully.");
        fakeLog.Collector.GetSnapshot()[1].Level.Should().Be(LogLevel.Information);

        fakeLog.Collector.GetSnapshot()[2].Message.Should().Be($"Order dispatched: {testOrder.ID}");
        fakeLog.Collector.GetSnapshot()[2].Level.Should().Be(LogLevel.Information);

        fakeLog.Collector.GetSnapshot()[3].Message.Should().Be("Sending invoice to customer");
        fakeLog.Collector.GetSnapshot()[3].Level.Should().Be(LogLevel.Information);

        fakeLog.Collector.GetSnapshot()[4].Message.Should().Be("Email sent successfully.");
        fakeLog.Collector.GetSnapshot()[4].Level.Should().Be(LogLevel.Information);
    }

This test demonstrates how straightforward it is to assert that the logger captures messages in execution order with the correct LogLevel and message. It also highlights the readability of the test.

How to Assert That Structured Log Arguments Are Passed Correctly

Structured logging allows us to pass objects and variables as arguments to log messages, providing richer and more searchable logs. In ILogger, we can pass an object like this:

_logger.LogInformation("Order processed: {OrderId}", order.ID);

By default, logging providers (like the built-in .NET ILogger provider) replace placeholders immediately in the final log message.

With the built-in ILogger, the log message is fully formatted at runtime, for example:

_logger.LogInformation("Order number {OrderId} dispatched", 123);

Final log recorded is:

"Order number 123 dispatched"

This means that when retrieving logs in tests using the default log provider, we can only verify the final formatted string when using FakeLogger as it captures the fully rendered log message.

Important: This differs from structured logging providers such as Serilog, where message templates and structured properties are stored separately. In Serilog, the Message column stores the original raw template string, while structured properties / objects are stored in a separate JSON field.

This doesn’t mean you can’t use FakeLogger with Serilog—you absolutely can. But when asserting logs, you must adjust your assertions depending on whether you're verifying the fully formatted message or structured properties.

If we log an order dispatch:

logger.LogInformation("Order dispatched: {OrderId}", order.ID);

Unlike Serilog, FakeLogger does not store {OrderId} as a separate property. Instead, it captures the fully formatted message:

"Order dispatched: 550e8400-e29b-41d4-a716-446655440000"

Thus, when testing with FakeLogger, we must assert against the final formatted string.

Even though FakeLogger does not store the original message template, it does capture structured data separately. This allows you to assert both:

1. The final formatted message (since placeholders are replaced at runtime).

2. The structured data (objects or properties passed as arguments).

The test below asserts the final formatted message, as well as a StructuredState object (the recorded structured log information).

[Fact]
    public void InvoiceOrder_ShouldLog_StructuredLogInfo()
    {
        // Arrange
        var fakeLogger = new FakeLogger<InvoiceService>();
        var service = new InvoiceService(fakeLogger);
        var testOrder = new Order
        {
            ID = Guid.NewGuid(),
            CustomerId = Guid.NewGuid(),
            Products =
            [
                new Product { ID = Guid.NewGuid(), Name = "Product 1", Price = 99.99m },
                new Product { ID = Guid.NewGuid(), Name = "Product 2", Price = 199.99m }
            ],
        };

        // Act
        service.SendInvoice(testOrder);

        // Assert
        fakeLogger.Collector.GetSnapshot()[0].Message.Should().Be($"Order dispatched: {testOrder.ID}");
        var keyValuePairs = fakeLogger.Collector.GetSnapshot()[0].StructuredState;

        var orderIdProperty = keyValuePairs != null && keyValuePairs
            .Any(x => x.Key == "OrderId" && x.Value == testOrder.ID.ToString());

        orderIdProperty.Should().BeTrue();
    }

How to Verify That a Message Has Been Called at Any Time

What if you want to test that a message or a set of messages are called anywhere within the call stack? You can easily do this with the help of LINQ (if you’re not familiar with LINQ you can read it about it in my other article here).

We don’t wish to assert that messages are sent in the correct order, just that the messages are logged. We can do this as follows:

    [Fact]
    public void AllMessages_Should_BeSentInAnyOrder()
    {
        // Arrange
        var testOrder = new Order
        {
            ID = Guid.NewGuid(),
            CustomerId = Guid.NewGuid(),
            Products =
            [
                new Product { ID = Guid.NewGuid(), Name = "Product 1", Price = 99.99m },
                new Product { ID = Guid.NewGuid(), Name = "Product 2", Price = 199.99m }
            ],
        };

        var fakeLogger = new FakeLogger();
        var invoiceService = new InvoiceService(fakeLogger);
        var orderService = new OrderService(fakeLogger, invoiceService);
        var expectedMessages = new List<string>
        {
            $"Order Dispatched: {testOrder.ID}",         
            "Processing order...",
            "Invoice sent"
        };

        // Act
        orderService.ProcessOrder(testOrder);

        // Assert
        fakeLogger.Collector.GetSnapshot()
            .Select(x => x.Message)
            .Should().IntersectWith(expectedMessages);
    }

Here, we can utilise the power of LINQ and FluentAssertions to Select each message stored within the Collector property, and then assert that the array of messages can IntersectWith the expected messages.

The IntersectWith method asserts that the collection shares one or more items with the provided collection, a perfect fit for this kind of scenario where we don’t care about the order of logged messages – only that at some point they are logged.

Final Thoughts

Testing logging in .NET applications has traditionally been tricky because of extension methods in ILogger. But with .NET 8’s FakeLogger, we now have a cleaner, more readable, and efficient way to verify log messages in unit tests.

By using FakeLogger alongside FluentAssertions, we can simplify assertions, improve test readability, and ensure our logging behaviour is correctly implemented without the complexity of traditional mocking libraries.

Whether you're verifying message content, structured logs, or execution order, FakeLogger provides a robust solution that integrates seamlessly into modern .NET testing practices. If you haven't already, I highly recommend upgrading to .NET 8 to take full advantage of this powerful feature.

Hope you found this helpful! If you want to chat more, feel free to reach out on Twitter.

C# provides a rich set of built-in data structures, such as lists, dictionaries, and more, making it easier to work with data differently. Each structure has strengths and is optimised for specific scenarios, so understanding their differences is key to writing clean, efficient, and maintainable code.

In this tutorial, we’ll explore:

• Lists: Your go-to for dynamic, ordered collections where elements can grow and shrink effortlessly.

• Arrays: The efficient choice for fixed-size collections with predictable memory usage and blazing-fast indexing.

• Dictionaries: Perfect for quick lookups and managing key-value pairs with unmatched speed and clarity.

• Stacks: Ideal for last-in-first-out (LIFO) operations, like tracking history or nested structures.

• Queues: Best for first-in-first-out (FIFO) tasks, like processing jobs or managing sequential workflows.

• HashSets: The choice for collections where uniqueness matters and fast lookups are key.

By the end of this guide, you'll understand the differences between these structures and be equipped to choose the right one for your next project.

Table of Contents

1. Arrays in C#

2. Lists in C#

3. Dictionaries in C#

4. HashSets in C#

5. Queues in C#

6. Stacks in C#

7. Common Problems

For some of the following examples, you’ll need the Animal record below:

public record Animal(int Age, string Name, int Legs, string Sound);

Arrays

An array in C# is a fixed-size collection of elements. Arrays are indexed, and their size is set when they are created unlike Lists and other collections. Once defined, the size of an array cannot be changed, making the memory efficient with a low overhead.

Single-Dimension Arrays

Arrays are zero-index based, meaning their index begins at 0, rather than 1. If you’re not familiar, an index is a pointer to help you find an item.

For example, if you have 5 names in an Array, the first name is index [0], and the last name would be at index [4].

Arrays are great in scenarios where low-level performance is critical, as they have very little overhead due to their lack of metadata (additional attached information).

int[] numbers = new int[] { 1, 2, 3, 4, 5 };

foreach(var number in numbers){
    Console.Write(number);
}
//Ouput
// 1 2 3 4 5

In the above example, we instantiate an array with its values (thus giving it a fixed length). But we can assign values after the array is created by using index assignment.

Note: You must still specify the size of the array at the time of creation, as the code needs to know the fixed size of the Array.

// create an empty array of 20 indexes
var numbers = new int[20];

// loop over available indexes and assign `i` 
for (int i = 0; i < numbers.Length; i++)
{
    numbers[i] = i + 1;
}

foreach (var number in numbers)
{
    Console.Write($" {number}");
}
// Output
//  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

Multi-Dimensional Arrays

Arrays can also be multi-dimensional (for example, rows and columns), meaning they can hold two values. This makes them perfect for building grid-like structures.

Unlike a jagged array, where each element is an array that can have different lengths, a multidimensional array is a matrix-like structure where each dimension has a fixed size.

// Create a 2D multi-dimensional array to represent a chessboard

string[,] chessBoard = new string[8, 8];

// Creating the starting positions of a Chessboard
chessBoard[0, 0] = "Rook";
chessBoard[0, 1] = "Knight";
chessBoard[0, 2] = "Bishop";
chessBoard[0, 3] = "Queen";
chessBoard[0, 4] = "King";
chessBoard[0, 5] = "Bishop";
chessBoard[0, 6] = "Knight";
chessBoard[0, 7] = "Rook";

chessBoard[1, 0] = "Pawn";
chessBoard[1, 1] = "Pawn";
chessBoard[1, 2] = "Pawn";
chessBoard[1, 3] = "Pawn";
chessBoard[1, 4] = "Pawn";
chessBoard[1, 5] = "Pawn";
chessBoard[1, 6] = "Pawn";
chessBoard[1, 7] = "Pawn";

chessBoard[6, 0] = "Pawn";
chessBoard[6, 1] = "Pawn";
chessBoard[6, 2] = "Pawn";
chessBoard[6, 3] = "Pawn";
chessBoard[6, 4] = "Pawn";
chessBoard[6, 5] = "Pawn";
chessBoard[6, 6] = "Pawn";
chessBoard[6, 7] = "Pawn";

chessBoard[7, 0] = "Rook";
chessBoard[7, 1] = "Knight";
chessBoard[7, 2] = "Bishop";
chessBoard[7, 3] = "Queen";
chessBoard[7, 4] = "King";
chessBoard[7, 5] = "Bishop";
chessBoard[7, 6] = "Knight";
chessBoard[7, 7] = "Rook";


// Print the chessboard
for (int row = 0; row < 8; row++)
{
    for (int col = 0; col < 8; col++)
    {
        string piece = chessBoard[row, col] ?? "Empty";
        Console.Write($"{piece}\t");
    }
    Console.WriteLine();
}

Output:

Rook    Knight  Bishop  Queen   King    Bishop  Knight  Rook    
Pawn    Pawn    Pawn    Pawn    Pawn    Pawn    Pawn    Pawn    
Empty   Empty   Empty   Empty   Empty   Empty   Empty   Empty   
Empty   Empty   Empty   Empty   Empty   Empty   Empty   Empty   
Empty   Empty   Empty   Empty   Empty   Empty   Empty   Empty   
Empty   Empty   Empty   Empty   Empty   Empty   Empty   Empty   
Pawn    Pawn    Pawn    Pawn    Pawn    Pawn    Pawn    Pawn    
Rook    Knight  Bishop  Queen   King    Bishop  Knight  Rook

Jagged Array

Welcome to inception. A jagged array in C# is an array of arrays, where each "inner" array can have a different length.

Unlike multi-dimensional arrays, jagged arrays are not rectangular, meaning the rows can have varying sizes.

A usage example could be building a Calendar app. Below is a basic usage outputting the days of each month in the year:

int[][] daysInMonths = new int[12][];

// Initialize each month with its corresponding number of days
daysInMonths[0] = new int[31]; // January
daysInMonths[1] = new int[28]; // February (non-leap year)
daysInMonths[2] = new int[31]; // March
daysInMonths[3] = new int[30]; // April
daysInMonths[4] = new int[31]; // May
daysInMonths[5] = new int[30]; // June
daysInMonths[6] = new int[31]; // July
daysInMonths[7] = new int[31]; // August
daysInMonths[8] = new int[30]; // September
daysInMonths[9] = new int[31]; // October
daysInMonths[10] = new int[30]; // November
daysInMonths[11] = new int[31]; // December

// Print the number of days in each month
for (int month = 0; month < daysInMonths.Length; month++)
{
    Console.WriteLine($"Month {month + 1}: {daysInMonths[month].Length} days");
}

You should use an Array in:

• Performance-critical applications where memory overhead and speed matter.

• Fixed data sets where the size will not change.

• Multi-dimensional data, for example, graph coordinates (x, y)

Lists

A List<T> in C# is a resizable collection of items of the same type, signaled above by the letter T. It allows adding, removing, and accessing items by index. Unlike arrays, lists grow dynamically as needed.

Commonly used for sequential data, they support LINQ queries and various utility methods for data manipulation.

var animals = new List<Animal>()
{
    new Animal(10, "Dog", 4, "Woof"),
    new Animal(5, "Cat", 4, "Meow"),
    new Animal(2, "Lion", 4, "Roar"),
    new Animal(6, "Giraffe", 4, "Trumpet"),
    new Animal(15, "Red-Panda", 4, "Squeak")    
};

animals.Add(new Animal(2, "Hamster",4,"Squeak"));
animals.Remove(x=>x.Sound == "Meow"); // Remove all squeaking animals

Lists are a highly versatile data structure, where the order of items remains the same order in which they are added or removed (no manipulation. For example, whenever you call .Add() a method on a list, it will append the item to the list, and the order stays the same as before but with the additional animal.

You can modify the data (for example, filter, map, or sort) before sending lists to other areas of your application thanks to the extensive utility methods available in the List<T> class.

Dictionaries

Dictionaries work just like the term we know in the English language.

We have a key (a lookup term) and a value (the mapped object or data). Because of this, you might hear the term 'key-value pair' when referring to dictionaries.

Dictionaries are best used to efficiently retrieve data based on a unique identifier, such as an ID, name, or other uniquely identifying fields. They ensure their unique keys are ideal for scenarios requiring optimal performance without iterative searching.

I recommend using dictionaries when the order of elements is unimportant and you need to represent relationships, such as mapping countries to capitals, products to prices, or people to addresses.

var animalDictionary = new Dictionary<string, Animal>()
{
    { "Dog", new Animal(10, "Dog", 4, "Woof") },
    { "Cat", new Animal(5, "Cat", 4, "Meow") },
    { "Elephant", new Animal(8, "Elephant", 4, "Trumpet") },
    { "Lion", new Animal(2, "Lion", 4, "Roar") },
    { "Giraffe", new Animal(6, "Giraffe", 4, "Trumpet") },
};
// Add
animalDictionary.Add("Red panda", new Animal(2, "Red Panda", 4, "Squeaker"));

// Remove
animalDictionary.Remove("Cat");

//Get
var giraffe = animalDictionary["Giraffe"];

HashSets

A HashSet<T> is a collection in C# that stores unique elements. It uses a hash-based implementation to ensure very efficient lookups, additions, and deletions. This means it uses hash functions to quickly map keys to values, you can read more about that here.

Duplicate elements are automatically ignored.

How does this differ from a Dictionary? HashSets don't have keys like Dictionaries. Instead, they store values directly and are accessed by iterating over the elements using a foreach loop or LINQ queries.

var animalHashSet = new HashSet<Animal>()
{
    new Animal(3, "Lion", 4, "Roar"),
    new Animal(5, "Tiger", 4, "Roar"),
    new Animal(2, "Elephant", 4, "Trumpet"),
    new Animal(1, "Giraffe", 4, "Neigh")
};
// Add
animalHashSet.Add(new Animal(3, "Lion", 4, "Roar"));
// Remove
animalHashSet.Remove(x=>x.Sound == "Neigh");
// Get
animalHashSet.FirstOrDefault(x=>x.Name == "Elephant");

Above, we create a HashSet<Animal> and attempt to add a duplicate object. You may expect this to throw an error, as we know HashSets can only store unique values. But instead it handles it quite beautifully and simply doesn’t add the duplicate object, so the output is:

Animal { Age = 3, Name = Lion, Legs = 4, Sound = Roar }
Animal { Age = 5, Name = Tiger, Legs = 4, Sound = Roar }
Animal { Age = 2, Name = Elephant, Legs = 4, Sound = Trumpet }

Queues

Queues work in just the same way as a queue does in everyday life, with a first-in, first-out approach.

Queue<T> does not implement the ICollection interface like Dictionaries and Lists, meaning it doesn't have an Add() method. This means you cannot add elements to the Queue whilst instantiating. It also means you cannot use the Add() method to add items – instead, you use the Enqueue() method.

var arc = new Queue<string>();
arc.Enqueue("2 Lions");
arc.Enqueue("2 Tigers");
arc.Enqueue("2 Bears");

// Peek method allows to peek at the front of the queue
Console.WriteLine("Front of the Queue: " + arc.Peek());

// Output
// Front of the Queue: 2 Lions

Console.WriteLine($"Processing: {arc.Dequeue()}"); // Output: 2 Lions
Console.WriteLine($"Processing: {arc.Dequeue()}"); // Output: 2 Tigers

The Dequeue method not only returns the next item in the queue but also removes the item from the queue as expected. You can also clear the queue using the Clear() method.

Stacks

Stacks work oppositely to Queue<T>, in that instead of first-in-first-out, they work on a last-in-first-out mechanic.

var stack = new Stack<int>();
stack.Push(1);
stack.Push(2);
stack.Push(3);
stack.Push(4);
stack.Push(5);

// iterate over the Stack
foreach(var number in stack )
{
    Console.WriteLine(number);
}

// Output
// 5 4 3 2 1

You may think looping through the items in a Stack would work the same as a List or Queue and would still print them out in order of going in. But the system knows it’s a stack, and so it enumerates the items in reverse order of how they were added – that is, the most recently added element (5) is returned first.

You can also utilise the Pop() method which will return the last item in the collection, and remove it at the same time.

Common Problems

When using various collections, you will more than likely come across common problems, such as KeyNotFoundException when using dictionaries, IndexOutOfRangeException on lists/arrays, or InvalidOperationException when modifying a collection during iteration.

KeyNotFoundException

Scenario: You try to access a Dictionary key that doesn’t exist in the Dictionary. This will result in a KeyNotFoundException, and error.

var dictionary = new Dictionary<string, string>()
{
    { "Morning", "Good Morning" },
    { "Afternoon", "Good afternoon" },
    { "Evening", "Good evening" },
    { "Night", "Good night" },
};

var message = dictionary["Dusk"];

Console.WriteLine(message);

// Output
//Unhandled exception. System.Collections.Generic.KeyNotFoundException: The given key 'Dusk' was not present in the dictionary.

Solution: I recommend using the TryGetValue function, which will handle it gracefully and return the item as an out parameter (if it can be found, otherwise the default value).

TryGetValue returns a boolean to show whether it could or couldn’t find the provided key. This boolean value can then be utilised to determine functionality based on successful retrieval or not, rather than checking the output parameter, for example (if it is null/empty or not).

var dictionary = new Dictionary<string, string>()
{
    { "Morning", "Good Morning" },
    { "Afternoon", "Good afternoon" },
    { "Evening", "Good evening" },
    { "Night", "Good night" },
};

var input = Console.ReadLine(); // Dusk

dictionary.TryGetValue(input, out var message);
Console.WriteLine($"`Message:{message}`");
// Ouput = `Message ` (blank message as default string value is empty string

//or check if was able to retrieve and access output if it was
if(dictionary.TryGetValue(input,out var m)){
    Console.WriteLine(message);
}

IndexOutOfRangeException (Lists/Arrays):

Scenario: Trying to access an index that’s outside the valid range of a list or array.

As we know, Arrays are 0 index-based, so trying to access an index of [5] on an Array of 5 items will throw the IndexOutOfRangeException.

Solutions:

1. Ensure the index is within bounds using list.Count or array.Length before access.

2. Use the ElementAtOrDefault() method. If it can’t access an item at the given index, it will return the default value, which can then be handled accordingly.

var names = new string[]
{
    "Tony", "Clint", "Bob", "Alice", "Lisa"
};

var name = names.ElementAtOrDefault(6);
Console.WriteLine(name ?? "Name not found.");

InvalidOperationException (Iterating Collections):

Scenario: Modifying a collection (for example, adding or removing items) while iterating over it with a foreach loop will throw an InvalidOperationException because you're trying to remove an item from the list while iterating over it with a foreach loop.

var myList = new List<string> { "Apple", "Banana", "Cherry", "Banana" };

foreach (var item in myList)
{
    if (item == "Banana")
    {
        myList.Remove(item); // Throws InvalidOperationException
    }
}

Why This Happens:

• The foreach loop maintains an internal enumerator for the collection.

• Modifying the collection (for example, adding/removing items) invalidates the enumerator, which causes the runtime to throw an InvalidOperationException.

Solution 1: Use a for Loop

You can use a for loop with an index to safely modify the list during iteration:

var fruits = new List<string> { "Apple", "Banana", "Cherry", "Banana" };

for (int i = 0; i < fruits; i++)
{
    if (fruits[i] == "Banana")
    {
        fruits.RemoveAt(i);
        // Adjust the index to account for the removed item
        i--; 
    }
}
Console.WriteLine(string.Join(", ", fruits)); 
// Output: Apple, Cherry

Solution 2: Iterate Over a Copy

Another approach is to iterate over a copy of the list using ToList(). This way, you’re not directly iterating over the original collection, so modifications won’t affect the loop.

var originalList = new List<string> { "Apple", "Banana", "Cherry", "Banana" };

foreach (var item in originalList.ToList()) // Create a copy
{
    if (item == "Banana")
    {
        originalList.Remove(item); // Safe removal
    }
}
Console.WriteLine(string.Join(", ", originalList)); 
// Output: Apple, Cherry

Solution 3: Use LINQ to Filter

If you only want to remove items based on a condition, you can use LINQ to create a new filtered list:

var fruits = new List<string> { "Apple", "Banana", "Cherry", "Banana" };

fruits = fruits.Where(item => item != "Banana").ToList(); // Filter out "Banana"

Console.WriteLine(string.Join(", ", fruits)); 
// Output: Apple, Cherry

Closing Thoughts

In this article, you’ve learned about many of the common Data Structures for storing multiple objects and values.

Whether you're storing data in a fixed-size array, managing a dynamic list, working with first-in-first-out queues, last-in-first-out stacks, or key-value pair dictionaries, knowing when and how to use each collection is key to becoming a confident and proficient C# developer.

Mastering these concepts will not only improve your ability to handle data effectively but also lay the groundwork for more advanced topics in data structures and algorithms. Combining these data structures with LINQ can provide some performant and easy-to-use mechanics. To learn more about LINQ you can check out my article here.

As you continue your coding journey, keep experimenting with these collections, apply them in real-world scenarios, and deepen your understanding of their inner workings.

As always should you wish to discuss this article further, any other coding-related problems, or hear about other articles I’m writing, drop me a follow on X(Twitter)

Happy coding! 😊

In this article, I will show you how to test the performance of your code, benchmark your code, and identify areas of improvement within your code base.

Table of Contents

• What is Benchmarking?

• Why Using a Stopwatch is Not Reliable

• How to Use BenchMarkDotnet

• What Else Can You Test with BenchmarkDotnet?

What is Benchmarking?

Benchmarking measures the performance of your code, application, system, or hardware under specific conditions.

The goal is to gather precise data about how the system behaves for metrics like processing speed, memory usage, resource consumption, or throughput and to identify areas where performance can be optimized.

Why Using a Stopwatch is Not Reliable

Using the Stopwatch class for benchmarking in C# comes with many problems. Although it provides a simple way to measure elapsed time on a method or process, it lacks the precision, control, and consistency needed for accurate benchmarking.

Before I get into the negatives of this utility, let’s look at how you could use it for very simple tasks.

using System.Diagnostics;

// Create a new Stopwatch instance
var sw = new Stopwatch();

// Start the stop watch clock
sw.Start();

// run your code
var sum = 0;
for (int i = 0; i < 100; i++)
{
    sum += i * i;
    Console.WriteLine($"{sw.ElapsedMilliseconds}");
}
// Stop the clock !
sw.Stop();

// Output total time elapsed on the Stopwatch.
Console.WriteLine($"Elapsed time: {sw.ElapsedMilliseconds} ms");

This would print out how many milliseconds have elapsed on each iteration as well as the end elapsed milliseconds. As this is a short program, you can convert to nanoseconds by using ticks like so:

long ticks = stopwatch.ElapsedTicks;
double nanoseconds = (ticks * 1e9) / Stopwatch.Frequency;

Using a stopwatch can be useful if you want to quickly compare two methods or identify obvious performance bottlenecks during development. It’s a lightweight way to get an initial sense of which sections of code might need optimization.

Cons of Stopwatch

• Lack of precision by default, being only accurate to around 100 nanoseconds, which may not be useful for smaller quick micro operations.

• JIT (Just in Time) compilation - When code runs for the first time, a JIT compiler compiles the code before running, causing a delay and skewing the timing of completion. Subsequent runs of the code will be slightly faster, however, Stopwatch does not account for this. Keeping this in mind, it is worth running the code a few times to try and alleviate this problem.

• Garbage Collection (GC) - If garbage collection happens during a Stopwatch measurement, the time recorded will include GC pause time, which does not reflect the actual execution time of your code.

These are just some of the basic, and most common flaws of using a Stopwatch to test the performance of your code but there are others.

So what is the best approach?

BenchmarkDotNet is a popular and robust library for benchmarking in .NET, which can be installed using nuget.

It overcomes many of the above challenges, in the following ways:

• Code Warm Ups - Automatically warms up the code (by running the code a few times) to avoid JIT-related inaccuracies.

• Multiple code iterations - Runs the code multiple times to analyze and calculates statistical summaries, around execution time, heap memory allocation and more. The number of times the code is ran can be configured.

• Isolated Environments - Manages garbage collection and isolates the execution environment to reduce external interference.

How to Use BenchMarkDotnet

Firstly, we need to install the Nuget package. To do this, run the following command in your command line/terminal:

dotnet add package BenchmarkDotnet

We then need some methods to benchmark, so create a .Net 8 C# console app with the following two class files:

// Program.cs
using BenchmarkDotNet.Running;

BenchmarkRunner.Run<Benchmarks>();

//Benchmarks.cs
using BenchmarkDotNet.Attributes;

public class Benchmarks
{
    private readonly int[] _numbers = Enumerable.Range(1, 1000).ToArray();

    [Benchmark]
    public int ForLoopSum()
    {
        int sum = 0;
        for (int i = 0; i < _numbers.Length; i++)
        {
            sum += _numbers[i];
        }

        return sum;
    }

    [Benchmark]
    public int ForeachLoopSum()
    {
        var sum = 0;
        foreach (int number in _numbers)
        {
            sum += number;
        }

        return sum;
    }

    [Benchmark]
    public int LinqSelect()
    {
        return _numbers.Sum();
    }
}

Above, we have 3 different methods to add up an array of integers, each doing so in a slightly different fashion. This is a perfect example to show how benchmarking can aid us to choose the best solution in our code base.

How to Run the Benchmarks

To run the benchmarks, you can run the following commands in your terminal/command line.

dotnet build
# then run 
dotnet run -c Release

BenchmarkDotnet will then run the methods marked with the [Benchmark] attribute multiple times, and will output the results in an easy to read table, like so:

| Method         | Mean     | Error   | StdDev  |
|--------------- |---------:|--------:|--------:|
| ForLoopSum     | 434.2 ns | 0.40 ns | 0.31 ns |
| ForeachLoopSum | 321.9 ns | 1.22 ns | 1.14 ns |
| LinqSelect     | 189.4 ns | 0.84 ns | 0.70 ns |

What does this mean?

Method - Name of the method under test

Mean - Shows the mean (average) time it took in nanoseconds.

Error - Represents the margin of error, telling you how much the "Mean" result might vary due to random factors in the system. The lower the number the better, here you can see a very small margin of error meaning the results are stable, whilst large numbers would mean more uncertainty/ unreliable results.

StdDev - (Standard Deviation) shows how consistent the benchmark results are. A low deviation score indicates the time taken was very similar across multiple runs, increasing reliability. If the standard deviation is high, it would mean the method’s execution time varied a lot between runs.

How to Measure Memory Allocation

Knowing how fast your methods run is a great statistic to understand and know. However, your performance and optimization isn’t just about the time of execution, sometimes you should ensure that there are no memory leaks or large sums of memory utilized, especially with large execution process.

We can use the [MemoryDiagnoser] to the Benchmarks class, which informs the benchmarking library to include memory statistics to the methods under test.

When we run our benchmarks, we get the following output:

| Method         | Mean     | Error   | StdDev  | Allocated |
|--------------- |---------:|--------:|--------:|----------:|
| ForLoopSum     | 436.8 ns | 5.32 ns | 4.98 ns |         - |
| ForeachLoopSum | 324.6 ns | 2.20 ns | 2.06 ns |         - |
| LinqSelect     | 192.7 ns | 2.40 ns | 2.24 ns |         - |

But wait, the Allocated column has but a dash ? Where are the results?

Simple operations, like summing values in an array generally don’t allocate memory, as they often only use stack memory, which BenchmarkDotNet doesn’t track in the same way.

But using the following tests, we can see how memory allocation can be analyzed:

public class MemoryBenchmark
{
    [Benchmark]
    public string StringConcatenation()
    {
        string result = "";
        for (int i = 0; i < 1000; i++)
        {
            result += "text";
        }
        return result;
    }

    [Benchmark]
    public string StringBuilderConcatenation()
    {
        var builder = new System.Text.StringBuilder();
        for (int i = 0; i < 1000; i++)
        {
            builder.Append("text");
        }
        return builder.ToString();
    }
}

Output:

| Method                     | Mean       | Error     | StdDev    | Gen0     | Allocated  |
|--------------------------- |-----------:|----------:|----------:|---------:|-----------:|
| StringConcatenation        | 218.930 us | 0.7230 us | 0.6409 us | 641.8457 | 3933.56 KB |
| StringBuilderConcatenation |   1.645 us | 0.0034 us | 0.0030 us |   2.6875 |   16.47 KB |

Here we have 2 new columns:
Gen0 Column:
The Gen0 column indicates how many Gen 0 garbage collections occurred during each method’s execution.

.Net uses a generational garbage collection system, where memory is divided into three "generations" (Gen0, Gen1, and Gen2).

• Gen0 (Generation 0): Holds short-lived objects, such as temporary variables and small, quickly discarded objects. Gen0 collections are the fastest type of GC but still introduce some overhead. Examples of Gen0 would be local variables in methods, temporary objects, or method call arguments that aren’t used later on.

• Gen1 and Gen2: This is for longer-lived objects that survive Gen0 collections, like static objects that are kept alive for the lifetime of the application (that is, singletons), caching objects or large collections used across many operations.

Objects in Gen0 are collected quickly but often, and objects in Gen2 are collected infrequently but with more effort because they are larger or more persistent. A lot of Gen0 collections can be an indicator of inefficient memory usage, while Gen2 or 3 collections may indicate that your app is keeping too many long-lived objects in memory.

Allocated Column:
The Allocated column shows the total memory allocated by each method during its execution. This is typically reported in kilobytes (KB).

This information helps you see how memory-intensive each method is, which can impact performance, especially if the method is called frequently.

For example, StringBuilderConcatenation is much more memory-efficient than StringConcatenation, which makes it preferable in cases where memory usage is a concern or where this operation is performed frequently.

What Else Can You Test with BenchmarkDotnet?

Throughput

• Analyzes how many iterations of a method can be executed per second.

• Indicates the efficiency and scalability of the code.

JIT (Just-In-Time) Optimization Impact

• Evaluates the effects of JIT optimizations on performance.

• Can test cold starts (first-run performance) versus steady-state performance (subsequent runs).

Platform and Framework Differences

You could run benchmarks of the same code across different .NET runtimes (for example, .NET 6, .NET 8, .NET Framework) to compare whether it’s worth upgrading your application to newer systems or not.

Simply update the TargetFramework node in the .csproj file of your application to target the frameworks you wish to test.

Add the following attributes to your benchmark class (based on the target runtime).

[SimpleJob(runtimeMoniker: RuntimeMoniker.Net60)]
[SimpleJob(runtimeMoniker: RuntimeMoniker.Net80)]

when you run your application you will get an output as below highlighting the differenes in methods across both .net 6 and .net 8

Impact of Input Parameters

• Supports parameterized benchmarks to test how different inputs affect performance.

• Helps identify optimal input ranges or problematic edge cases.

You can do something like this

using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;

public class SortBenchmark
{
    [Params(10, 100, 1000)]  // Size of the array
    public int N;

    [Params(10, 100, 1000)]  // Maximum value of the array elements
    public int MaxValue;

    private int[] data;

    // Setup method to create an array before each benchmark
    [GlobalSetup]
    public void Setup()
    {
        data = new int[N];
        var rand = new Random();
        for (int i = 0; i < N; i++)
        {
            data[i] = rand.Next(MaxValue);
        }
    }

    [Benchmark]
    public void SortArray()
    {
        Array.Sort(data);  // Sort the array
    }
}

class Program
{
    static void Main(string[] args)
    {
        // Run the benchmark
        BenchmarkRunner.Run<SortBenchmark>();
    }
}

Giving the output of:

Third-Party Library Performance

Using the techniques mentioned above, you can compare the performance of different third-party libraries for the same task to make informed decisions on library usage.

Conclusion

There you have it, how to benchmark your C# application. Using a combination of these methods, tools and techniques, the possibilities of benchmarking are incredible.

You can use benchmarking to improve your application’s code base, help make decisions on upgrade paths, and method choices.

I hope you find this article helpful, and as always, if you wish to discuss it you can follow me on Twitter.

In this article, you’ll learn how to simplify your Git commands by using aliases.

Table of Contents

• Prerequisites

• What Are Git Aliases?

• How to Add Git Aliases Via the Global Git Configuration File (Recommended)

  • How to Set Your Preferred Git Editor

  • How to Open the Git Config File

  • How to Add a Git Alias Via Your Config File

• How to Add Aliases in the CLI

• How to Create Custom Commands for More Complex Shortcuts

  • How to Use Parameters in All Commands

• Other Useful Aliases

• Summary

Prerequisites

• Knowledge of Git.

• Git Bash installed (optional but recommended Windows users).

• An IDE like VS Code (this is also optional).

What Are Git Aliases?

Git aliases are custom shortcuts for existing Git commands, making common tasks quicker and easier. They let you define your commands, allowing you to tailor shortcuts exactly how you want.

You have two main options for adding/creating git aliases in your git configuration, using your Git configuration file or adding them directly via the CLI (terminal/command line).

How to Add Git Aliases Via the Global Git Configuration File (Recommended)

This option involves opening your global git config file and appending your git aliases to the bottom of the file.

How to Set Your Preferred Git Editor

Set your default Git config editor software, for example, I use VS Code to edit my Git configuration file, but you can use whatever text editor/code editor you prefer.

Run this command to set Notepad as your preferred editor on Windows (CMD/PowerShell):

git config --global core.editor "notepad"

Run this command to set VS Code as your preferred editor on Windows & MacOS /Linux:

git config --global core.editor "code --wait"

To set a different default editor, search online for “Set {editor} as default Git editor,” and replace {editor} with your preferred app.

How to Open the Git Config File

Open your terminal of choice and enter the following command. This will open the global Git config file (git config —global), in edit mode (-e).

git config --global -e

You can open the git configuration file directly from the following locations:

Mac Os: Home Directory → show hidden (Cmd + Shift + H) → .gitconfig

Windows: C:\Users\YourUsername\ → then show hidden files (in View) → and find .gitconfig

Linux: Home Directory → show hidden (Ctrl + H) → .gitconfig

How to Add a Git Alias Via Your Config File

If you're adding Git aliases for the first time, open your .gitconfig file, add [alias] at the end, and then list your shortcuts below. This tells Git these are aliases. Add your preferred alias (the shortened command you wish to run).

The format of a git alias is <alias> = <command>, so we have:

co = checkout
cob = checkout -b

Explanation of the above examples:

co = checkout this maps the git checkout command to a shorter git co command. You’d then call git co feature/123 in your terminal.

You do not need to type git in front of the command, as the configuration will pre-pend this automatically as it knows the command you’re mapping is a Git command.

Note: Any parameters passed to the command will be applied to the final command called within the alias only.

More aliases can be added in this way, mapping shortcuts to existing git commands. Saving and closing the file will then make the aliases available within your terminal.

How to Add Aliases in the CLI

If you want a more streamlined approach to adding Git aliases, you can add them directly from within the terminal/command line.

Taking the examples above, we can add these directly in the following way:

The format of the command is: git config --global alias.{alias} "{original command}":

git config --global alias.co "checkout"
#or
git config --global alias.cob "checkout -b"

It’s as easy as that!

How to Create Custom Commands for More Complex Shortcuts

Ok, this seems great, but it’s not really that impressive – we’re only removing a few characters. However, we can make them much more helpful, we can create our commands using shell commands.

Let’s take the following example, a command I use a lot!

new-work = !git checkout main && git pull && git cob

This alias combines multiple Git commands into one shell command. The ! character tells Git to treat it as a shell command, not a standard Git command.

Without !, Git treats the alias as a Git command (for example, checkout becomes git checkout). With !, Git knows to run it as a shell command without adding git in front.

By chaining these commands, we can write much more useful aliases. The one above will:

• First, check out the main branch.

• Using the && operator, it means the other commands will only run if the previous one has been successful.

• Secondly, it will pull down the changes from main.

• Finally, create a new branch from the main branch using our other alias git cob.

The final command can then accept parameters (as the original Git command would), so it can be used like so:

git new-work 'feature/new-work-from-main'

How to Use Parameters in All Commands

Up until now, we’ve only been able to pass our parameters to the final git command in our alias. However, what if we want to pass parameters to some, if not all of the commands within the alias? We can achieve this by using a shell function.

Take the following example:

new-work = "!f() { git checkout \"$1\" && git pull && git checkout -b \"$2\"; }; f"

Above we’re using a shell function that processes input parameters.

Explanation:

1. !f():

   • The ! tells Git to interpret the alias as a shell command rather than a standard Git command.

   • f() defines a shell function f that will allow us to execute multiple commands in sequence.

2. Everything inside { } is what will be executed within the f() function.

3. git checkout \”$1”'\: Will run a parameterized Git command, where $1 is escaped and will be replaced with the 1st parameter passed to the alias. The \" escape sequences around $1 allow for branch names with spaces.

4. && is a logical operator that ensures each command only runs if the previous one succeeds. If git checkout "$1" fails, the commands that follow won’t run.

5. git checkout -b \”$2”\ : Creates a new branch with the name of the second parameter as before.

6. ;: Marks the end of the f() function;

7. f: The final f calls the alias function immediately, meaning that when you call the alias, it declares the function and then calls it immediately.

Usage:

git new-work development task/feat-123

Other Useful Aliases

[alias]
     co = checkout
    cob = checkout -b
    s = status
    tidy-up = !git checkout main && git branch | grep -v "main" | xargs git branch -D
    latest = !git checkout main && git pull
    new-work = "!f() { git checkout \"$1\" && git pull && git checkout -b \"$2\"; }; f"
    done = !git push -u origin HEAD
    save = !git add -A && git commit
    saveM = !git add -A && git commit -m
    br = branch --format='%(HEAD) %(color:yellow)%(refname:short)%(color:reset) - %(contents:subject) %(color:green)(%(committerdate:relative)) [%(authorname)]' --sort=-committerdate

Summary

co: Checkout given branch → git co task/feat-123

cob: Creates a new branch from the current branch → git cob feature/123

s: Calls git status to view the status of the current git branch → git s

tidy-up: Deletes all local branches other than main → git tidy-up

latest: Gets the latest changes from remote main branch → git latest

new-work: Creates a new branch (2nd param) from 1st param branch → git new-work main feat/123

git done: Pushes the current branch to the remote repository (origin) and sets it as the upstream branch. This can be helpful when pushing your first commit and you get the error:
fatal: The current branch has no upstream branch. To push the current branch and set the remote as upstream, use git push --set-upstream origin

save: Will simply add all changed files, and commit them, opening your default Git editor and requesting a commit message → git save

savem: Will do as above, but instead of opening your editor, you can pass in a commit message inline → git savem ‘Task123: add index.html

br: This one looks complicated, but it’s not as complicated as it seems but does highlight the power of aliases. In essence, it customizes the output format of git branch to display a detailed, color-coded list of branches, sorted by the most recent commit date, it will look something like the image below for each branch you have locally.

There you have it, an introduction to Git aliases and some useful examples of aliases you can add as a starter to your configuration.

As always if you want to chat about it, or hear about future articles you can follow me on Twitter.

This is particularly useful when you want to add new functionality to a type you don't own or can't change, like types from third-party libraries or built-in .NET types such as string, List<T>, and so on.

In this article, you’ll learn how to add extension methods to your classes, as well as third-party and system classes.

Table of Contents

• How to Create DateTime Extension Methods

• How to Chain Same-Type Extension Methods

• Why Can’t I Just Add These Methods to My Class?

• When to Use Extensions

• When Not to Use Extension Methods

• Things to Consider When Designing Extensions

• Conclusion

How to Create DateTime Extension Methods

Let’s say we want some methods that can be used along with the existing DateTime class, perhaps a method that returns whether the given DateTime object is a weekend or something different.

Extension methods need to be defined in a static class because they are essentially syntactic sugar that allows you to call a static method as if it were an instance method on the type you're extending.

Extension methods need to be in a static class because:

1. No Object Needed: You don’t need to create an object to use an extension method. Since the method adds new functionality to an existing type (like string), it can work without needing an instance of the class.

2. Organized Code: Putting extension methods in a static class keeps things tidy. It allows you to group related methods, and you can easily include them in your code by using the appropriate namespace.

So, by using a static class, you can add useful methods to existing types without changing their original code, and you don’t need an object to call them.

First, let’s create a DateTimeExtensions static class.

public static class DateTimeExtensions {

}

This will encompass all the DateTime extensions we want to create.

public static bool IsWeekend(this DateTime date)
{
    return date.DayOfWeek is DayOfWeek.Saturday or DayOfWeek.Sunday;
}

Explanation:

public static bool IsWeekend: This defines that it is a static method called IsWeekend which will return a bool value (true/false).

this DateTime date: The this keyword as a method argument denotes that this method is an extension method. It means that the method will be an extension of the DateTime class.

How to Chain Same-Type Extension Methods

For an extension method to be chained with others, it typically needs to return the same type as the one it's extending (or a compatible type). This allows another method to be called on the result of the previous one.

using System.Globalization;

public static string ToTitleCase(this string str)
{
    return CultureInfo.CurrentCulture.TextInfo.ToTitleCase(str.ToLower());
}

public static string TrimAndAppend(this string str, string toAppend)
{
    return str.Trim() + toAppend;
}

In the above example, both the ToTitleCase and TrimAndAppend methods return a string value, meaning that we can chain the extension methods as below, which will convert the string to title-case before trimming all whitespace and appending the provided string.

Notice that we only provided the second parameter to the TrimAndAppend method, as the first parameter is the string having the extension method applied to (as explained previously, denoted by the this keyword).

var title = "hello world   "
    .ToTitleCase()
    .TrimAndAppend("!!");

//Output:
// Hello World!!

If the extension method returns a different type (not the original one or a compatible type), you cannot chain it. For example:

var date = new DateTime();
date.IsWeekend().AddDays(1);

For less obvious reasons, this will not work. When you chain methods, they do not chain from the original variable—they chain from the return type of the previous method call.

Here, we have a date called IsWeekend() which returns a Boolean. We then attempted to call AddDays(1) on a Boolean value which doesn’t exist, as it is a DateTime extension. The code compiler will fail to build, raising an error informing you of this.

How to Return the Instance to Chain

In some extension methods, especially those for configuration (like Dependency Injection), you return the same instance to allow method chaining. This lets you continue working with the original object or its modified state across multiple calls, enabling a fluent interface.

Let’s take the example of a list of cars.

public static List<T> RemoveDuplicates<T>(this List<T> list)
{
    // Use Distinct to remove duplicates and update the list
    list = list.Distinct().ToList();

    // Return the modified list to allow method chaining
    return list;
}

public static List<T> AddRangeOfItems<T>(this List<T> list, IEnumerable<T> items)
{
    // Add a range of items to the list
    list.AddRange(items);

    // Return the modified list to allow method chaining
    return list;  
}

Now that we’ve returned the list from these extension methods, we can chain additional methods on the same list. For example, after removing duplicates with RemoveDuplicates(), we can immediately call AddRangeOfItems() on the same list.

So we can do something like:

var existingStock = new List<string> { "Ford", "Jaguar", "Ferrari", "Ford", "Renault" };

var availableBrands = existingStock
    .RemoveDuplicates()
    .AddRangeOfItems(new[] { "Lamborghini" }); // new stock available

Console.WriteLine("Brands Available Now: " + string.Join(", ", availableBrands));

// Output: Brands Available Now: Ford, Jaguar, Ferrari, Renault, Lamborghini

We removed duplicates from a list of car brands and added new stock to the same list. This works because RemoveDuplicates returns the list, enabling us to chain it with AddRangeOfItems.

If RemoveDuplicates returned void instead of the list, we wouldn't be able to chain the methods. It would still remove duplicates, but further actions like adding new stock, wouldn't be possible in the same expression.

We’d also have to update the RemoveDuplicates to update the list argument passed in, as Distinct() returns a new list which isn’t being returned as shown below, which I think you’ll agree is a lot more verbose.

public static void RemoveDuplicates<T>(this List<T> list)
{
    // Get the distinct elements and clear the original list
    var distinctItems = list.Distinct().ToList();
    list.Clear(); 

    // Add the distinct items back to the original list
    list.AddRange(distinctItems);
}

Why Can’t I Just Add These Methods to My Class?

If the method is not a core part of the class’s functionality, placing it in an extension method can help keep the class focused and maintainable.

Separation of Concerns: Using extension methods keeps your code cleaner, and helps reduce complexity. It helps avoid bloating the class with methods that may not be used frequently.

Enhancing External Libraries: If you’re using a library or framework where you cannot modify the source code, extension methods allow you to add functionality to those types without altering their definitions.

Let’s say you’re using the FileInfo class from the System.IO namespace to work with files. You may want to add a method to easily check if a file is too large (for example, more than 1 GB), but you cannot modify the FileInfo class directly because it belongs to the System.IO namespace (that is, it's baked into .Net).

Without an extension:

var fileInfo = new FileInfo("myFile.txt");

if (fileInfo.Length > 1024 * 1024 * 1024) // filesize is bigger than 1GB
{
    Console.WriteLine("The file is too large.");
}
else
{
    Console.WriteLine("The file size is acceptable.");
}

With Extension Method:

You can make this more reusable by adding an extension method that checks whether the file is larger than 1 GB.

public static class FileInfoExtensions
{
    //extension method, with default file size of 1GB (can be overriden)
    public static bool IsFileTooLarge(this FileInfo fileInfo, long sizeInBytes = 1024 * 1024 * 1024)
    {
        return fileInfo.Length > sizeInBytes;
    }
}

Now you can use the IsFileTooLarge method directly on FileInfo objects, making your code cleaner:

csharpCopy codevar fileInfo = new FileInfo("myFile.txt");

if (fileInfo.IsFileTooLarge())
{
    Console.WriteLine("The file is too large.");
}
else
{
    Console.WriteLine("The file size is acceptable.");
}

Extending third-party libraries and packages can make your code much more compatible.

Better Organization & Readability: You can organize extension methods into static classes based on functionality or context, making it easier to find and use them. This is certainly enhanced by allowing extension methods to be chained.

When to Use Extensions

• For Utility Methods: If you have utility methods that are useful for a type but don’t belong directly in the type itself (for example, formatting, validation).

• For Enhancing Built-In Types: If you want to add functionality to built-in types (like string or DateTime) without modifying them.

• When You Want to Keep Methods Optional: If you want to provide additional methods that users can opt to use without forcing them to incorporate them into the main class design.

Example Scenario

Imagine that you have a Person class, and you want to add a method to format the person's name nicely:

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

// Extension method in a static class
public static class PersonExtensions
{
    public static string GetFullName(this Person person)
    {
        return $"{person.FirstName} {person.LastName}";
    }
}

By using an extension method for GetFullName, you can keep the Person class simple and focused on its core responsibilities, while still providing useful functionality.

When Not to Use Extension Methods

• For Core Functionality: If a method is essential to a class's core behavior, it should be part of the class itself, not an extension.

• For Tight Coupling: If the extension method requires intimate knowledge of the class's private state or needs regular access to its internal logic.

• For Public APIs: When designing a public-facing library or API, it's often better to include necessary methods directly in the class rather than forcing users to find or create their extension methods.

Things to Consider When Designing Extensions

While extension methods are powerful and convenient in many cases, there are certain cons or situations where using them might not be the best choice:

Hidden Behavior/Confusion

• Extension methods don't appear directly in the class definition, meaning that they can be harder to discover by developers who are unfamiliar with the available extensions.

• Developers need to know that these extension methods exist, or they might miss using them unless they are working in an IDE with features like IntelliSense (for example, Visual Studio, JetBrains Rider). These IDEs can suggest extension methods from other files or namespaces as they detect the appropriate type. Without a feature-rich IDE, the developer would have to be aware of the extension methods or find the folder they’re stored in.

Can’t Access Private Members

• Extension methods can only access members (methods, properties, fields) that are public or internal.

• They cannot access private or protected members of a class because extension methods operate as if they are part of the class from the outside, similar to regular method calls from outside the class.

Example:

public class Car
{
    private string engineNumber = "12345"; // Private field

    public string Brand { get; set; } = "Ford"; // Public property

    private void StartEngine() // Private method
    {
        Console.WriteLine("Engine started");
    }
}

public static class CarExtensions
{
    public static void DisplayBrand(this Car car)
    {
        Console.WriteLine($"Brand: {car.Brand}"); // Accessing the public 'Brand' property
    }

    public static void TryAccessPrivateField(this Car car)
    {
        // Cannot access the private 'engineNumber'
        // This will result in a compile-time error.
        Console.WriteLine(car.engineNumber);
    }
}

Code Duplication & Overuse

• In some cases, extension methods can encourage code duplication. If multiple projects or classes require similar extension methods, you might end up writing or copying the same extension methods in different places, making it harder to manage and update the code consistently.

  To avoid this, organize your code effectively. I would recommend keeping all extensions within an extensions folder or project, close to the origin (depending on the design patterns being used within your application).

• Abuse of Extensions: If used excessively, they can clutter the global space with methods that might not need to be global. This can cause pollution of the type’s API, making it harder to understand what’s core to the class versus what’s added via extensions.

In some cases, it's better to encapsulate functionality in a separate helper classes or services rather than adding it via extension methods.

Conclusion

Extension methods are useful for adding functionality in a clean and modular way, but they can also introduce confusion, namespace conflicts, and lack of access to private members.

As highlighted throughout the article, they have many usages and are certainly a very nice feature of the Dotnet framework when used effectively. They should be used when appropriate, but not as a substitute for functionality that belongs within the class itself.

C# (C Sharp) offers multiple ways to do these things, and I’m about to show you some of the most common ones. We’ll discuss the pros and cons of each method, and which ones are more suited for particular scenarios.

Table of Contents

• What You Will Learn In This Article

• If / Else if / Else Statements

• Replacing If / Else with Ternary Operator

• Switch Case Statements

• Switch Statements - Expression Syntax

• Performance Summary

• Conclusion

What You Will Learn In This Article

I will teach you all about the following conditional coding mechanisms within C#.

• If / Else If / Else statements

• Ternary statements

• Switch-Case statements

• Analysing performance of conditional coding options

Pre-requisites:

• Very basic knowledge of the C# coding language

• Coding IDE (to code along if you wish)

If / Else if / Else Statements

When first learning a new programming language, the If statement is a staple in any developer’s learning syllabus. It’s the easiest way in which you can conditionally route the flow of your code’s execution.

Let’s take a look at building up the complexity of the the If statement syntax. In its most basic form, you can use it as a simple if clause, meaning the code within the if block will only be executed if a condition is met.

Example:

// For the demo we're using a hard coded age.
int age = 22;

//check person is of legal age in the UK
if (!string.IsNullOrEmpty(age) && age >= 18)
{
   // If true, run the following code
   AllowAccessToNightClub();
}

Going one step further, if we wanted to carry out some code where the statement results in false, we can do that using an if / else statement like so:

var ageLimit = 18;
var customersAge = 17

if(customersAge >= ageLimit){
{   
    AllowAccessToTheClub();
} else{
    // Deny Access
    DenyAccess();
    // we can also nest if statements
    // if the customer doesn't leave call the Police!
    if(!CustomerLeaves()){
        CallThePolice();
    };
}

The above example illustrates how you can use if / else statements to control your flow of code. You’ve seen how you can handle specific scenarios with nested statements, allowing you to check future outcomes.

In the above code, we are checking if CustomerLeaves() returns a true or false value, and depending on the outcome, we see whether we need to CallThePolice() or not.

For situations where you want to check more than one condition before defaulting to else, you can use the if / else if / else syntax. Let's see how it works:

int age = 17;

if(age >= 18){
    Console.WriteLine("You can drink alcohol in the UK");
    Console.WriteLine("You can vote in the UK");
    Console.WriteLine("You can get a tattoo");
} else if(age >= 16 && age < 18){
    Console.WriteLine("You can join the royal forces in the UK");
} else{
   Console.WriteLine("Stay in School!");
}

The example above uses if / else if / else to display different text based on which condition is met. Only one block will ever run, as you can only match a single condition with this syntax.

Let’s say you wanted to build a stringup based on multiple conditions, but you wanted all conditions to be checked individually. In that case, you could utilise multiple if statements to accomplish this. Be aware, though, that this can make your code less performant and harder to read.

using System.Text;

int age = 20;
bool hasDrivingLicense = true;
bool hasVoterID = false;

var builder = new StringBuilder();

// Multiple independent if statements
if (age >= 18)
{
    builder.Append("You are an adult.");
}

if (hasDrivingLicense)
{
    builder.Append("You can drive.");
}

if (hasVoterID)
{
    builder.Append("You are eligible to vote.");
}

Console.WriteLine(builder.ToString());
Console.WriteLine(builder.ToString());
/* Output
You are an adult.You can drive.
*/

The above code demonstrates using multiple if statements instead of if, else if, else. This allows multiple conditions to be checked independently, so multiple code blocks can run if the conditions are met. This is useful when wanting to assign values to an object’s properties based on different criteria or independent conditions.

Replacing If / Else with Ternary Operator

If / Else statements are very useful, but sometimes they can take up a lot of space for really simple assignment code. The ternary operator is perfect for these situations. Its syntax uses ? and : to represent what happens if the condition is true or false, eliminating the need for brackets.

Here’s an example:

var backgroundColor = isDarkMode ? "black" : "white";

Explanation:

• backgroundColor: The variable being assigned.

• isDarkMode: A boolean condition being evaluated.

• ?: Marks the start of the ternary operator. If isDarkMode is true, the value after ? ("black") is assigned.

• :: Separates the true case from the false case. If isDarkMode is false, the value after : ("white") is assigned.

The ternary statement is shorthand for simple conditional assignments, making your code more compact. I would recommend using it for simple variable assignment or simple binary calling of functions (like call A or call B).

Here’s an example:

isLoggedIn ? ShowWelcomeMessage() : PromptLogin();

void ShowWelcomeMessage()
{
    Console.WriteLine("Welcome back, user!");
}

void PromptLogin()
{
    Console.WriteLine("Please log in to continue.");
}

Ternary operations can be nested also like so:

var isDarkMode = true;
var isAccessibilityActive = true;

var backgroundColor = isDarkMode ? isAccessibilityActive ? "green" : "black" : "white";

Console.WriteLine(backgroundColor);

The above example uses nested ternary operators to replace a nested if / else statement. Just keep in mind that the flow is different from a regular ternary operation. It would read like this:

IF isDarkMode is true, then check if isAccessibilityActive is true

IF isAccessibility is true, set the value to “green” otherwise return “black”

IF isDarkMode is false it will skip the inner checks, and return “white”;

I’d avoid using nested ternary operators where you can, as they’re messy and can be difficult to read.

Switch Case Statements

Switch case statements work by testing a variable (switch) against multiple possibilities (case).

string userRole = "Admin";

// check the user role against following criteria.
switch (userRole)
{
    case "Admin":
        Console.WriteLine("You have full access.");
        break;
    case "Moderator":
        Console.WriteLine("You can moderate content.");
        break;
    case "User":
        Console.WriteLine("You have limited access.");
        break;
    default:
        Console.WriteLine("Role not recognised.");
        break;
}

Note: the value and type of variable being evaluated must match. For example, you can’t compare a string with a integer (without casting / parsing first). If none of the cases match, the default block is executed, similar to the else in an if/else structure, usually used for a fallback case.

Why Use Switch-Case Over If Statement?

Readability: When handling multiple distinct values (like roles, commands, or enum types), switch is easier to read and maintain because it organises conditions more cleanly, without multiple if and else if blocks.

Performance: In some cases, switch statements can be more efficient than multiple if / else if blocks, especially when dealing with multiple possible values of a single variable. Some compilers optimise switch statements into lookup tables, improving performance

Scalability: When managing a long list of distinct options or conditions, a switch case scales better. Adding new cases is simpler and doesn't involve updating long chains of if / else if.

Clean Defaults: The default case provides a clear way to handle unrecognised or unexpected scenarios, similar to the else block in an if / else if statement, but it feels more naturally integrated with the switch structure. This can be handy for throwing exceptions, logging, and so on.

Switch Statements - Expression Syntax

There are times where you need slightly more complex conditions to be evaluated yet still wish to utilise the switch syntax. In this scenario you can utilise the switch expression syntax which was introduced in C# 8.

string userType = "VIP";
decimal purchaseAmount = 500m;

decimal discount = userType switch
{
    "Regular" when purchaseAmount < 100 => 0.05m,  
    "Regular" => 0.10m,  
    "VIP" when purchaseAmount < 500 => 0.15m,  
    "VIP" => 0.20m,  
    "Employee" => 0.25m,  
    _ => 0m 
};

Console.WriteLine($"Your discount is: {discount * 100}%");

This syntax is great when needing to assign a value to the outcome of the case.

• userType switch { ... }: a switch expression that returns a value (in this case, the discount) based on the userType and optional conditions (like purchaseAmount).

• The when clause allows for more complex conditions, such as checking the purchaseAmount in addition to the userType to alter the discount amount.

Default Case / Fallback

The default case in this syntax uses the _ character. In our example, if none of the above cases are met, the default case is met and we return 0m (no discount).

Benefits of Switch Expressions Over Conventional switch Statements:

Concise and Readable: The switch expression is more compact and readable, especially when returning values directly based on conditions, without needing to declare variables or use break statements.

Pattern Matching: It supports pattern matching (when), making it easier to add complex conditions to each case, something that would require more verbose if checks in a traditional switch statement.

Returns a Value: The switch expression is an expression that directly returns a value, making it ideal for assignments or inline use, reducing boilerplate code. Below, you’ll find an example using a switch expression as the return value in a method without assigning it to a variable.

Simplifies Complex Logic: It's excellent for scenarios like this one, where multiple conditions affect the outcome, handling them concisely without deeply nested if / else if blocks.

decimal CalculateDiscount(string userType, decimal purchaseAmount) =>
    userType switch
    {
        "Regular" when purchaseAmount < 100 => 0.05m,
        "Regular" => 0.10m,
        "VIP" when purchaseAmount < 500 => 0.15m,
        "VIP" => 0.20m,
        "Employee" => 0.25m,
        _ => 0m
    };

// Usage
decimal discount = CalculateDiscount("VIP", 500m);
Console.WriteLine($"Your discount is: {discount * 100}%");

Performance Summary

To help you decide, here are is a quick Benchmarking project (using BenchmarkDotNet package, which you can install with dotnet add package BenchmarkDotnet):

using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Order;
using System.Collections.Generic;

namespace Csharp_Console_Playground
{
    [MemoryDiagnoser]
    [Orderer(SummaryOrderPolicy.FastestToSlowest)]
    public class BenchMarkRunner
    {
        private static readonly Dictionary<int, string> RankingMessages = new()
        {
            { 0, "Do not stay in this hotel" },
            { 1, "It's cheap and cheerful" },
            { 2, "It's clean and tidy" },
            { 3, "In the middle hotel, good service and great amenities" },
            { 4, "It's a nice hotel, but the price is not too high" },
            { 5, "It's the best hotel in the area" }
        };

        private int ranking = 5;

        [Benchmark]
        public string BenchMarkIfElse()
        {
            var winningMessage = "";

            if (ranking == 0)
            {
                winningMessage = "Do not stay in this hotel";
            }
            else if (ranking == 1)
            {
                winningMessage = "It's cheap and cheerful";
            }
            else if (ranking == 2)
            {
                winningMessage = "It's clean and tidy";
            }
            else if (ranking == 3)
            {
                winningMessage = "In the middle hotel, good service and great amenities";
            }
            else if (ranking == 4)
            {
                winningMessage = "It's a nice hotel, but the price is not too high";
            }
            else if (ranking == 5)
            {
                winningMessage = "It's the best hotel in the area";
            }

            return winningMessage;
        }

        [Benchmark]
        public string BenchMarkSwitchCaseExpression()
        {
            var winningMessage = ranking switch
            {
                0 => "Do not stay in this hotel",
                1 => "It's cheap and cheerful",
                2 => "It's clean and tidy",
                3 => "In the middle hotel, good service and great amenities",
                4 => "It's a nice hotel, but the price is not too high",
                5 => "It's the best hotel in the area",
                _ => ""
            };

            return winningMessage;
        }

        [Benchmark]
        public string BenchMarkSwitchCase()
        {
            var winningMessage = "";
            switch (ranking)
            {
                case 0:
                    winningMessage = "Do not stay in this hotel";
                    break;
                case 1:
                    winningMessage = "It's cheap and cheerful";
                    break;
                case 2:
                    winningMessage = "It's clean and tidy";
                    break;
                case 3:
                    winningMessage = "In the middle hotel, good service and great amenities";
                    break;
                case 4:
                    winningMessage = "It's a nice hotel, but the price is not too high";
                    break;
                case 5:
                    winningMessage = "It's the best hotel in the area";
                    break;
                default:
                    winningMessage = "Invalid ranking";
                    break;
            }

            return winningMessage;
        }

        [Benchmark]
        public string? BenchMarkDictionary()
        {
            return RankingMessages.TryGetValue(ranking, out var rankingMessage) ? rankingMessage : null;
        }
    }
}

You can then run these tests in your Program.cs:

using BenchmarkDotNet.Running;
using Csharp_Console_Playground;

BenchmarkRunner.Run<BenchMarkRunner>();

Make sure you use your Release build profile in order to run the benchmarks.

 dotnet build -c Release

then execute dotnet on your build location, for example:

dotnet bin/Release/net8.0/FCC-Conditions.dll

Results:

switch statements can be faster than dictionaries because the compiler helps optimise them. When the compiler sees a switch, it can create a special lookup table (jump table, or binary search tree) that allows it to find the right case quickly, especially when the cases are close together (like numbers 1, 2, and 3). This means it can check the value almost instantly.

The reason the dictionary is the slowest is due to memory allocation. Within our bench mark test, we needed to create an in-memory variable for the dictionary to be created and stored (time consuming), and then retrieval also needs to be carried out when doing the lookup.

Switch-Case Expressions:

Compile-Time Optimisation: Switch cases are typically optimised at compile-time (when you build your code). The compiler analyses the possible case values and generates efficient machine code to handle them. Depending on the cases, this could be via jump tables, or branching / binary search mechanisms.

Since this is all done during compilation, the switch statement has no additional overhead at runtime beyond what the compiler has set up.

Dictionaries:

Runtime Construction: In contrast, a dictionary (for example, Dictionary<TKey, TValue> in C#) is built at runtime. The dictionary uses a hash table under the hood, where keys are hashed to generate an index that maps to a value. Here’s the key difference:

• Hash Function: When you add a key to a dictionary, the hash function is applied to the key to determine where the value should be stored.

• Collision Handling: If two keys happen to have the same hash (a "collision"), the dictionary has to resolve it (usually by chaining or probing), which can introduce some additional overhead.

Since dictionaries are built and modified at runtime, they have to perform these operations dynamically, which adds more overhead compared to the static structure of switch cases.

Conclusion

Understanding how to control the flow of your code through conditional logic is a foundational skill in programming, and C# offers various tools to achieve this. Whether you're using if/else statements for simple conditions, the ternary operator for concise assignments, or switch statements for complex logic, each approach has its strengths and ideal use cases.

Switch statements provide clarity and performance optimisations, especially when handling multiple conditions. On the other hand, dictionaries offer flexibility but come with a runtime overhead. Knowing when to use each method allows you to write more efficient, readable, and maintainable code tailored to specific scenarios.

As always if you want to chat about any of my articles you can follow me on Twitter.

DRY is a concept you may have come across—it means “Don’t Repeat Yourself”. DRY is a coding principle that encourages you to minimize code duplication by using abstractions like functions or modules.

It's important because it reduces redundancy, makes code easier to maintain, improves readability, and decreases the risk of errors during updates.

What Will This Article Cover?

In this article, you’ll learn:

• How to build a modal using React and CSS.

• How to ensure that the modal can be reused in multiple scenarios, content and styling.

• How to integrate state and callback functions into the modal.

Table of Contents

• What Will This Article Cover?

• The Core Modal Component

• Props Interface

• The Markup

• React useEffect

• When Do We Use useEffect?

• How to Use the Reusable Modal

• Additional Improvements

• Conclusion

The Core Modal Component

In this section, we'll use React to build a component library. There are multiple patterns that you can follow to do this, but one of my favorite is the atomic design pattern.

import React, {useEffect} from 'react';
import './Modal.css'

interface Props {
    open: boolean;
    cancelFn?: () => void;
    primaryFn?: () => void;
    closeIcon?: string;
    content?: React.ReactNode;
    titleContent?: React.ReactNode;
    className?: string;
}

export const Modal: React.FC<Props> = (props) => {
    const {open, cancelFn, primaryFn, closeIcon, titleContent, content} = props;

    // simple useEffect to capture ESC key to close the modal 
    useEffect(() => {
        const handleKeyDown = (e: KeyboardEvent) => {
            if (e.key === 'Escape' && open) {
                if (cancelFn) {
                    cancelFn();
                }
            }
        };

        document.addEventListener('keydown', handleKeyDown);
        return () => document.removeEventListener('keydown', handleKeyDown);
    }, [open, cancelFn]);


    if (!open) return null;

    return (
        <div className="modalBackground">
            <div className="modalContainer">
                {titleContent && (<div className="title">
                        {titleContent}
                        <div className="titleCloseBtn">
                            <button onClick={cancelFn}>{closeIcon ?? 'X'}</button>
                        </div>
                    </div>
                )}

                <div className="body">
                    {content}
                </div>

                <div className="footer">
                    {secondaryFn && (
                        <button onClick={secondaryFn} id="cancelBtn">
                            Cancel
                        </button>
                    )}
                    {primaryFn && (
                        <button onClick={primaryFn}>Continue</button>
                    )}
                </div>
            </div>
        </div>

    );
};

.modalBackground {
    width: 100vw;
    height: 100vh;
    background-color: rgb(33, 33, 33, 0.9);
    position: fixed;
    display: flex;
    justify-content: center;
    align-items: center;
}

.modalContainer {
    display: flex;
    flex-direction: column;
    border-radius: 20px;
    background-color: white;
    box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;

}

.modalContainer .title {
    display: flex;
    flex-direction: row;
    text-align: center;
    align-items: center;
    justify-content: space-between;
    padding: 8px;
    border-top-right-radius: 20px;
    border-top-left-radius: 20px;
    background-color: #FFE936;
}

.titleCloseBtn {
    display: flex;
    justify-content: flex-end;
}

.titleCloseBtn button {
    font-size: 0.3rem;
}

.titleCloseBtn button {
    background-color: transparent;
    border: none;
    font-size: 25px;
    cursor: pointer;
}

.modalContainer .body {
    flex: 1;
    padding: 16px;
    display: flex;
    flex-direction: column;
    justify-content: center;
    align-items: center;
    font-size: 1rem;
    text-align: center;
}

.modalContainer .footer {
    display: flex;
    justify-content: center;
    align-items: center;
}

.modalContainer .footer button {
    width: 150px;
    height: 45px;
    margin: 10px;
    border: none;
    background-color: cornflowerblue;
    color: white;
    border-radius: 8px;
    font-size: 20px;
    cursor: pointer;
}

#cancelBtn {
    background-color: crimson;
}

The code above is the core modal component. Let’s break it down.

Props Interface

interface Props {
    open: boolean;
    cancelFn?: () => void;
    primaryFn?: () => void;
    closeIcon?: string | React.ReactNode;
    content?: React.ReactNode;
    titleContent?: React.ReactNode;
}

In this interface (which we’re passing to the Modal component) we have:

• open: A boolean value that signifies whether the modal should be shown or not. A common way of toggling the modal on or off.

• cancelFn: An optional parameter (denoted by ?) that provides a call back function for when the secondary button is being pressed. For example, the cancel functionality to close the modal, or undo an action.

• primaryFn: An optional parameter that provides a call back function for when the primary button is being pressed. For example, ok, confirm, or submit functionality.

• closeIcon: An optional parameter that provides an icon to be used as the top right close button for the modal. For example, you could use a circle with an X in it, or another form of a button.

• content: An optional parameter that provides the inner content for the modal. This could be as simple as a <p/> tag to a fully fledged <form/> element.

• titleContent: An optional parameter that provides content to be situated within the title section of the modal. This could be anything from text, to a logo image, anything you want.

The Markup

The markup is pretty straightforward, there are divs for each section (title, content, and actions) along with some conditional rendering logic.

That is:

{titleContent && (
    <div className="title">
        {titleContent}
        <div className="titleCloseBtn">
            <button onClick={secondaryFn}>{closeIcon ?? 'X'}</button>
         </div>
    </div>
)}

We used the short-circuit evaluation syntax to check if the titleContent property is defined by the developer. If it is, the modal’s title is rendered; if not, the title section is omitted.

This approach allows flexible configuration of the modal, letting you easily include or exclude sections like title, content, or actions.

For example, a confirmation modal might only need a title like 'Are you sure?' and action buttons like 'Yes' or 'No', without any additional content.

React useEffect

If you’re not familiar with useEffect and plan on using React more, l’d highly recommend reading about it here, as it is one of the backbones of React’s ecosystem.

In essence, useEffect is like a helper that makes sure you do things at the right time in your app.

When Do We Use useEffect?

1. When you want something to happen right after your app is ready:

   • Example: When the app opens, and you want to fetch some data from the internet (like loading recipes for your dinner).

2. When something a state variable or input prop changes, and you want to do something after that change.

3. When your app closes or cleans up.

In our React App, we’ve created a useEffect Hook that runs after our modal component has loaded. The useEffect will simply attach a keydown event handler to the document (the page/DOM), which will listen to all keys that are pressed on the screen, and then check if it is the ESC key.

If it is the ESC key, it will call the secondaryFn function passed into the modal. In our case, this is the function that closes the modal. The return statement removes the event handler on unmount (when modalOpen is false).

How to Use the Reusable Modal

import './App.css'
import {useState} from "react";
import {Modal} from "./components/molecules/Modal";

function App() {

    const [modalOpen, setModalOpen] = useState(false);

    return (
        <div className="App">
            <h1>Hey, click on the button to open the modal.</h1>
            <button className="openModalBtn" onClick={() => setModalOpen(true)}>
                Open
            </button>

            <Modal 
                open={modalOpen}
                titleContent={<h1> Close </h1>}
                secondaryFn={() => setModalOpen(false)}
                content={
                   <>
                     <h2>This is a modal</h2>
                     <p>You can close it by pressing Escape key, pressing close, or clicking outside the modal.</p>
                  </>

               }
           />
        </div>
    );
}

export default App

Breaking It Down

In the above code, we have a button component that triggers the modal to be displayed. This is done by updating the useState variable modalOpen. Setting this to true will cause the Modal component to be seen.

Further down the code, we implemented the Modal component and passed in the relevant properties within the modal: a title, body content, and a secondary button (we didn't pass a primary function). This renders the following modal:

Using the same component, we can also mix it up and build a confirmation modal like so:

Replacing the previous modal implementation with:

<Modal
    open={modalOpen}
    titleContent={<h1> Are you sure? </h1>}
    cancelFn={() => setModalOpen(false)}
    primaryFn={() => {
        alert(" You deleted everything everything");
        setModalOpen(false);
    }}
    content={
        <>
            <h4>Do you really want to delete everything?</h4>
        </>
    }
/>

There you have it, you have a Modal component with endless possibilities and configurations, depending on what content you pass to each area of the modal.

Additional Improvements

There are some additional improvements

Replacing the Cancel and Primary Buttons

Instead of passing the cancelFn and primaryFn properties, you can pass a full component containing the buttons, or any other footer components.

The updated code should look like this:

import React, { useEffect } from 'react';
import './Modal.css';

interface Props {
    open: boolean;
    escFn: () => void;
    closeIcon?: string;
    content?: React.ReactNode;
    titleContent?: React.ReactNode;
    className?: string;
    actions?: React.ReactNode; // This will be used to pass buttons or other actions as children
}

export const Modal: React.FC<Props> = (props) => {
    const { open, closeIcon, titleContent, content, actions } = props;

    useEffect(() => {
        const handleKeyDown = (e: KeyboardEvent) => {
            if (e.key === 'Escape' && open) {

            }
        };
        document.addEventListener('keydown', handleKeyDown);
        return () => document.removeEventListener('keydown', handleKeyDown);
    }, [open]);

    if (!open) return null;

    return (
        <div className="modalBackground">
            <div className="modalContainer">
                {titleContent && (
                    <div className="title">
                        {titleContent}
                        <div className="titleCloseBtn">
                            <button>{closeIcon ?? 'X'}</button>
                        </div>
                    </div>
                )}

                <div className="body">
                    {content}
                </div>

                <div className="footer">
                    {actions && actions}
                </div>
            </div>
        </div>
    );
};

Usage:

const handleCancel = () => {
    setIsOpen(false);
};

const handleContinue = () => {
    console.log('Continue action');
};

 <Modal
    open={isOpen}
    titleContent={<h2>Confirm Action</h2>}
    content={<p>Are you sure you want to proceed?</p>}
    closeIcon="X"
    actions={
        <div className="custom-actions">
           <button onClick={handleCancel}>Cancel</button>
           <button onClick={handleContinue}>Continue</button>
        </div>
    }
/>

Here, we’re now passing the buttons as a property. You can also design the modal to pass the content as a child component, but this can get messy, as developers may see this at first glance as passing the modal content, rather than just footer elements.

There are pros and cons of doing it this way though:

Pros:

• More flexibility: Allows you to pass all kinds of elements to the footer section. For example, multiple CTA (Call To Action) buttons, links, or anything you’d like, with custom styling.

• Separation of concerns: The modal is now only responsible for rendering the container (layout, title, content, and so on). The logic of what actions (buttons) to display and their behaviours are handled by the parent component that renders the modal, which makes the modal component cleaner and more reusable.

• Improved reusability: You can pass any JSX as the actions, making it usable for a variety of cases (for example, a modal with form submission buttons or multiple options). This approach is useful when you have modals that need different sets of buttons or interactions dependent on other logic within the parent/modal component. The logic can be handled by a builder function, or within another wrapper component which houses the buttons.

Cons:

• More responsibility on the parent component: You now have to handle the buttons in each instance where you use the Modal. This might result in repetition of the button logic (like handleCancel and handleContinue) in different places if you're not careful.

• Slightly more complex usage: The previous approach allowed you to pass in cancelFn and primaryFn directly (optionally), which might be easier for the majority/simple use cases. Passing actions as children may require more setup.

• Inconsistent action layout: If you're not mindful of your code, you could end up with inconsistent button placement or styles across different instances of the modal. This can be managed by ensuring you always pass consistent markup or styles when passing actions as children, but again, it may become difficult to manage.

Conclusion

Building a reusable modal component in React offers great flexibility and reusability across your application. You can easily adapt the modal to various scenarios, whether it’s a simple confirmation modal or a more complex form submission modal.

However, it’s essential to balance between flexibility and simplicity—too much complexity might overburden the parent components with unnecessary repetition.

Overall, this approach keeps your code DRY, improves maintainability, and empowers you to create scalable UI components. By applying these practices and enhancements, you can build highly adaptable modals that cater to diverse requirements, improving both the developer experience and the final product's quality.

As always, feel free to drop me a follow or reach out on Twitter/X.