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.

That repetition doesn’t just waste time – it slows down your development and creates maintenance headaches across projects.

This guide walks you through a set of reusable, modular Unity packages you can drop into any project to speed up development. You’ll build them once as packages and install them via Git wherever you need them, instead of reimplementing the same systems every time.

The article covers four core packages:

1. com.core.initializer – Finds and initializes your game controllers at runtime (MVC-style) so startup and dependencies centralized.

2. com.core.data – Handles local (and optionally cloud) save data using MemoryPack binary serialization and a provider abstraction so you can switch or extend storage backends.

3. com.core.ui – Manages popups and full-screen UIs in a consistent way so you can show dialogs, panels, and screens without duplicating logic.

4. com.core.dotween – Wraps the DoTween tween engine as a Unity package so com.core.ui (and other packages) can reference it for animations.

In this tutorial, we’ll build all four packages step by step. The Initializer, Data, UI, and DoTween packages are all documented so you can easily follow along. All packages are also upload to github which you can find the links at the end.

Table of Contents

• What You Will Learn

• Prerequisites

• Set Up Your Development Project

• Package 1: The Initializer Package

• Package 2: The Data Package

• Package 3: The DoTween Package

• Package 4: The UI Package

• Summary

What You Will Learn

• How to create a Unity package with the Package Manager

• How to set up the package structure

• How to built a centralized initialization flow for your packages

• How to use UniTask for async initialization on Unity's main thread

• How the Data package uses IDataProvider and MemoryPack for local save/load

• How the UI package uses popups (stack) and screens (single active) with DoTween animations

Prerequisites

Before you start, make sure you have:

• Unity installed (any Long Term Support version compatible with the packages. The referenced packages target Unity 6000.3)

• Git installed

• Jetbrains Rider or Visual Studio Community installed

• Know how to use Unity game engine

• Know C# and async/await structures

You will use the Unity Package Manager to create packages, then upload and install them via Git in other projects.

Set Up Your Development Project

Create a new Unity project if you don’t already have one. We’ll use it as a playground to build and test your packages. This project (and not the packages themselves) is your development environment.

Package 1: The Initializer

The first package is com.core.initializer. It finds all your controllers, runs their async initialization before the first scene loads, and lets the rest of the game access them via a single handler.

What com.core.initializer Does

• Early initialization: Runs at RuntimeInitializeLoadType.BeforeSceneLoad, so all controllers exist and are initialized before the first scene loads.

• Central access: Stores each controller by its type and exposes them through a type-safe getter.

• Completion signaling: Exposes a static event (ControllersInitialized) and a UniTaskCompletionSource (InitializationCompleted) so you can run code only after all controllers have finished initializing.

Create the Initializer Package

To start, open Window → Package Manager (under Package Management). Then click the + button and choose Create package.

Name the package com.core.initializer (or your preferred name).

Unity creates the essential package files for you.

You can edit package.json and the assembly definition (asmdef) names to match your naming. The full set of changes is not listed here. The final package is available on GitHub (linked at the end).

Add the UniTask Dependency

Unity runs on the main thread, and C# Tasks can be problematic in that context. They don’t know about the Unity Editor's play state and keep running after exiting play mode for example. So you’ll need to handle these cases manually. For these reasons, this package uses UniTask instead of C# Tasks for async operations.

Git-based dependencies are supported at the project level but not at the package level. Add UniTask via OpenUPM by following the manual installation steps.

Add UniTask as a dependency in package.json of initializer package:

"dependencies": {
  "com.cysharp.unitask": "2.5.10"
}

Also reference UniTask in the asmdef file.

You’ll need to follow this dependency flow for the rest of the packages you create.

Implement the Package Structure

The initializer uses an MVC-like architecture. Controllers handle both initialization and game logic. You could later split initialization into services and keep business logic in controllers (for example, an MVCS-style setup). This tutorial keeps things simple and uses only controllers.

Target layout:

• Runtime/Interface/ – IController

• Runtime/Helper/ – Creator (reflection-based instance creation)

• Runtime/ – ControllerHandler (orchestrates initialization)

All controllers implement the IController interface. The Initialize method returns a UniTask so initialization can be async on the main thread.

using Cysharp.Threading.Tasks;

namespace com.core.initializer
{
    public interface IController
    {
        bool IsInitialized { get; }

        UniTask Initialize();
    }
}

Create the Creator Helper

You’ll need to find all types that implement IController, create instances of them at runtime, and also find MonoBehaviours that implement IController (since those cannot be created via reflection). The Creator class does both.

using System;
using System.Collections.Generic;
using System.Linq;
using UnityEngine;

namespace com.core.initializer
{
    public static class Creator
    {
        /// <summary>
        /// Creates instances of every type which inherits from T interface.
        /// </summary>
        public static IEnumerable<T> CreateInstancesOfType<T>(params Type[] exceptTypes)
        {
            var interfaceType = typeof(T);

            var result = AppDomain.CurrentDomain.GetAssemblies().SelectMany(x => x.GetTypes()).Where
                (
                 x => interfaceType.IsAssignableFrom(x) &&
                      !x.IsInterface                    &&
                      !x.IsAbstract                     &&
                      exceptTypes.All(type => !x.IsSubclassOf(type) && x != type)
                ).Select(Activator.CreateInstance);

            return result.Cast<T>();
        }

        public static IEnumerable<T> GetMonoControllers<T>() => UnityEngine.Object.FindObjectsByType<MonoBehaviour>(FindObjectsInactive.Include, FindObjectsSortMode.None).OfType<T>();
    }
}

Using reflection at runtime has some overhead. You can optimize this later with baking the reflection in editor and using it at runtime. For MonoBehaviours, FindObjectsByType is used here for simplicity. In a larger project, you might use a dependency injection solution such as VContainer or Reflex.

Implement the ControllerHandler

The ControllerHandler uses Creator to gather all IController instances (both reflection-created and MonoBehaviours), initializes them in order, and exposes an event and a UniTaskCompletionSource so the rest of the game can wait for startup to finish.

using System;
using System.Collections.Generic;
using System.Linq;
using Cysharp.Threading.Tasks;
using UnityEngine;

namespace com.core.initializer
{
    public class ControllerHandler
    {
        public static readonly UniTaskCompletionSource InitializationCompleted = new();

        public static event Action ControllersInitialized;

        private static Dictionary<Type, IController> _controllers = new();

        [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
        public static async void Initialize()
        {
            var controllers = Creator.CreateInstancesOfType<IController>(typeof(MonoBehaviour)).ToList();
            controllers.AddRange(Creator.GetMonoControllers<IController>());

            Debug.Log("Initializing controller");

            foreach (var controller in controllers)
            {
                Debug.Log($"<color=yellow>Initializing {controller.GetType().Name}</color>");
                await controller.Initialize();
                _controllers.Add(controller.GetType(), controller);
                Debug.Log($"<color=green>Initialized {controller.GetType().Name}</color>");
            }

            Debug.Log("<color=green>All controllers are initialized</color>");
            ControllersInitialized?.Invoke();
            InitializationCompleted?.TrySetResult();
        }

        public static T GetController<T>() where T : class, IController => _controllers[typeof(T)] as T;
    }
}

How to Test the Initializer

1. Create a class that implements IController (or a MonoBehaviour that implements it).

2. Implement Initialize() with your setup logic (you can use await and UniTask).

3. After initialization, access the controller with:
   var myController = ControllerHandler.GetController<MyController>();

You can also subscribe to ControllerHandler.ControllersInitialized or await ControllerHandler.InitializationCompleted.Task to run code after all controllers are ready.

There are some limitations here. First, it can be hard to handle dependencies between different controllers. Second, it’s easy to run into circular dependencies.

When you check the GitHub repo, a DI framework may already be implemented to address these limitations. Make sure to open an issue if you want this feature.

Package 2: The Data Package

com.core.data handles local saving with a binary serializer. The package uses MemoryPack for fast, binary serialization and defines an IDataProvider interface so you can plug in different providers (local, cloud, or hybrid).

Package dependency: com.cysharp.memorypack (version 1.10.0). Add it to your project via OpenUPM and add it to package.json and the asmdef for com.core.data.

Create a new package and name it com.core.data. Use a structure such as:

• Runtime/Interface/ – IDataProvider

• Runtime/Providers/ – LocalDataProvider

• Runtime/ – optional sample DataController (in your game assembly) that implements IController and uses an IDataProvider

All data providers use the IDataProvider interface.

using Cysharp.Threading.Tasks;

namespace com.core.data
{
    public interface IDataProvider
    {
        bool     IsInitialized { get; }
        void     Save<T>(string key, T data);
        T        Load<T>(string key, T defaultValue = default);
        bool     HasKey(string  key);
        string[] GetKeys();
        UniTask  Delete(string key);
        UniTask  DeleteAll();
    }
}

You will use UniTask in the data package as well. Add com.cysharp.unitask to package.json since both IController and IDataProvider uses it.

Here’s the DataController:

using System;
using System.Collections.Generic;
using System.Text;
using com.core.data;
using com.core.initializer;
using Cysharp.Threading.Tasks;
using UnityEngine;

namespace com.core.data
{
    public class DataController : IController
    {
        private const string PLAYER_VERSION_KEY = "player-version-key";

        private IDataProvider _provider;

        public bool IsInitialized { get; private set; }

        public UniTask Initialize()
        {
            _provider = new LocalDataProvider();
            SaveUserVersion();
            IsInitialized = true;
            return UniTask.CompletedTask;
        }

        private void SaveUserVersion()
        {
            var versionHistory = Load(PLAYER_VERSION_KEY, new List<string>());
            var sb             = new StringBuilder();
            versionHistory.ForEach(vh => sb.Append(vh + Environment.NewLine));
            Debug.Log($"[DataController] Player version history: {sb}");

            if (!versionHistory.Contains(Application.version))
            {
                Debug.Log($"[DataController] Player's current version: {Application.version}");
                versionHistory.Add(Application.version);
                Save(PLAYER_VERSION_KEY, versionHistory);
            }
        }

        public void Save<T>(string key, T data) => _provider.Save(key, data);

        public T Load<T>(string key, T defaultValue = default) => _provider.Load(key, defaultValue);

        public bool         HasKey(string key)  => _provider.HasKey(key);
        public string[]     GetKeys()           => _provider.GetKeys();
        public UniTask      Delete(string key)  => _provider.Delete(key);
        public UniTask      DeleteAll()         => _provider.DeleteAll();
        public List<string> GetVersionHistory() => Load(PLAYER_VERSION_KEY, new List<string>());
    }
}

The controller delegates all logic to LocalDataProvider, which uses MemoryPack to serialize and write bytes to a "Data" folder under Application.persistentDataPath. The controller also keeps the user's app version history, which is useful for upgrade prompts or blocking old versions.

Here’s the full implementation:

using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using Cysharp.Threading.Tasks;
using MemoryPack;
using UnityEngine;

namespace com.core.data
{
    public class LocalDataProvider : IDataProvider
    {
        private const    string StorageFolderName = "Data";
        private readonly string _storagePath;

        private static readonly UTF8Encoding KeyEncoding = new(false);

        public bool IsInitialized => true;

        public LocalDataProvider()
        {
            _storagePath = Path.Combine(Application.persistentDataPath, StorageFolderName);
            EnsureStorageDirectoryExists();
        }

        public void Save<T>(string key, T data)
        {
            if (string.IsNullOrEmpty(key)) { Debug.LogWarning("[LocalDataProvider] Save called with null or empty key."); return; }
            if (data == null) { Debug.LogWarning("[LocalDataProvider] Save called with null data."); Delete(key).Forget(); return; }
            try
            {
                byte[] bin = MemoryPackSerializer.Serialize(data);
                WriteBytes(key, bin);
            }
            catch (Exception ex) { Debug.LogError($"[LocalDataProvider] Save failed for key '{key}': {ex.Message}"); throw; }
        }

        public T Load<T>(string key, T defaultValue = default)
        {
            if (string.IsNullOrEmpty(key)) { Debug.LogWarning("[LocalDataProvider] Load called with null or empty key."); return defaultValue; }
            if (!ReadBytes(key, out byte[] bin)) return defaultValue;
            try { return MemoryPackSerializer.Deserialize<T>(bin) ?? defaultValue; }
            catch (Exception ex) { Debug.LogError($"[LocalDataProvider] Load failed for key '{key}': {ex.Message}"); return defaultValue; }
        }

        public bool HasKey(string key) => !string.IsNullOrEmpty(key) && File.Exists(GetFilePath(key));

        public UniTask Delete(string key)
        {
            if (string.IsNullOrEmpty(key)) return UniTask.CompletedTask;
            try { var filePath = GetFilePath(key); if (File.Exists(filePath)) File.Delete(filePath); }
            catch (Exception ex) { Debug.LogError($"[LocalDataProvider] Delete failed for key '{key}': {ex.Message}"); }
            return UniTask.CompletedTask;
        }

        public UniTask DeleteAll()
        {
            try
            {
                if (!Directory.Exists(_storagePath)) return UniTask.CompletedTask;
                foreach (string file in Directory.GetFiles(_storagePath))
                {
                    try { File.Delete(file); }
                    catch (Exception ex) { Debug.LogWarning($"[LocalDataProvider] Could not delete file '{file}': {ex.Message}"); }
                }
            }
            catch (Exception ex) { Debug.LogError($"[LocalDataProvider] DeleteAll failed: {ex.Message}"); }
            return UniTask.CompletedTask;
        }

        public string[] GetKeys()
        {
            if (!Directory.Exists(_storagePath)) return Array.Empty<string>();
            var keys = new List<string>();
            foreach (string file in Directory.GetFiles(_storagePath))
            {
                try { string key = DecodeKeyFromFileName(Path.GetFileName(file)); if (key != null) keys.Add(key); }
                catch { Debug.LogWarning($"[LocalDataProvider] Could not read file '{file}'."); }
            }
            return keys.ToArray();
        }

        private void EnsureStorageDirectoryExists() { if (!Directory.Exists(_storagePath)) Directory.CreateDirectory(_storagePath); }
        private void WriteBytes(string key, byte[] bin) { EnsureStorageDirectoryExists(); File.WriteAllBytes(GetFilePath(key), bin); }
        private bool ReadBytes(string key, out byte[] bin) { string filePath = GetFilePath(key); if (!File.Exists(filePath)) { bin = null; return false; } bin = File.ReadAllBytes(filePath); return true; }
        private string GetFilePath(string key) => Path.Combine(_storagePath, EncodeKeyToFileName(key));
        private static string EncodeKeyToFileName(string key) { byte[] bytes = KeyEncoding.GetBytes(key); string base64 = Convert.ToBase64String(bytes); return base64.Replace('+', '-').Replace('/', '_'); }
        private static string DecodeKeyFromFileName(string fileName) { try { string base64 = fileName.Replace('-', '+').Replace('_', '/'); return KeyEncoding.GetString(Convert.FromBase64String(base64)); } catch { return null; } }
    }
}

You can implement another IDataProvider (for example JSON via Newtonsoft or PlayerPrefs) and swap it in your DataController.

In production, you might use a local and a cloud provider and sync data based on the player's online status. The com.core.data GitHub repo may be updated with cloud saving and syncing. You can open an issue if you need that feature.

Package 3: com.core.dotween

com.core.dotween is a Unity package wrapper around DOTween (Demigiant). DoTween is a widely used, production-ready tween engine. The UI package uses it for popup show/hide animations.

DOTween is not available on OpenUPM, so you’ll typically need to download it from the Unity Asset Store and import it into your project (for example, under Assets/Plugins).

Then you’ll run the DOTween setup window(it should pop automatically after importing) and click Create ASMDEF so assembly definition files are generated and you can reference them from other packages.

Next, create a new package (for example, com.core.dotween) and move the Demigiant folder from Assets/Plugins into the package folder so that com.core.ui (or any other package) can depend on com.core.dotween via Package Manager or Git.

After that, reference com.core.dotween in com.core.ui's asmdef(You will create the UI package right after this) so you can use DG.Tweening namespace in BasePopup and other UI scripts.

com.core.dotween has no external dependencies – it only wraps the DOTween asset.

Package 4: The UI Package

com.core.ui centralizes how you show popups and full-screen UIs. It contains:

• Popups – Modal or non-modal dialogs (confirm/cancel, alerts, forms) with a consistent API so you don’t duplicate panel logic in every screen. Popups are stacked – the top one is closed first.

• Screens – Full-screen panels (for example, loading, main menu). Only one screen is active at a time, and switching a screen hides the current one and shows the new one.

Create a new package named com.core.ui with a structure such as:

• Runtime/Interface/ – IUI

• Runtime/UIs/ – BasePopup, BaseScreen

• Runtime/ – UIController, UIParent

• Runtime/Resources/UIPrefabs/ – UIParent prefab, and subfolders Popups and Screens

Add com.core.dotween, com.core.initializer, and com.cysharp.unitask as dependencies in package.json and asmdef.

Popups work like a stack: each popup is shown on top of the previous one and closed from top to bottom. Screens are single-active: only one screen is visible at a time. UIController hides the current one when you show another. UIController is the single point of contact for both screens and popups and handles stacking, caching, and background placement.

IUI Interface

Both BasePopup and BaseScreen implement IUI:

using System;
using Cysharp.Threading.Tasks;

namespace com.core.ui
{
    public interface IUI
    {
        event Action<IUI> Showed;
        event Action<IUI> Hidden;

        UniTask ShowAsync();
        UniTask HideAsync();
    }
}

IUI is a very basic interface with 2 async Show/Hide methods and 2 events to be fired upon completion of those methods.

BasePopup

BasePopup uses DoTween to animate scale on show/hide and exposes events and overridable animation methods:

using System;
using Cysharp.Threading.Tasks;
using DG.Tweening;
using UnityEngine;

namespace com.core.ui
{
    public abstract class BasePopup : MonoBehaviour, IUI
    {
        public event Action<IUI> StartedShowing;
        public event Action<IUI> Showed;
        public event Action<IUI> Hidden;

        [SerializeField] private float   openingTime  = 0.35f;
        [SerializeField] private float   closingTime  = 0.25f;
        [SerializeField] private Vector3 initialScale = new(0.75f, 0.75f, 0.75f);
        [SerializeField] private Ease   openingEase  = Ease.OutBack;
        [SerializeField] private Ease   closingEase  = Ease.InBack;

        protected virtual Tweener PlayShowAnimation(Action completedCallback) => transform.DOScale(Vector3.one, openingTime).SetEase(openingEase).SetUpdate(true).OnComplete(() => completedCallback?.Invoke());
        protected virtual Tweener PlayHideAnimation(Action completedCallback) => transform.DOScale(initialScale, closingTime).SetEase(closingEase).SetUpdate(true).OnComplete(() => completedCallback?.Invoke());

        public UniTask ShowAsync()
        {
            StartedShowing?.Invoke(this);
            transform.SetAsLastSibling();
            var utcs = new UniTaskCompletionSource();
            transform.localScale = initialScale;
            gameObject.SetActive(true);

            PlayShowAnimation(() => OnAnimationShowed(utcs));
            return utcs.Task;
        }

        public void Show() => ShowAsync().Forget();

        public UniTask HideAsync()
        {
            var utcs = new UniTaskCompletionSource();
            PlayHideAnimation(() => OnAnimationCompleted(utcs));
            return utcs.Task;
        }

        private void OnAnimationShowed(UniTaskCompletionSource utcs)
        {
            Showed?.Invoke(this);
            utcs.TrySetResult();
        }

        private void OnAnimationCompleted(UniTaskCompletionSource utcs)
        {
            transform.SetAsFirstSibling();
            gameObject.SetActive(false);
            Hidden?.Invoke(this);
            utcs.TrySetResult();
        }

        public void Hide() => HideAsync().Forget();
    }
}

You can see that DoTween is the core component in this class and a lot of parameters are configurable like opening/closing times and easings. Notice how DoTween completion callbacks are utilized to fire Showed and Hidden events.

Another important thing here is the usage of SetUpdate(true) for animations. This makes animations to ignore timescale. I found that most of the time it's best to ignore the timescale for animations but if you don't want this then feel free to change it.

BaseScreen

BaseScreen only enables/disables the GameObject and raises events. There’s no animation:

using System;
using Cysharp.Threading.Tasks;
using UnityEngine;

namespace com.core.ui
{
    public abstract class BaseScreen : MonoBehaviour, IUI
    {
        public event Action<IUI> Showed;
        public event Action<IUI> Hidden;

        public virtual UniTask ShowAsync()
        {
            gameObject.SetActive(true);
            Showed?.Invoke(this);
            return UniTask.CompletedTask;
        }

        public UniTask HideAsync()
        {
            gameObject.SetActive(false);
            Hidden?.Invoke(this);
            return UniTask.CompletedTask;
        }
    }
}

You will notice that BaseScreen doesn't need UniTask since it is not performing any async operations but it is still beneficial to have this since it doesn't cause any overheads and if we ever need an animation for any of our screens like popups, we have it ready.

UIController

UIController implements IController, instantiates UIParent from Resources, and provides APIs to push/pop popups and show/hide screens. It caches popup and screen instances by type and loads prefabs from Resources:

• UIParent: Resources/UIPrefabs/UIParent

• Popups: Resources/UIPrefabs/Popups/<TypeName>.prefab

• Screens: Resources/UIPrefabs/Screens/<TypeName>.prefab

using System;
using System.Collections.Generic;
using com.core.initializer;
using Cysharp.Threading.Tasks;
using UnityEngine;
using Object = UnityEngine.Object;

namespace com.core.ui
{
    public class UIController : IController
    {
        private const string UI_PARENT_PATH    = "UIPrefabs/UIParent";
        private const string POPUPS_RESOURCES  = "UIPrefabs/Popups";
        private const string SCREENS_RESOURCES = "UIPrefabs/Screens";

        private readonly Stack<BasePopup>             _popupStack  = new();
        private readonly Dictionary<Type, BasePopup>  _popupCache  = new();
        private readonly Dictionary<Type, BaseScreen> _ScreenCache = new();

        private BaseScreen _currentScreen;
        private UIParent   _uiParent;

        public bool IsInitialized { get; private set; }

        public UniTask Initialize()
        {
            var uiParentPrefab = Resources.Load<UIParent>(UI_PARENT_PATH);
            if (uiParentPrefab == null)
            {
                Debug.LogError($"[UIController] UIParent prefab not found at {UI_PARENT_PATH}. Ensure it exists in a Resources folder.");
                return UniTask.CompletedTask;
            }

            _uiParent      = Object.Instantiate(uiParentPrefab);
            _uiParent.name = "UIParent";

            Object.DontDestroyOnLoad(_uiParent.gameObject);

            IsInitialized = true;
            return UniTask.CompletedTask;
        }

        public async UniTask<TPopup> PushPopupAsync<TPopup>() where TPopup : BasePopup
        {
            var popup = GetOrCreatePopup<TPopup>();
            _popupStack.Push(popup);
            var popupTask = popup.ShowAsync();
            UpdateBackgroundForTopPopup();
            await popupTask;
            return popup;
        }

        public void PushPopup<TPopup>() where TPopup : BasePopup => PushPopupAsync<TPopup>().Forget();

        public async UniTask PopPopupAsync()
        {
            if (_popupStack.Count == 0)
            {
                Debug.LogWarning("[UIController] PopPopup called but popup stack is empty.");
                return;
            }

            var top = _popupStack.Pop();
            await top.HideAsync();
            UpdateBackgroundForTopPopup();
        }

        public void PopPopup() => PopPopupAsync().Forget();

        public BasePopup PeekPopup() => _popupStack.Count > 0 ? _popupStack.Peek() : null;

        public async UniTask<TScreen> ShowScreenAsync<TScreen>() where TScreen : BaseScreen
        {
            var screen = GetOrCreateScreen<TScreen>();

            if (_currentScreen == screen && screen.gameObject.activeSelf) return screen;
            if (_currentScreen != null   && _currentScreen != screen && _currentScreen.gameObject.activeSelf) await _currentScreen.HideAsync();

            _currentScreen = screen;
            await screen.ShowAsync();
            return screen;
        }

        public async UniTask HideScreenAsync<TScreen>() where TScreen : BaseScreen
        {
            var type = typeof(TScreen);
            if (!_ScreenCache.TryGetValue(type, out var screen))
            {
                Debug.LogWarning($"[UIController] HideScreenAsync<{type.Name}> called but Screen was never shown (not in cache).");
                return;
            }

            await screen.HideAsync();

            if (_currentScreen == screen) _currentScreen = null;
        }

        public void ShowScreen<TScreen>() where TScreen : BaseScreen => ShowScreenAsync<TScreen>().Forget();
        public void HideScreen<TScreen>() where TScreen : BaseScreen => HideScreenAsync<TScreen>().Forget();

        private TPopup GetOrCreatePopup<TPopup>() where TPopup : BasePopup
        {
            var type = typeof(TPopup);
            if (_popupCache.TryGetValue(type, out var cached) && cached != null) return (TPopup)cached;

            var prefab = LoadPopupPrefab<TPopup>();
            if (prefab == null)
            {
                Debug.LogError($"[UIController] Popup prefab for {type.Name} not found at {POPUPS_RESOURCES}/{type.Name}. Ensure the prefab exists in a Resources folder.");
                return null;
            }

            var instance = UnityEngine.Object.Instantiate(prefab, _uiParent.PopupParent);
            instance.gameObject.SetActive(false);

            var popup = instance.GetComponent<TPopup>();
            _popupCache[type] = popup;

            return popup;
        }

        private TScreen GetOrCreateScreen<TScreen>() where TScreen : BaseScreen
        {
            var type = typeof(TScreen);
            if (_ScreenCache.TryGetValue(type, out var cached) && cached != null) return (TScreen)cached;

            var prefab = LoadScreenPrefab<TScreen>();
            if (prefab == null)
            {
                Debug.LogError($"[UIController] Screen prefab for {type.Name} not found at {SCREENS_RESOURCES}/{type.Name}. Ensure the prefab exists in a Resources folder.");
                return null;
            }

            var instance = UnityEngine.Object.Instantiate(prefab, _uiParent.ScreenParent);
            instance.gameObject.SetActive(false);

            var screen = instance.GetComponent<TScreen>();
            _ScreenCache[type] = screen;

            return screen;
        }

        private TPopup  LoadPopupPrefab<TPopup>() where TPopup : BasePopup     => LoadViewPrefab<TPopup>(POPUPS_RESOURCES);
        private TScreen LoadScreenPrefab<TScreen>() where TScreen : BaseScreen => LoadViewPrefab<TScreen>(SCREENS_RESOURCES);

        private static T LoadViewPrefab<T>(string resourcesPath) where T : MonoBehaviour
        {
            var type = typeof(T);
            var path = $"{resourcesPath}/{type.Name}";
            var go   = Resources.Load<GameObject>(path);
            return go != null ? go.GetComponent<T>() : null;
        }

        private void UpdateBackgroundForTopPopup()
        {
            var backgroundGO = _uiParent.BackgroundGO;
            if (backgroundGO == null) return;

            if (_popupStack.Count > 0)
            {
                var topPopup = _popupStack.Peek();
                if (topPopup != null && topPopup.gameObject.activeSelf)
                {
                    // Position background one step behind the top popup
                    var topPopupIndex = topPopup.transform.GetSiblingIndex();
                    backgroundGO.SetActive(true);
                    backgroundGO.transform.SetSiblingIndex(Mathf.Max(0, topPopupIndex - 1));
                }
                else
                {
                    // Top popup is inactive, hide background
                    backgroundGO.SetActive(false);
                }
            }
            else
            {
                // No popups in stack, hide background
                backgroundGO.SetActive(false);
            }
        }
    }
}

Usage:

var ui = ControllerHandler.GetController<UIController>();
await ui.PushPopupAsync<MyPopup>();
await ui.PopPopupAsync();
await ui.ShowScreenAsync<MainMenuScreen>();
await ui.HideScreenAsync<LoadingScreen>();

UIController also updates the background GameObject so it indexes behind the top popup.

It uses GetOrCreatePopup<TPopup>() / GetOrCreateScreen<TScreen>() to load and cache prefabs from Resources/UIPrefabs/Popups/<TypeName> and Resources/UIPrefabs/Screens/<TypeName>, pushes popups onto a stack, and shows/hides screens with async methods.

UIParent is a MonoBehaviour that holds references to ScreenParent, PopupParent, and BackgroundGO:

using UnityEngine;

namespace com.core.ui
{
    public class UIParent : MonoBehaviour
    {
        [SerializeField] private Transform  screensParent;
        [SerializeField] private Transform  popupsParent;
        [SerializeField] private GameObject backgroundGO;

        public Transform  ScreenParent => screensParent;
        public Transform  PopupParent  => popupsParent;
        public GameObject BackgroundGO => backgroundGO;
    }
}

UIParent prefab has a canvas and UIParent script attached:

There are a couple limitations here as well. First, popups and screens must live under Resources/UIPrefabs/Popups and Resources/UIPrefabs/Screens. Second, prefab name must match the script/type name (for example, TestPopup prefab name for a script named TestPopup).

Summary

In this article, you set up a Unity project and walked through creating four reusable packages:

• com.core.initializer – You created the package, added UniTask, defined IController, used the Creator helper to find and create controllers (including MonoBehaviours), and implemented ControllerHandler to run initialization at BeforeSceneLoad and expose controllers via GetController<T>().

• com.core.data – You use IDataProvider and LocalDataProvider with MemoryPack for binary local save/load, and the DataController that implements IController and tracks version history.

• com.core.dotween – You wrap the DoTween asset as a package so other packages (like com.core.ui) can reference it for animations.

• com.core.ui – You created a modular UI package that you can use in your games to handle popups and full size screens. You can also extend this to add other UI types in the future.

Building these as separate packages keeps your code modular and speeds up development across projects. You can install each package via Git into any Unity project.

Example manifest.json file to implement these packages:

{
  "dependencies"    : {
	"com.core.data"       : "https://github.com/TalhaCagatay/com.core.data.git#v0.1.0",
	"com.core.initializer": "https://github.com/TalhaCagatay/com.core.initializer.git#v0.1.0",
	"com.core.dotween"    : "https://github.com/TalhaCagatay/com.core.dotween.git#v0.1.0",
	"com.core.ui"         : "https://github.com/TalhaCagatay/com.core.ui.git#v0.1.0"
  },
  "scopedRegistries": [
	{
	  "name"  : "package.openupm.com",
	  "url"   : "https://package.openupm.com",
	  "scopes": [
		"com.cysharp.unitask",
		"com.cysharp.memorypack"
	  ]
	}
  ]
}

Resources:

• com.core.initializer on GitHub

• com.core.data on GitHub

• com.core.dotween on Github

• com.core.ui on Github

• Example game that I developed and used many modular systems like the ones you built in this article.

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.

We just posted a full course on the freeCodeCamp YouTube channel that will teach you to build scaleable cloud applications. Muhammad Abdullah developed this course.

This hands-on course takes you from fundamental concepts to production-ready implementations, covering everything from Azure Functions and Docker containers to advanced orchestration with Kubernetes and .NET Aspire.

Here are the sections in this course:

• What is Serverless?

• Understanding Serverless Architecture

• Microservices Types & Patterns Explained

• Onion Architecture Explained

• Docker Demystified

• Azure Functions and Triggers

• Background Functions in Azure

• IoT Functions

• Microservices in Practice - Route Planning

• Introduction to Kubernetes

Watch the full course on the freeCodeCamp.org YouTube channel (5-hour watch).

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.

But they serve different purposes, feel different to write, and open up different types of job opportunities.

This article will help you understand what each language is, what they’re good at, and how they compare in real-world use cases.

Table of Contents

• What Is JavaScript?

• What Is C#?

• Performance

• Community and Support

• Ease of Learning

• Career Opportunities

• Final Thoughts

What Is JavaScript?

JavaScript is the language of the web. It runs in your browser and powers everything from simple websites to complex web apps. Want to make a button do something when clicked? That’s JavaScript. Want to load data without reloading the page? JavaScript again.

But here’s the cool part, JavaScript isn’t just for the front end anymore. With Node.js, it can run on servers too. This means JavaScript is now used to build entire applications, front to back. You can build APIs, handle databases, run background jobs, and more, all with the same language.

This makes JavaScript beginner-friendly. You can write your first script in a browser and still use the same language to build large systems. It’s fast to start, and you’ll find lots of resources and jobs if you go down this path.

What Is C#?

C# (pronounced “C sharp”) is a language built by Microsoft. It’s often used in combination with the .NET framework to create desktop apps, web services, and enterprise software. If a business runs a Windows-based software, chances are that it’s built with C#.

C# is also a top choice for game development, thanks to its strong connection with Unity, one of the most popular game engines in the world.

Unlike JavaScript, C# is statically typed. This means you need to define your variables clearly and follow more rules. That sounds like a lot at first, but it actually helps you catch errors early and keep big projects neat and tidy.

Now that you know what JavaScript and C# are, let’s compare them across five key areas.

Performance

C# usually performs better than JavaScript, especially when dealing with heavy workloads or tasks that demand a lot from the processor. This advantage comes from the fact that C# is a compiled language.

When you run a C# program, the code is first converted into an intermediate language and then compiled into machine code that your computer’s processor can execute directly. This compilation step removes much of the overhead that comes with interpreting code on the fly.

The result is faster execution and more efficient memory usage, which makes C# ideal for scenarios like handling large files, running complex mathematical calculations, or powering game engines where every millisecond counts.

JavaScript works differently. It’s an interpreted language, which means the code runs line by line in a runtime environment like a web browser or Node.js. Instead of being compiled to machine code ahead of time, the JavaScript engine reads and executes the code as it runs.

This approach offers flexibility and makes it easy to develop and deploy scripts quickly, which is a big reason why JavaScript dominates web development. But because it doesn’t have the same direct link to the machine as compiled languages do, it can struggle in situations that require extremely high performance, like processing massive datasets, rendering complex graphics, or building high-frequency trading systems.

However, modern JavaScript engines have come a long way. Engines like V8, which powers Chrome and Node.js, use Just-In-Time (JIT) compilation to optimize code while it’s running. They can identify patterns and compile parts of the code into machine instructions on the fly, dramatically improving speed compared to older interpreters.

This means that for most everyday web applications, the difference in performance between JavaScript and C# won’t be noticeable. Web dashboards, e-commerce sites, and typical server-side APIs run perfectly fine in JavaScript. But if your project involves raw computational power, game graphics, or real-time simulations, C# will still give you a clear edge.

Community and Support

JavaScript has one of the largest and most active developer communities in the world. Since it's used in almost every corner of the tech world, from websites and browsers to mobile apps and even desktop apps, it has become a go-to language for millions of developers.

That popularity means you’re never alone when learning or building with JavaScript. Whatever problem you run into, chances are that someone else has already faced it and posted about it online. Whether you prefer watching YouTube tutorials, reading blog posts, browsing GitHub repositories, or asking questions on Stack Overflow, you’ll find an overwhelming amount of help and resources to guide you.

C# also has a strong and dedicated community, though it’s more concentrated in the enterprise and professional development space. Backed by Microsoft, C# is consistently updated, well-documented, and deeply integrated with tools like Visual Studio and the .NET ecosystem.

You’ll find a wealth of high-quality documentation, official guides, and forums where professionals share their knowledge. While it might not generate the same buzz as JavaScript in startup circles or web-first communities, C# has a long-standing presence in large-scale systems, corporate software, game development (especially with Unity), and Windows applications. In those environments, it’s not uncommon to find teams of seasoned developers with years of experience in C#.

In short, both languages enjoy excellent support. JavaScript might feel more beginner-friendly due to its widespread usage and endless online tutorials, making it easy to pick up quickly. C#, on the other hand, shines in more structured, professional settings where stability, performance, and long-term maintainability are key. It may not have the same trendy reputation, but within its ecosystem, it’s trusted, respected, and well-loved.

Ease of Learning

JavaScript is one of the easiest languages to start with because it requires almost no setup. You can open your browser, type a few lines of code in the console, and immediately see the results.

This instant feedback loop makes learning feel exciting and interactive, especially for beginners who want to experiment and see quick outcomes. You can start small, tweak your code, and watch it come to life without installing tools, setting up projects, or even leaving the browser. This low barrier to entry is one of the biggest reasons JavaScript has become the go-to language for people taking their very first steps in programming.

But this simplicity comes with quirks. JavaScript is a very flexible language, which is both a blessing and a curse. It often lets you write code that “just works,” even if it isn’t the best approach. While this makes it forgiving in the early stages, it can also lead to confusing bugs down the line.

Small mistakes might not throw errors immediately, and behavior can change in unexpected ways. Anyone who has wrestled with tricky type conversions knows that JavaScript’s freedom can sometimes backfire. This flexibility demands that you develop discipline on your own if you want to avoid messy, hard-to-maintain code.

C#, on the other hand, feels more structured from the start. It enforces rules like defining types, organizing code into classes, and following a clear syntax. This can feel strict and even a little intimidating at first because you can’t just write anything and hope it works.

The compiler checks your code before it runs and points out mistakes early, which can be frustrating as a beginner. But this structure pays off as your projects grow. The rules and strong typing help you catch errors before they become serious problems, guide you toward better programming habits, and make large, complex codebases easier to manage. Once you get used to its style, C# actually makes programming feel more predictable and less error-prone.

In simple terms, JavaScript gives you the quickest path to start coding and see results, which is perfect for learning and experimenting. C# takes longer to warm up to, but it rewards that effort with cleaner, safer, and more maintainable projects as they grow in size and complexity.

Career Opportunities

Learning JavaScript unlocks a wide range of career opportunities because it powers so much of the modern digital world.

Starting with front-end development, you can build interactive websites and web applications that run in the browser using frameworks like React, Vue, or Angular. If you want to go deeper, Node.js allows you to use JavaScript for back-end development as well, which means you can handle server logic, databases, and APIs without ever switching languages.

This flexibility makes full-stack roles especially accessible to JavaScript developers, since you can manage both the front-end and back-end with a single skillset. On top of that, JavaScript extends into mobile app development with tools like React Native and Ionic, letting you build apps for both iOS and Android.

Because nearly every business needs a website or web application, the demand for JavaScript developers is both high and consistent, making it a strong career path for anyone entering the tech industry.

C# leads to a slightly different set of roles, often tied to enterprise or specialized development. It is heavily used in backend systems that run on the .NET ecosystem, where reliability and performance are critical. Many large companies rely on C# for internal tools, financial applications, and large-scale software products that power their core operations.

One of the most exciting areas for C# developers is game development, thanks to its deep integration with Unity, the most popular game engine in the world. From indie studios to major game companies, Unity uses C# as its primary scripting language, opening the door to careers in the gaming industry. Additionally, C# is a natural fit for building Windows desktop applications and enterprise-level cloud solutions, especially within companies already invested in Microsoft technologies.

Both languages can lead to solid salaries and stable careers, but the paths they open are different. JavaScript thrives in web and mobile-focused roles with a steady demand across startups, agencies, and tech companies of all sizes. C# excels in enterprise, backend, and game development, where the projects are often larger, more complex, and built for long-term reliability. Choosing between them really comes down to the type of work that excites you most and the industry you want to grow in.

Final Thoughts

JavaScript and C# are both modern, useful, and in demand. JavaScript is light, fast, and flexible, perfect for websites and small-to-large web apps. C# is powerful, structured, and ideal for Windows apps, enterprise systems, and games.

If you're new to coding and want to see results fast, start with JavaScript. If you're interested in game dev or building strong business apps, try C#.

You don’t have to choose forever. Many developers learn both. Start with one, explore the other later, and you’ll become a well-rounded coder ready for anything.

Join my newsletter for a summary of my articles every Friday. You can also connect with me on Linkedin.

Whether you are onboarding 50 new hires or rolling out access to a new app, managing roles by hand can be tedious and error-prone.

In this article, you will learn about three scalable ways to assign security roles across multiple users or teams, with low-code and pro-code options.

Table of Contents

1. Aside: Teams

2. Canvas Apps Relate / Unrelate Functions

3. Power Automate with the Relate Rows in Dataverse Action

4. C# Console App: Using the Dataverse SDK

5. Final Thoughts

Aside: Teams

Teams are the simplest way to assign roles to multiple users.

Dataverse admins and team owners can add users to one or more teams. Rather than assigning roles to individual users, the security role is assigned to the team.

But there are caveats: record ownership and team management can introduce their own complexity. In environments with many teams, updating security roles can become just as tedious as assigning them individually.

This article focuses on programmatic individual assignments, but keep in mind that all three methods described below can be adapted to work with teams as well.

Canvas Apps Relate / Unrelate Functions

Canvas app developers can use Power FX to assign security roles across users or teams. Minimal code is required, and the result can serve as a lightweight security role management portal.

While not ideal for massive batches, this approach is suitable for assigning roles to a few hundred users.

ForAll(
    colSelectedUsers As User,
    Relate(
        User.'Security Roles (systemuserroles_association)',
        cbx_securityRoles.Selected
    )
)

Here:

• colSelectedUsers is a collection of users.

• cbx_securityRoles is a Combobox control holding the security role to assign.

The Relate function connects each user with the selected security role. The first parameter is the many-to-many relationship (systemuserroles_association) between systemuser and role.

To find relationship names, open the User table > Relationships. Then, look for many-to-many connections to the role table.

The security role/user relationship is a many-to-many relationship.

Power Automate with the Relate Rows in Dataverse Action

The Relate Rows in Dataverse action allows you to assign roles dynamically in cloud flows.

How it works:

• Trigger a flow (for example, manually or via Dataverse trigger).

• Fetch a list of users based on a condition.

• Loop through each user with Apply to Each.

• Assign a static or dynamic security role.

C# Console App: Using the Dataverse SDK

This method offers maximum control and supports complex, high-scale role assignments – but it requires pro-code skills.

Example:

This console app:

1. Connects to the environment via client credentials.

2. Retrieves all users with the title "Salesperson"

3. Builds a batch of associate requests.

4. Executes the batch transactionally – if one fails, all fail.

using Microsoft.PowerPlatform.Dataverse.Client;
using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Messages;
using Microsoft.Xrm.Sdk.Query;

class Program
{
    static void Main(string[] args)
    {
        string dataverseUrl = "https://your-org.crm.dynamics.com";
        string clientId     = "client-id-here";
        string clientSecret = "client-secret-here";
        string tenantId     = "tenant-id-here";

        string connectionString = $@"
            AuthType=ClientSecret;
            Url={dataverseUrl};
            ClientId={clientId};
            ClientSecret={clientSecret};
            TenantId={tenantId};
        ";
        // Connect to our environment
        using var serviceClient = new ServiceClient(connectionString);

        if (!serviceClient.IsReady)
        {
            Console.WriteLine("Failed to connect.");
            return;
        }

        // Fetch a list of users that we intend to associate a role with
        var query = new QueryExpression("systemuser")
        {
            ColumnSet = new ColumnSet("systemuserid"),
            Criteria = new FilterExpression
            {
                Conditions =
                {
                     new ConditionExpression(
                        "title",
                        ConditionOperator.Equal,
                        "Salesperson"
                     ),
                }
            }
        };

        var users = serviceClient.RetrieveMultiple(query);

        // Role to assign (pretend guid for demo purposes)
        var securityRoleId = new Guid(
            "00000000-0000-0000-0000-000000000ABC"
        );

        // Prepare our transaction
        var transaction = new ExecuteTransactionRequest
        {
            ReturnResponses = true,
            Requests = new OrganizationRequestCollection()
        };

        // For each user we fetched above, we add an associate request 
        // to the transaction
        foreach (var user in users.Entities)
        {
            var userId = (Guid)user["systemuserid"];

            var relationship = new Relationship(
                "systemuserroles_association"
            );

            var relatedReferences = new EntityReferenceCollection
            {
                new EntityReference(
                    "role",
                    securityRoleId
                )
            };
            // build the associate request
            var request = new AssociateRequest
            {
                Target = new EntityReference(
                    "systemuser",
                    userId
                ),
                RelatedEntities = relatedReferences,
                Relationship = relationship
            };
            // add the request to the transaction
            transaction.Requests.Add(request);
        }

        // Finally, execute the batch as a transaction
        serviceClient.Execute(transaction);
    }
}

You can even utilize this logic within a Custom API, allowing Power Automate or Canvas Apps to call it, blending low-code and pro-code capabilities.

Final Thoughts

If your teams are already well-structured and manageable in number, teams remain the easiest way to assign roles at scale.

But when teams aren't feasible – or when assigning directly to users is required – each method we discussed here offers a viable alternative:

• Use Canvas Apps for lightweight, user-facing management portals

• Use Power Automate when complexity is low and there is a need to trigger it in a variety of ways.

• Use C# and the Dataverse SDK for full control and batch efficiency.

Ready to automate your role assignments? Start small – build a simple Power App or Flow – and scale your approach from there.

Found this helpful? I write about practical automation, productivity systems, and building smarter workflows — without the jargon. Visit me at brandonwoz.com.

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! 😊

Different types of classes serve various purposes. For instance, organizing your logic to make your code easier to navigate is helpful when building an application.

You can group or separate your code into classes, and through inheritance, you can utilize different classes as needed. Classes help encapsulate your code, enabling you to reuse your logic in other application parts. Classes have many functionalities, and we will explore some of them in detail.

In this guide, we'll explore various types of classes in C# and how you can use them to create efficient and maintainable code.

Prerequisites

Before we proceed, you should have the following:

1. Basic knowledge of C#: you should understand C# syntax and basic programming constructs like variables, loops, and conditionals.

2. Familiarity with Object-Oriented Programming (OOP) concepts: you should know how to work with classes, objects, inheritance, polymorphism, encapsulation, and abstraction.

3. Familiarity with access modifiers: you should understand public, private, internal, and protected access modifiers.

4. Experience with C# IDE/Environment: you should be able to write and run C# programs using an IDE like Visual Studio.

If you want to learn more about C#, you can check out my YouTube channel: CliffTech.

Table of Contents

• Static Classes in C Sharp

• Sealed Classes in C Sharp

• Concrete Classes in C Sharp

• Abstract Classes in C Sharp

• Singleton Classes in C Sharp

• Generic Classes in C Sharp

• Internal Classes in C Sharp

• Nested Classes in C Sharp

• Partial Classes in C Sharp

• Conclusion

The first type of class we’ll discuss is the Static Class. Let’s dive in.

Static Classes in C Sharp

Static classes are a special type of class in C# designed to provide a collection of related utility methods and properties that do not rely on instance data.

Static classes in C# are a unique type of class designed to house a collection of related utility methods and properties that don't depend on instance data.

Unlike regular classes, static classes cannot be instantiated, and they exclusively contain static members. This characteristic means they cannot be inherited, making them perfect for organizing stateless methods that don't require the features of object-oriented programming.

In essence, when we refer to stateless grouping, it implies that there's no need to create an instance to call a static method – you can simply use the class or method name directly. This approach provides a clear and efficient way to manage utility functions, enhancing code organization and accessibility.

Example of a Static Class in C

Here's an example of a static class in C#:

namespace StaticClasses
{
// Define a static class
    public static class MathUtils
    {
        // Static method to add two numbers
        public static int Add(int a, int b)
        {
            return a + b;
        }

        // Static method to subtract two numbers
        public static int Subtract(int a, int b)
        {
            return a - b;
        }

       // Static method to multiply two numbers
        public static int Multiply(int a, int b)
        {
            return a * b;
        }
    }
}

In this example:

• The MathUtils class is defined as static, meaning it cannot be instantiated.

• It contains three static methods: Add, Subtract, and Multiply.

• These methods can be called directly on the MathUtils class without creating an instance.

Before you can use this, you need to call it in your Program.cs. When you create any C# application, the entry point is Program.cs. You’ll need to go there and make sure to call these classes so that you can execute them. This is what we will be doing for the rest of the section.

How to Use Static Methods in Program.cs

Now you can use the static methods defined in the MathUtils class as follows:

 // program.cs
namespace StaticClasses
{
    class Program
    {
        static void Main(string[] args)
        {
             // Call static methods from the MathUtils class
            int sum = MathUtils.Add(5, 3);
            // Call the static method Subtract from the MathUtils class
            int difference = MathUtils.Subtract(5, 3);

            // Call the static method Multiply from the MathUtils class
            int product = MathUtils.Multiply(5, 3);

            // Display the results of the sum method
            Console.WriteLine($"Sum: {sum}"); // Output: 8
            // Display the results of the difference method
            Console.WriteLine($"Difference: {difference}"); // Output: 2
            // Display the results of the product method
            Console.WriteLine($"Product: {product}");  // Output: 15
        }
    }
}

When to Use Statice Classes vs Methods

To decide when to use static classes or methods in C#, consider the following guidelines:

1. Use Static Classes when:

   • You need a collection of utility or helper methods that do not require any instance data.

   • The methods and properties are stateless and can be accessed globally without creating an object.

   • You want to group related functions that are not tied to a specific object state.

   • You need to ensure that the class cannot be instantiated or inherited.

2. Use Static Methods when:

   • You have a class that is mostly instance-based, but you need a few methods that do not depend on instance data.

   • The method performs a task that is independent of any object state and can be executed without an instance.

   • You want to provide a utility function within a class that can be accessed without creating an object of that class.

By using static classes and methods appropriately, you can enhance code organization, improve performance by avoiding unnecessary object creation, and ensure that certain functionalities are easily accessible throughout your application.

Key Points to Remember About Static Classes in C

• Cannot be Instantiated: You cannot create objects from a static class.

• Only static members: Static classes can only have static members. They do not support instance methods or fields.

• Sealed by default: Static classes are automatically sealed, so they cannot be inherited.

• Utility and helper methods: Static classes are usually used to group related utility or helper methods that don't need an object state.

Static classes help organize and access utility methods and properties clearly and simply, making them important for creating efficient and maintainable code.

Sealed Classes in C Sharp

Sealed classes are a special type of class in C# that cannot be inherited. You can use them to prevent other classes from deriving from them, which can be useful for creating immutable types or ensuring that a class's behavior remains unchanged.

By sealing a class, you ensure that it cannot be modified or extended, making it useful for scenarios where you want to provide a specific implementation without allowing further alterations.

Example of a Sealed Class in C

Here's an example of a sealed class in C#:

namespace SealedClasses
{

    // Define an abstract class
    public abstract class Shape
    {
        // Abstract method to calculate the area
        public abstract double CalculateArea();
    }

     // Define a sealed class
    public sealed class Rectangle : Shape
    {

        //  Properties
        public double Width { get; }
        public double Height { get; }

        // Constructor
        public Rectangle(double width, double height)
        {
            Width = width;
            Height = height;
        }

       // Implement the CalculateArea method
        public override double CalculateArea()
        {
            return Width * Height;
        }
    }
}

In this example:

• The Shape class is an abstract base class with an abstract method CalculateArea().

• The Rectangle class inherits from Shape and provides an implementation for CalculateArea().

• The Rectangle class is sealed, which means it cannot be inherited from. This ensures that the class's implementation cannot be modified or extended.

How to Use the Sealed Rectangle Class in the Program.cs

Here's how you can use the Rectangle class in a Program.cs file:

namespace SealedClasses
{
    class Program
    {
        static void Main(string[] args)
        {
            Rectangle rectangle = new Rectangle(5, 3);
            double area = rectangle.CalculateArea();

            Console.WriteLine($"Area of the rectangle: {area}"); // Output: Area of the rectangle: 15
        }
    }
}

In this example, the Rectangle class is sealed to ensure that its behavior cannot be changed through inheritance. This guarantees that the Rectangle class's implementation of CalculateArea() stays the same, which helps maintain consistent behavior.

When to Use Sealed Classes

Sealed classes are particularly useful in the following contexts:

1. Framework development: When developing frameworks or libraries, you might use sealed classes to lock down certain classes that are not intended to be extended by users. This helps maintain control over the framework's behavior and ensures that users cannot introduce bugs or inconsistencies by extending these classes.

2. Preventing inheritance: If a class is designed to be a specific implementation with no need for further customization or extension, sealing it prevents other developers from creating subclasses that might alter its intended functionality.

3. Finalizing class design: When a class has reached a point where its design is considered complete and no further changes or extensions are anticipated, sealing it can signal to other developers that the class should be used as-is.

4. Avoiding overriding: In scenarios where overriding methods could lead to incorrect behavior or security issues, sealing the class ensures that its methods cannot be overridden, preserving the original logic and functionality.

Key Points to Remember About Sealed Classes

• No inheritance: Sealed classes cannot be inherited, ensuring their behavior stays the same.

• Prevent modification: They prevent further inheritance, avoiding accidental changes or extensions.

• Immutable and specific: Sealed classes are useful for creating immutable classes or when you need a specific, unchangeable implementation.

Sealed Classes vs. Static Classes

You might wonder why we need sealed classes if static classes are already sealed. The key differences are:

• Static Classes are sealed and cannot be instantiated. They are used for grouping static methods and properties.

• Sealed Classes can be instantiated but cannot be inherited. This allows for creating objects that are protected from further subclassing.

Sealed classes offer flexibility in creating classes that can be used directly without the risk of modification through inheritance.

Concrete Classes in C Sharp

Concrete classes are essential in object-oriented programming in C#. They are fully implemented classes that you can use to create objects directly.

Unlike abstract classes or interfaces, concrete classes have complete implementations of all their methods and properties, making them versatile and fundamental to most C# applications.

A concrete class is not abstract. It includes full implementations of all its members—methods, properties, fields, and so on—and can be used to create objects. These classes represent real-world entities or concepts in your application, encapsulating both data (stored in fields or properties) and behavior (defined by methods).

Example: Defining a Concrete Class in C

Here's a simple example of a concrete class in C#:

// Define a concrete class
public class Animal
{
    public void Speak()
    {
        Console.WriteLine("The animal makes a sound.");
    }
}

// Define a derived class that inherits from the Animal class
public class Dog : Animal
{
    public void Bark()
    {
        Console.WriteLine("The dog barks.");
    }
}

In this example, the Animal class is a concrete class with a method Speak that represents a generic sound made by any animal. The Dog class inherits from Animal and adds a Bark method to represent a sound specific to dogs. Both Animal and Dog are concrete classes because they can be instantiated and used to create objects.

How to Instantiate and Use Concrete Classes

Here's how you can use the Dog class in a Program.cs file:

// program.cs
class Program
{
    static void Main(string[] args)
    {
        // Create an instance of the Dog class
        Dog myDog = new Dog();

        // Call the inherited method
        myDog.Speak(); // Output: The animal makes a sound.

        // Call the method defined in the Dog class
        myDog.Bark();  // Output: The dog barks.
    }
}

In this example, we create an instance of the Dog class called myDog. We first call the Speak method, which is inherited from the Animal class, and then the Bark method from the Dog class. This shows how concrete classes can include both inherited and unique behaviors.

Real-World Example: Concrete Class for a Product

To illustrate the practical application of concrete classes, consider the following example of a Product class:

// Define a concrete class for a product
public class Product
{
    // Data properties
    public string Name { get; set; }
    public decimal Price { get; set; }

    // Method to display product information
    public void DisplayInfo()
    {
        Console.WriteLine($"Product: {Name}, Price: {Price:C}");
    }
}

This Product class is a concrete class with properties Name and Price to store information about a product. The DisplayInfo method provides a way to display the product’s details.

How to Use the Product Class

Here's how you can use the Product class:

class Program
{
    static void Main(string[] args)
    {
        // Create an instance of the Product class
        Product product = new Product
        {
            Name = "Laptop",
            Price = 1299.99m
        };

        // Display product information
        product.DisplayInfo(); // Output: Product: Laptop, Price: $1,299.99
    }
}

In this scenario, the Product class is used to create a product object. The DisplayInfo method is called to show the product's name and price. This demonstrates how concrete classes are used to model and work with real-world data.

Key Points to Remember About Concrete Classes

• Instantiable: Concrete classes can be instantiated, allowing you to create objects that represent specific entities or concepts in your application.

• Complete implementation: Concrete classes provide full implementations of all methods and properties, unlike abstract classes or interfaces.

• Common use: They are the most common type of class in C#, used to define objects with specific behavior and data.

Concrete classes are essential for C# development, enabling you to define and work with objects that model real-world entities within your applications. Understanding how to effectively use concrete classes is crucial for building robust, object-oriented software.

Abstract Classes in C Sharp

In C#, abstract classes are a powerful feature that allow you to define a blueprint for other classes without providing complete implementations. They serve as base classes that cannot be instantiated directly but can be inherited by other classes that will provide specific implementations for the abstract methods defined within them. This design helps enforce consistency across related classes while allowing flexibility in how certain behaviors are implemented.

What Does "Instantiated" Mean?

Before exploring abstract classes, let's clarify what it means to instantiate a class. Instantiation is the process of creating an object from a class. When you use the new keyword in C#, you are creating an instance (or object) of that class.

But abstract classes cannot be instantiated directly. They must be inherited by a non-abstract (concrete) class that provides implementations for the abstract methods.

Understanding Abstract Classes and Abstract Methods

Abstract classes are classes you can't create objects from directly. They act as templates for other classes. They can have both complete methods and methods without a body (abstract methods). Abstract classes help set up a common interface and shared behavior for related classes.

Abstract methods, on the other hand, are methods in an abstract class that don't have a body. Any non-abstract class that inherits from the abstract class must provide a body for these methods. This ensures all subclasses have a consistent interface.

Real-World Example: Bank Account Management

Let's explore a real-world example to illustrate the concept of abstract classes and abstract methods in C#.

using System;

// define an abstract class
namespace AbstractClasses
{
    // Abstract class
    public abstract class BankAccount
    {
        // Properties
        public string AccountNumber { get; private set; }
        public decimal Balance { get; protected set; }

        // Constructor
        public BankAccount(string accountNumber, decimal initialBalance)
        {
            AccountNumber = accountNumber;
            Balance = initialBalance;
        }

        // Abstract methods
        public abstract void Deposit(decimal amount);
        public abstract void Withdraw(decimal amount);
        public abstract void DisplayAccountInfo();
    }

    // Derived class: SavingsAccount
    public class SavingsAccount : BankAccount
    {
        private decimal interestRate;

        public SavingsAccount(string accountNumber, decimal initialBalance, decimal interestRate)
            : base(accountNumber, initialBalance)
        {
            this.interestRate = interestRate;
        }

        // Implementing abstract methods
        public override void Deposit(decimal amount)
        {
            Balance += amount;
            Console.WriteLine($"Deposited {amount} to Savings Account {AccountNumber}. New Balance: {Balance}");
        }

        public override void Withdraw(decimal amount)
        {
            if (amount > Balance)
            {
                throw new InvalidOperationException("Insufficient funds.");
            }
            Balance -= amount;
            Console.WriteLine($"Withdrew {amount} from Savings Account {AccountNumber}. New Balance: {Balance}");
        }

        public override void DisplayAccountInfo()
        {
            Console.WriteLine($"Savings Account {AccountNumber} - Balance: {Balance}, Interest Rate: {interestRate}%");
        }
    }

    // Derived class: CheckingAccount
    public class CheckingAccount : BankAccount
    {
        private decimal overdraftLimit;

        public CheckingAccount(string accountNumber, decimal initialBalance, decimal overdraftLimit)
            : base(accountNumber, initialBalance)
        {
            this.overdraftLimit = overdraftLimit;
        }

        // Implementing abstract methods
        public override void Deposit(decimal amount)
        {
            Balance += amount;
            Console.WriteLine($"Deposited {amount} to Checking Account {AccountNumber}. New Balance: {Balance}");
        }

        public override void Withdraw(decimal amount)
        {
            if (amount > Balance + overdraftLimit)
            {
                throw new InvalidOperationException("Overdraft limit exceeded.");
            }
            Balance -= amount;
            Console.WriteLine($"Withdrew {amount} from Checking Account {AccountNumber}. New Balance: {Balance}");
        }

        public override void DisplayAccountInfo()
        {
            Console.WriteLine($"Checking Account {AccountNumber} - Balance: {Balance}, Overdraft Limit: {overdraftLimit}");
        }
    }
}

In this example, the BankAccount class is an abstract class that defines a common interface for different types of bank accounts. It includes abstract methods like Deposit, Withdraw, and DisplayAccountInfo, which must be implemented by any class that inherits from BankAccount.

The SavingsAccount and CheckingAccount classes inherit from BankAccount and provide specific implementations for these abstract methods. This design enforces that every type of bank account must implement deposit, withdrawal, and display functions, while still allowing each account type to implement these functions in a way that makes sense for that specific type.

How to Use Abstract Classes in a Program

Let's see how we can use the SavingsAccount and CheckingAccount classes in a Program.cs file.

namespace AbstractClasses
{
    class Program
    {
        static void Main(string[] args)
        {
            // Create a savings account
            BankAccount savings = new SavingsAccount("SA123", 1000, 1.5m);
            // Create a checking account
            BankAccount checking = new CheckingAccount("CA123", 500, 200);

            // Deposit and withdraw from the savings account
            savings.DisplayAccountInfo();

           // Deposit and withdraw from the checking account
            savings.Deposit(200);

            savings.Withdraw(100);
            // Display the updated account information
            savings.DisplayAccountInfo();

            checking.DisplayAccountInfo();

             // Deposit and withdraw from the checking account
            checking.Deposit(300);

            checking.Withdraw(600);

            // Display the updated account information
            checking.DisplayAccountInfo();

            try
            {
                checking.Withdraw(200);
            }
            catch (InvalidOperationException ex)
            {
                Console.WriteLine($"Error: {ex.Message}");
            }

            checking.DisplayAccountInfo();
        }
    }
}

This program will produce the following output:

Savings Account SA123 - Balance: 1000, Interest Rate: 1.5%
Deposited 200 to Savings Account SA123. New Balance: 1200
Withdrew 100 from Savings Account SA123. New Balance: 1100
Savings Account SA123 - Balance: 1100, Interest Rate: 1.5%
Checking Account CA123 - Balance: 500, Overdraft Limit: 200
Deposited 300 to Checking Account CA123. New Balance: 800
Withdrew 600 from Checking Account CA123. New Balance: 200
Checking Account CA123 - Balance: 200, Overdraft Limit: 200
Withdrew 200 from Checking Account CA123. New Balance: 0
Checking Account CA123 - Balance: 0, Overdraft Limit: 200

In this example, the SavingsAccount and CheckingAccount objects are created, and the abstract methods Deposit, Withdraw, and DisplayAccountInfo are called. The abstract class BankAccount ensures that both account types have these methods, while the derived classes provide the specific functionality.

Key Points to Remember About Abstract Classes

• Cannot be instantiated: You can't create an instance of an abstract class directly. A subclass must inherit it and provide the implementations for the abstract methods.

• Contain abstract methods: Abstract methods in an abstract class have no body. Any non-abstract class that inherits from the abstract class must implement these methods.

• Define common interfaces: Abstract classes set a common interface for related classes, ensuring they are consistent while allowing different implementations.

Abstract classes are important in C#. They help enforce a structure across related classes but still allow for specific details. By using abstract classes, you can make your code more organized, easier to maintain, and extend.

Singleton Classes in C Sharp

Singleton classes are a design pattern that restricts the instantiation of a class to one single instance. This is particularly useful when you need a single, shared resource across your application, such as a configuration manager, logging service, or database connection.

Why Use Singleton Classes in C#?

Imagine you have a class responsible for managing a database connection. You don’t want multiple instances of this class running around, potentially causing issues with resource management or inconsistent data. A Singleton class ensures that only one instance is created and provides a global point of access to it.

Example: Defining a Singleton Class

Let’s now see how you can implement a Singleton class in C#:

// Define a singleton class
public class Singleton
{
    private static Singleton instance;
    private static readonly object lockObject = new object();

    // Private constructor prevents instantiation from outside the class
    private Singleton()
    {
    }

    // Public property to access the single instance of the class
    public static Singleton Instance
    {
        get
        {
            // Ensure thread safety
            lock (lockObject)
            {
                if (instance == null)
                {
                    instance = new Singleton();
                }
            }
            return instance;
        }
    }

    // Example method to demonstrate the singleton instance
    public void PrintMessage()
    {
        Console.WriteLine("Hello, I am a singleton class.");
    }
}

In this example, the Singleton class is defined with a private constructor, which prevents other classes from creating new instances. The static property Instance returns the single instance of the class, creating it if it doesn't already exist. The lockObject ensures that the class is thread-safe, meaning that even in a multi-threaded environment, only one instance will be created.

The PrintMessage method is just a simple example to show that the Singleton instance can be used like any other class instance.

How to Use the Singleton Class in Program.cs

Now let’s see how you can use this Singleton class in your application:

class Program
{
    static void Main(string[] args)
    {
        // Retrieve the single instance of the Singleton class
        Singleton singleton1 = Singleton.Instance;
        singleton1.PrintMessage(); // Output: Hello, I am a singleton class.

        // Retrieve the instance again
        Singleton singleton2 = Singleton.Instance;

        // Check if both instances are the same
        Console.WriteLine(singleton1 == singleton2); // Output: True
    }
}

In this example, we retrieve the Singleton instance twice. Because the class is a Singleton, both singleton1 and singleton2 refer to the same instance. The == operator confirms this by returning true.

How to Extend the Singleton Example

You can expand the Singleton pattern to handle more complex scenarios. For example, you could initialize the Singleton instance with configuration data:

public class ConfigurationManager
{
    private static ConfigurationManager instance;
    private readonly Dictionary<string, string> settings = new Dictionary<string, string>();

    private ConfigurationManager()
    {
        // Simulate loading settings from a configuration file
        settings["AppName"] = "MyApplication";
        settings["Version"] = "1.0.0";
    }

    public static ConfigurationManager Instance
    {
        get
        {
            if (instance == null)
            {
                instance = new ConfigurationManager();
            }
            return instance;
        }
    }

    public string GetSetting(string key)
    {
        return settings.ContainsKey(key) ? settings[key] : null;
    }
}

Here, ConfigurationManager is a Singleton class that loads and manages application settings. The GetSetting method allows you to retrieve specific configuration values, ensuring that all parts of your application use the same settings.

Key Points to Remember About Singleton Classes

• Single instance: Singleton classes ensure that only one instance of the class exists in the application.

• Global access: Singleton provides a global point of access to the instance, making it easy to use across different parts of your application.

• Thread safety: In multi-threaded environments, ensure your Singleton is thread-safe to avoid creating multiple instances.

• Use cases: Common use cases for Singleton include managing configurations, logging services, and database connections.

Singleton classes are a fundamental design pattern in software engineering, offering a simple yet powerful way to manage shared resources. Understanding and correctly implementing Singletons can help you write more efficient and maintainable code.

Generic Classes in C Sharp

Generic classes in C# provide a powerful way to create reusable and type-safe code. By using generic classes, you can design a single class that works with any data type, eliminating the need for type-specific implementations. This makes your code more flexible and reduces redundancy.

Why Use Generic Classes?

Imagine you need to implement a stack that stores integers. Later, you might need another stack to store strings.

Instead of writing two separate classes, you can write one generic stack class that can handle both data types—and any others you might need. Generic classes help you avoid code duplication and make your codebase easier to maintain.

Example: Defining a Generic Class

Let’s take a look at a simple implementation of a generic stack class:

// Define a generic class
public class Stack<T>
{
    private List<T> items = new List<T>();

    public void Push(T item)
    {
        items.Add(item);
    }

    public T Pop()
    {
        if (items.Count == 0)
        {
            throw new InvalidOperationException("The stack is empty.");
        }
        T item = items[items.Count - 1];
        items.RemoveAt(items.Count - 1);
        return item;
    }

    public T Peek()
    {
        if (items.Count == 0)
        {
            throw new InvalidOperationException("The stack is empty.");
        }
        return items[items.Count - 1];
    }

    public bool IsEmpty()
    {
        return items.Count == 0;
    }
}

In this example, the Stack<T> class is defined with a type parameter T. This type parameter is a placeholder that represents the type of data the stack will store. The class includes methods like Push to add an item to the stack, Pop to remove and return the top item, Peek to view the top item without removing it, and IsEmpty to check if the stack is empty.

Because Stack<T> is generic, you can use it with any data type, whether it's int, string, or even a custom class.

How to Use the Stack Class in Program.cs

Let’s see how this generic Stack class can be used in a program:

class Program
{
    static void Main(string[] args)
    {
        // Stack for integers
        Stack<int> intStack = new Stack<int>();
        intStack.Push(10);
        intStack.Push(20);
        Console.WriteLine(intStack.Pop()); // Output: 20
        Console.WriteLine(intStack.Peek()); // Output: 10

        // Stack for strings
        Stack<string> stringStack = new Stack<string>();
        stringStack.Push("Hello");
        stringStack.Push("World");
        Console.WriteLine(stringStack.Pop()); // Output: World
        Console.WriteLine(stringStack.Peek()); // Output: Hello
    }
}

In this example, we create two instances of the Stack class: one that stores integers and another that stores strings. The flexibility of generics allows us to use the same class to work with different data types, making our code more reusable and concise.

How to Extend the Generic Class

Let’s take it a step further and extend our Stack class to include a method that returns all items as an array:

public T[] ToArray()
{
    return items.ToArray();
}

Now, you can easily convert the stack’s items into an array:

int[] intArray = intStack.ToArray();
string[] stringArray = stringStack.ToArray();

This extension further showcases the power of generics, allowing the same method to work with different data types seamlessly.

Key Points to Remember About Generic Classes

• Flexibility: Generic classes can handle any data type, making them adaptable and reusable.

• Type safety: Using type parameters ensures that your code is type-safe, catching errors during compile-time instead of runtime.

• Code reuse: Generics remove the need to duplicate code for different data types, resulting in cleaner and easier-to-maintain code.

• Type parameters: Generic classes use type parameters as placeholders for the actual data types you will use when creating an instance of the class.

Generic classes are crucial in C# for building flexible, reusable, and type-safe code. By learning and using generics, you can create more reliable and maintainable applications.

Internal Classes in C Sharp

Internal classes in C# are a powerful way to encapsulate implementation details within an assembly. By using the internal access modifier, you can restrict access to certain classes, ensuring they are only accessible within the same assembly.

This is particularly useful for hiding complex logic or utility classes that are not intended to be exposed to the public API of your library or application.

Why Use Internal Classes?

In a large application, you may have classes that should only be used internally by your code and not by external consumers. For example, helper classes, utility functions, or components of a larger system that do not need to be exposed outside the assembly can be marked as internal. This ensures that your public API remains clean and focused while still allowing full functionality within the assembly.

Example: Defining an Internal Class

Let’s consider a scenario where you have a library that processes orders. You might have a class that handles the complex logic of calculating discounts, but you don't want this class to be accessible to users of your library. Instead, you only expose the main OrderProcessor class, keeping the discount logic hidden with an internal class.

// Define a public class that uses an internal class
public class OrderProcessor
{
    public void ProcessOrder(int orderId)
    {
        // Internal class is used here
        DiscountCalculator calculator = new DiscountCalculator();
        decimal discount = calculator.CalculateDiscount(orderId);
        Console.WriteLine($"Order {orderId} processed with a discount of {discount:C}");
    }

    // Internal class that handles discount calculations
    internal class DiscountCalculator
    {
        public decimal CalculateDiscount(int orderId)
        {
            // Complex discount calculation logic
            return orderId * 0.05m;
        }
    }
}

In this example, the DiscountCalculator class is marked as internal, meaning it’s only accessible within the assembly. The OrderProcessor class, which is public, uses this internal class to process orders. External users of the library can call ProcessOrder without needing to know about or interact with the DiscountCalculator class.

How to Use the Internal Class in Program.cs

Now, let's see how this works in practice:

class Program
{
    static void Main(string[] args)
    {
        OrderProcessor processor = new OrderProcessor();
        processor.ProcessOrder(12345); // Output: Order 12345 processed with a discount of $617.25
    }
}

In this example, the ProcessOrder method is publicly accessible, but the internal workings of discount calculation remain hidden, providing a clean and secure API.

Key Points to Remember About Internal Classes

• Limited access: Internal classes can only be accessed within the same assembly, which helps keep your public API simple and focused.

• Encapsulation: They are used to hide implementation details, like helper functions or complex logic, that shouldn't be publicly visible.

• Visibility control: The internal access modifier lets you control which classes and members are visible, ensuring only the necessary parts of your code are accessible to other assemblies.

Internal classes are important for managing complex applications, allowing you to control what parts of your code can be accessed from outside your assembly. By hiding details and limiting access, you can keep your codebase clean, easy to maintain, and secure.

Nested Classes in C Sharp

Nested classes in C# are defined within another class. This structure is useful for grouping related classes together and encapsulating the implementation details. Nested classes can be either static or non-static, and they have direct access to the private members of their enclosing class.

Why Use Nested Classes?

Nested classes are particularly useful when a class is closely tied to the logic of another class and isn’t meant to be used independently. They allow you to encapsulate helper classes, hide them from other parts of the program, and keep related code together. This can lead to a cleaner, more organized codebase.

Example: Defining a Nested Class

Let’s consider a scenario where we have a class that represents a Car and another class that represents a Engine. Since the Engine class is closely related to the Car class and doesn’t make much sense on its own, we can define it as a nested class within Car.

// Define a class with a nested class
public class Car
{
    // Define private fields
    private string model;
    private Engine carEngine;

   // Constructor
    public Car(string model)
    {
        this.model = model;
        carEngine = new Engine();
    }


    // Method to start the car
    public void StartCar()
    {
        carEngine.StartEngine();
        Console.WriteLine($"{model} is starting...");
    }

    // Nested class
    public class Engine
    {
        public void StartEngine()
        {
            Console.WriteLine("Engine started.");
        }
    }
}

In this example, the Car class has a private field model and a method StartCar that starts the car. The Engine class is nested within the Car class and contains a StartEngine method. By nesting Engine inside Car, we express the close relationship between the two.

How to Use the Nested Class in Program.cs

Let’s see how we can use the Car class and its nested Engine class in a program:

class Program
{
    static void Main(string[] args)
    {
        Car myCar = new Car("Toyota");
        myCar.StartCar(); // Output: Engine started. Toyota is starting...

        // Although you can create an instance of the nested class separately, it usually makes sense to use it through the outer class
        Car.Engine engine = new Car.Engine();
        engine.StartEngine(); // Output: Engine started.
    }
}

In this example, we create an instance of the Car class and call the StartCar method, which internally calls the StartEngine method of the nested Engine class. While it's possible to instantiate the nested class separately, it’s more common to access it through the outer class, emphasizing the relationship between the two.

Key Points to Remember About Nested Classes

• Encapsulation: Nested classes keep details hidden that shouldn't be seen outside the main class.

• Access to private members: Nested classes can access private parts of the main class, making them good for helper classes that need to work with the main class's internal parts.

• Organization: Use nested classes to keep related classes together, which makes the code cleaner and more organized.

• Static or non-static: Nested classes can be static or non-static. Static nested classes can't access the instance parts of the main class directly, but non-static nested classes can.

Nested classes are a useful way to organize your code, especially for complex objects with closely related parts. Keeping related classes together makes your code easier to manage and maintain.

Partial Classes in C Sharp

Partial classes in C# allow you to split a class definition across multiple files. This feature is particularly useful in large projects, where it can be beneficial to break a complex class into smaller, more manageable sections.

By using the partial keyword, you can organize your code better, especially when working with generated code or collaborating in a team environment.

Why Use Partial Classes?

Imagine you’re working on a large application where a single class contains hundreds of lines of code. This can become difficult to manage and maintain. By using partial classes, you can divide the class into logical parts, each residing in a separate file. This not only makes the code more readable but also allows multiple developers to work on different parts of the class simultaneously without causing merge conflicts.

Example: Defining a Partial Class in C

Let’s say we have a class that handles various operations for an employee management system. Instead of putting all methods in one file, we can split them across multiple files using partial classes.

File 1: PartialClass_Methods1.cs

// Define a partial class
public partial class EmployeeOperations
{
    public void AddEmployee(string name)
    {
        Console.WriteLine($"Employee {name} added.");
    }
}

File 2: PartialClass_Methods2.cs

// Define the other part of the partial class
public partial class EmployeeOperations
{
    public void RemoveEmployee(string name)
    {
        Console.WriteLine($"Employee {name} removed.");
    }
}

In these examples, the EmployeeOperations class is split into two files, each containing a part of the class. The first file handles adding employees, while the second file handles removing them.

How to Use the Partial Class in Program.cs

Now, let’s use the EmployeeOperations class in our Program.cs file:

class Program
{
    static void Main(string[] args)
    {
        EmployeeOperations operations = new EmployeeOperations();

        operations.AddEmployee("John Doe");    // Output: Employee John Doe added.
        operations.RemoveEmployee("John Doe"); // Output: Employee John Doe removed.
    }
}

In this example, the EmployeeOperations class, although defined in multiple files, behaves like a single class. The methods AddEmployee and RemoveEmployee are seamlessly combined, providing a clean and organized way to manage operations.

Key Points to Remember About Partial Classes

• Code organization: Partial classes help keep large classes organized by splitting them into smaller, focused sections.

• Team collaboration: Multiple developers can work on different parts of the same class without interfering with each other’s code.

• Generated code: Often used with auto-generated code, where part of the class is generated by a tool, and the rest is written manually.

Partial classes are a powerful feature in C# that allows for better code management, especially in large-scale applications. By breaking down a class into logical components, you can maintain clean, readable, and maintainable code.

Conclusion

Classes are the building blocks of object-oriented programming in C#. By understanding the different types of classes—abstract, static, sealed, concrete, and singleton—you can create well-structured, maintainable, and efficient code.

Whether you’re designing utility classes, defining abstract interfaces, or encapsulating complex logic, classes play a crucial role in shaping your application’s architecture.

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.

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.

The SOLID Principles were introduced by a software engineer named Robert C. Martin (also known as "Uncle Bob") in the early 2000s. Uncle Bob’s goal was to promote good software design practices, particularly in object-oriented programming (OOP), by addressing common problems developers face as software systems grow in size and complexity.

Here are the five SOLID principles:

• S: Single Responsibility Principle (SRP)

• O: Open-closed Principle (OCP)

• L: Liskov Substitution Principle (LSP)

• I: Interface Segregation Principle (ISP)

• D: Dependency Inversion Principle (DIP)

By following these principles, you can create software designs that are easier to understand, maintain, and extend, leading to higher-quality software that is more robust and adaptable to change.

In this article, to demonstrate each principle, I’ll first show you a bad code example in C# that violates the principle. We will then discuss the issues this bad code causes, and then solve those issues by refactoring the code to satisfy the principle.

First up we have the…

Single Responsibility Principle (SRP) in C

A class should have only one reason to change, meaning that it should have only one responsibility or purpose.

This principle encourages you to create classes that are more focussed and perform one single well-defined task, rather than multiple tasks. Breaking up classes into smaller, more focused units makes code easier to understand, maintain, and test.

An example that violates the SRP:

public class User
{
 public string Username { get; set; }
 public string Email { get; set; }

 public void Register()
 {
   // Register user logic, e.g. save to database...

   // Send email notification
   EmailSender emailSender = new EmailSender();
   emailSender.SendEmail("Welcome to our platform!", Email);
 }
}

public class EmailSender
{
 public void SendEmail(string message, string recipient)
 {
   // Email sending logic
   Console.WriteLine($"Sending email to {recipient}: {message}");
 }
}

In this example, the User class manages user data (username and email), and contains logic for registering a user. This violates the SRP because the class has more than one reason to change. It could change due to:

• Modifications in user data management – for example adding more fields, such as firstName, gender, hobbies.

• Modifications to the logic of registering a user, for example we may choose to fetch a user from the database by their username rather than their email.

To adhere to the Single Responsibility Principle, we should separate these responsibilities into separate classes.

Refactoring the code to satisfy the SRP:

public class User
{
 public string Username { get; set; }
 public string Email { get; set; }
}

public class EmailSender
{
 public void SendEmail(string message, string recipient)
 {
   // Email sending logic
   Console.WriteLine($"Sending email to {recipient}: {message}");
 }
}

public class UserService
{
 public void RegisterUser(User user)
 {
   // Register user logic...

   EmailSender emailSender = new EmailSender();
   emailSender.SendEmail("Welcome to our platform!", user.Email);
 }
}

In the refactored code, the User class is responsible solely for representing user data. The UserService class now handles user registration, separating concerns related to user data management from user registration logic. The UserService class is responsible only for the business logic of registering a user.

This separation of responsibilities adheres to the Single Responsibility Principle, making the code easier to understand, maintain, and extend.

Open/Closed Principle (OCP) in C

Software entities (classes, modules, functions, etc.) should be open for extension but closed for modification.

This principle promotes the idea that existing code should be able to be extended with new functionality without modifying its source code. It encourages the use of abstraction and polymorphism to achieve this goal, allowing for code to be easily extended through inheritance or composition.

(By the way, if you don’t understand these fundamental OOP concepts, such as abstraction, polymorphism, inheritance and composition — then check out my book, Mastering Design Patterns in C#: A Beginner-Friendly Guide, Including OOP and SOLID Principles on Amazon or Gumroad.)

Let's consider an example of a Shape class hierarchy that calculates the area of different geometric shapes. Initially, this violates the Open/Closed Principle because adding a new shape requires modifying the existing code:

public enum ShapeType
{
 Circle,
 Rectangle
}

public class Shape
{
 public ShapeType Type { get; set; }
 public double Radius { get; set; }
 public double Length { get; set; }
 public double Width { get; set; }

 public double CalculateArea()
 {
   switch (Type)
   {
     case ShapeType.Circle:
       return Math.PI * Math.Pow(Radius, 2);
     case ShapeType.Rectangle:
       return Length * Width;
     default:
       throw new InvalidOperationException("Unsupported shape type.");
   }
 }
}

In this example, the Shape class has a method, CalculateArea(), that calculates the area based on the type of shape. Adding a new shape, such as a triangle, would require modifying the existing Shape class, violating the OCP.

To adhere to the Open/Closed Principle, we should design the system in a way that allows for extension without modification. Let's refactor the code using inheritance and polymorphism:

public abstract class Shape
{
 public abstract double CalculateArea();
}

public class Circle : Shape
{
 public double Radius { get; set; }

 public override double CalculateArea()
 {
   return Math.PI * Math.Pow(Radius, 2);
 }
}

public class Rectangle : Shape
{
 public double Length { get; set; }
 public double Width { get; set; }

 public override double CalculateArea()
 {
   return Length * Width;
 }
}

In this refactored code, we define an abstract Shape class with an abstract CalculateArea() method. Concrete shape classes (Circle and Rectangle) inherit from the Shape class and provide their own implementations of CalculateArea().

Adding a new shape, such as a triangle, would involve creating a new class – extending the codebase – that inherits from Shape and implements CalculateArea(), without modifying existing code. This adheres to the OCP by allowing for extension without modification.

Being able to add functionality without modifying existing code means that we don’t have to worry as much about breaking existing working code and introducing bugs.

Following the OCP encourages us to design our software so that we add new features only by adding new code. This helps us to build loosely-coupled, maintainable software.

Liskov Substitution Principle (LSP) in C

Objects of a superclass should be replaceable with objects of its subclass without affecting the correctness of the program.

This principle ensures that inheritance hierarchies are well-designed and that subclasses adhere to the contracts defined by their superclasses.

Violations of the LSP can lead to unexpected behavior or errors when substituting objects, making code harder to reason about and maintain.

Let's consider an example involving a Rectangle class and a Square class, which inherit from a common Shape class. Initially, we'll violate the LSP by not adhering to the behavior expected from these classes. Then, we'll fix it to ensure that the principle is respected.

public abstract class Shape
{
 public abstract double Area { get; }
}

public class Rectangle : Shape
{
 public virtual double Width { get; set; }

 public virtual double Height { get; set; }

 public override double Area => Width * Height;
}

public class Square : Rectangle
{
 public override double Width
 {
   get => base.Width;
   set => base.Width = base.Height = value;
 }

 public override double Height
 {
   get => base.Height;
   set => base.Height = base.Width = value;
 }
}

Now, let’s test out if Rectangle calculates its area correctly:

// Program.cs

var rect = new Rectangle();
rect.Height = 10;
rect.Width = 5;

System.Console.WriteLine("Expected area = 10 * 5 = 50.");

System.Console.WriteLine("Calculated area = " + rect.Area);

Running the program:

Expected area = 10 * 5 = 50.

Calculated area = 50

Perfect!

Now, in our program, the Square class inherits from, or extends, the Rectangle class, because, mathematically, a square is just a special type of rectangle, where its height equals its width. Because of this, we decided that Square should extend Rectangle – it’s like saying “a square is a (special type of) rectangle”.

But look what happens if we substitute the Rectangle class for the Square class:

var rect = new Square();
rect.Height = 10;
rect.Width = 5;

System.Console.WriteLine("Expected area = 10 * 5 = 50.");

System.Console.WriteLine("Calculated area = " + rect.Area);

Expected area = 10 * 5 = 50.

Calculated area = 25

Oh dear, LSP has been violated: we replaced the object of a superclass (Rectangle) with an object of its subclass (Square), and it affected the correctness of our program. By modeling Square as a subclass of Rectangle, and allowing width and height to be independently set, we violate the LSP. When setting the width and height of a Square, it should retain its squareness, but our implementation allows for inconsistency.

Let’s fix this to satisfy LSP:

public abstract class Shape
{
 public abstract double Area { get; }
}

public class Rectangle : Shape
{
 public double Width { get; set; }

 public double Height { get; set; }

 public override double Area => Width * Height;
}

public class Square : Shape
{
 private double sideLength;

 public double SideLength
 {
   get => sideLength;
   set
   {
     sideLength = value;
   }
 }

 public override double Area => sideLength * sideLength;
}

// Program.cs

Shape rectangle = new Rectangle { Width = 5, Height = 4 };

Console.WriteLine($"Area of the rectangle: {rectangle.Area}");

Shape square = new Square { SideLength = 5 };

Console.WriteLine($"Area of the square: {square.Area}");

In this corrected example, we redesign the Square class to directly set the side length. Now, a Square is correctly modeled as a subclass of Shape, and it adheres to the Liskov Substitution Principle.

How does this satisfy LSP? Well, we have a superclass, Shape, and subclasses Rectangle and Square. Both Rectangle and Square maintain the correct expected behavior of a Shape — we can substitute a square for a rectangle and the area will still be calculated correctly.

Interface Segregation Principle (ISP) in C

Clients should not be forced to depend on interfaces they do not use.

This principle encourages the creation of fine-grained interfaces that contain only the methods required by the clients that use them. It helps to prevent the creation of "fat" interfaces that force clients to implement unnecessary methods, leading to cleaner and more maintainable code.

Let's consider an example involving 2D and 3D shapes, initially violating the ISP.

Violating ISP:

public interface IShape
{
 double Area();
 double Volume(); // problem: 2D shapes don't have volume!
}

public class Circle : IShape
{
 public double Radius { get; set; }

 public double Area()
 {
   return Math.PI * Math.Pow(Radius, 2);
 }

 public double Volume()
 {
   throw new InvalidOperationException("Volume not applicable for 2D shapes.");
 }
}

public class Sphere : IShape
{
 public double Radius { get; set; }

 public double Area()
 {
   return 4 * Math.PI * Math.Pow(Radius, 2);
 }

 public double Volume()
 {
   return (4.0 / 3.0) * Math.PI * Math.Pow(Radius, 3);
 }
}

In this example, we have an IShape interface representing both 2D and 3D shapes. However, the Volume() method is problematic for 2D shapes, like Circle and Rectangle, because they don't have volume. This violates the ISP because clients (classes using the IShape interface) may be forced to depend on methods they do not need.

var circle = new Circle();
circle.Radius = 10;

System.Console.WriteLine(circle.Area());
System.Console.WriteLine(circle.Volume()); // My text editor doesn't flag a problem...

var sphere = new Sphere();
sphere.Radius = 10;

System.Console.WriteLine(sphere.Area());
System.Console.WriteLine(sphere.Volume());

Usually, if I try to call a method on an object that doesn’t exist, VS Code will tell me that I’m making a mistake. But above, when I call circle.Volume(), VS code is like “no problem”. And VS code is correct, because the IShape interface forces Circle to implement a Volume() method, even though circles don’t have volume.

It’s easy to see how violating ISP can introduce bugs into a program – above, everything looks fine, until we run the program and an exception gets thrown.

Fixing ISP

public interface IShape2D
{
 double Area();
}

public interface IShape3D
{
 double Area();
 double Volume();
}

public class Circle : IShape2D
{
 public double Radius { get; set; }

 public double Area()
 {
   return Math.PI * Math.Pow(Radius, 2);
 }
}

public class Sphere : IShape3D
{
 public double Radius { get; set; }

 public double Area()
 {
   return 4 * Math.PI * Math.Pow(Radius, 2);
 }

 public double Volume()
 {
   return (4.0 / 3.0) * Math.PI * Math.Pow(Radius, 3);
 }
}

In the fixed example, we've segregated the IShape interface into two smaller, more focused interfaces: IShape2D and IShape3D. Each shape class now implements only the interface that is relevant to its functionality.

This adheres to the Interface Segregation Principle by ensuring that clients are not forced to depend on methods that they do not use. Clients can now depend only on the interfaces that they need, promoting better code reuse and flexibility.

Next up, the fifth and final SOLID principle…

Dependency Inversion Principle (DIP) in C

High-level modules should not depend on low-level modules. Both should depend on abstractions.

Dependency Inversion is the strategy of depending upon interfaces or abstract classes rather than upon concrete classes. This principle promotes decoupling between modules and promotes the use of interfaces or abstract classes to define dependencies, allowing for more flexible and testable code.

Let's start with an example violating the DIP and then we’ll correct it.

public class Engine // Engine is our "low-level" module
{
 public void Start()
 {
   System.Console.WriteLine("Engine started.");
 }
}

public class Car // Car is our "high-level" module
{
 private Engine engine;

 public Car()
 {
   this.engine = new Engine(); // Direct dependency on concrete Engine class
 }

 public void StartCar()
 {
   engine.Start();
   System.Console.WriteLine("Car started.");
 }
}

In this example:

• The Car class directly creates an instance of the Engine class, leading to a tight coupling between Car and Engine.

• If the Engine class changes, it may affect the Car class, violating the Dependency Inversion Principle.

The UML diagram below shows that Car depends on Engine:

But what do we mean by “high level” and “low level” classes?

High-Level Class: The high-level class is typically the one that represents the main functionality or business logic of the application. It orchestrates the interaction between various components and is often more abstract in nature.

In this example, the Car class can be considered the high-level class. It represents the main functionality related to starting the car and driving it. The Car class is concerned with the overall behavior of the car, such as controlling its movement.

Low-Level Class: The low-level class is usually one that provides specific functionality or services that are used by the high-level class. It typically deals with implementation details and is more concrete in nature.

In this example, the Engine class can be considered the low-level class. It provides the specific functionality related to starting the engine. The Engine class encapsulates the details of how the engine operates, such as ignition and combustion.

So in summary, the Car class is the high-level class, representing the main functionality of the application related to the car's behavior.

The Engine class is the low-level class, providing specific functionality related to the operation of the engine, which is used by the Car class.

Fixing DIP:

To adhere to the Dependency Inversion Principle, we introduce an abstraction (interface) between Car and Engine, allowing Car to depend on an abstraction instead of a concrete implementation.

public interface IEngine
{
 void Start();
}

public class Engine : IEngine
{
 public void Start()
 {
   System.Console.WriteLine("Engine started.");
 }
}

public class Car
{
 private IEngine engine;

 public Car(IEngine engine)
 {
   this.engine = engine;
 }

 public void StartCar()
 {
   engine.Start();
   System.Console.WriteLine("Car started.");
 }
}

We can now inject any type of engine into Car implementations:

var engine = new Engine(); // concrete implementation to be "injected" into the car

var car = new Car(engine);

car.StartCar();

From the UML diagram below, we can see that both objects now depend on the abstraction level of the interface. Engine has inverted its dependency on Car.

In this corrected example:

1. We define an interface IEngine representing the behavior of an engine.

2. The Engine class implements the IEngine interface.

3. The Car class now depends on the IEngine interface instead of the concrete Engine class.

4. Dependency injection is used to inject the IEngine implementation into the Car class, promoting loose coupling. Now, if we want to give a car a different type of engine, for example a FastEngine, we can inject that in instead.

5. Now, if the implementation of the engine changes, it won't affect the Car class as long as it adheres to the IEngine interface.

Dependency Injection (DI) offers several advantages in software development:

• Decoupling: DI promotes loose coupling between components by removing direct dependencies. Components rely on abstractions rather than concrete implementations, making them more independent and easier to maintain.

• Testability: Dependency injection simplifies unit testing by allowing components to be easily replaced with mock or stub implementations during testing. This enables isolated testing of individual components without relying on their dependencies.

• Flexibility: DI provides flexibility in configuring and swapping dependencies at runtime. It allows different implementations of dependencies to be used interchangeably without modifying the client code, facilitating runtime customization and extensibility.

• Readability and Maintainability: By explicitly specifying dependencies in the constructor or method parameters, DI improves code readability and makes the codebase easier to understand. It also reduces the risk of hidden dependencies, leading to more maintainable and understandable code.

• Reusability: DI promotes component reusability by decoupling them from their specific contexts or environments. Components can be designed to be independent of the application framework or platform, making them more portable and reusable in different projects or scenarios.

• Scalability: DI simplifies the management of dependencies in large-scale applications by providing a standardised approach for dependency resolution. It helps prevent dependency hell and makes it easier to manage and scale complex systems.

Overall, dependency injection enhances modularity, testability, and maintainability of software systems, contributing to improved software quality and developer productivity.

Conclusion

Congratulations – you now understand the extremely important SOLID principles. These principles are going to save you a lot of headaches during your software development career, and guide you towards creating beautiful, maintainable, flexible, testable software.

If you’d like to take your software development skills to the next level and learn:

• OOP principles: encapsulation, abstraction, inheritance, polymorphism, coupling, composition, composition vs inheritance, fragile base class problem.

• All 23 design patterns (“The Gang of Four Design Patterns”) with real world examples.

• Unified Modeling Language (UML): the standard way to model classes and the relationships between them.

Then check out my book:

Mastering Design Patterns in C#: A Beginner-Friendly Guide, Including OOP and SOLID Principles on Amazon (also available on Gumroad).

Hopefully this article helps you to become a better OOP software developer!

Thanks for reading,

Danny 😎