DEV Community: Ivan Kahl

Beyond CRUD: A Practical Guide to Modeling Business Processes in REST APIs

Ivan Kahl — Wed, 01 Apr 2026 09:30:00 +0000

Most developers agree that naming things is one of the hardest parts of our job. Designing a clear, effective RESTful API comes in as a close runner-up.

On the surface, REST makes a lot of sense. Compared to its dominant predecessor, SOAP, which involved hammering a POST endpoint with unwieldy XML requests, REST feels like a breath of fresh air. By combining an HTTP Method with a URI (Uniform Resource Identifier), you can create (POST), read (GET), update (PUT or PATCH), and delete (DELETE) resources. Simple and intuitive, right?

Not quite. HTTP methods were originally designed to manage documents, not to model complex business processes. They assume that all you need to do with a resource is create, read, update, or delete it. In reality, business applications often require more: resources might need to be approved, cancelled (without being deleted), paid, or moved between different states. Sometimes, a process even spans several resources at once. Mapping these kinds of business actions to a RESTful API is not always straightforward.

The good news is you don't need to give up on REST to address these challenges. In this guide, I'll walk you through how to design RESTful APIs that clearly communicate business intent. We'll start by choosing which resources to expose, then move on to modeling more complex operations as your API grows.

By the end, you'll have a practical framework you can apply to your next RESTful API design.

Choose Your Resources Carefully

RESTful APIs are built around the concept of resources. A resource is any entity you expose as an endpoint, such as a Customer at /customers or an Invoice at /invoices. Choosing the right resources is essential for designing an API that feels intuitive and communicates intent clearly. If you get this step wrong, your API will be awkward and confusing for consumers.

A common pitfall is to expose every table in your database as a resource. Unless you're building a simple CRUD API, this approach usually leads to problems. Not all entities in your database are equal. Some are primary entities with their own lifecycles, while others only exist as part of a parent entity.

Consider a billing system that has two entities: Invoices and InvoiceLineItems. A naive, database-oriented approach would be to map each entity to its own root-level endpoint:

GET    /invoices/{invoice_id}
GET    /invoice-lines/{line_id}
PATCH  /invoice-lines/{line_id}
DELETE /invoice-lines/{line_id}

This flat structure introduces several problems.

First, it breaks encapsulation. A line item can't exist on its own; it always belongs to an invoice. With this URI structure, that relationship is hidden. There's no way to tell which invoice a line item belongs to just by looking at the endpoint. This also complicates authorization, since you now need extra logic to check whether the caller has permission to access the parent invoice for a given line item.

Second, it hides important business rules. For example, once an invoice is finalized, it should be locked, and no further changes should be allowed, including changes to its line items. If line items are exposed as root resources, it suggests they have their own lifecycle and can be changed at any time, regardless of the invoice's state. This can lead to confusion and errors.

Stripe avoids these problems by only ever exposing line items as a sub-resource on an invoice:

GET /v1/invoices/{invoice_id}/lines

There's no /invoice-lines endpoint for fetching, updating, or deleting line items directly. All operations must go through the parent invoice. By nesting line items under invoices, the URI makes the relationship between the two entities clear.

This design brings additional benefits. Your authorization middleware can extract the invoice ID from the URL and check access before the request reaches your business logic. Validation can also check the invoice's state and reject changes if the invoice is finalized. API consumers can immediately see the relationship between invoices and line items just by reading the URL.

📐 Principle 1
Identify the primary entities in your domain and expose them as root-level resources. You should then scope every other entity as a sub-resource of its parent. If an entity can't exist without another, the URI should reflect that dependency.

Break Resources Into Sub-Resources

Once you have identified your main resources, take a closer look to see if any can be broken down further. Sometimes, even if a resource matches a single database table, there are groups of fields that represent a separate concept and are usually read or updated together.

When you spot these groupings, consider breaking them out into their own sub-resources. This makes your API much more intuitive. Instead of sending generic updates to the parent resource, where the intent can be lost in the request body, API consumers can use a dedicated endpoint that clearly shows what they are trying to do.

GitHub's REST API does this well with repository Pages configuration. A repository has core settings, its name, description, visibility, whether issues are enabled, merge strategies, etc. These are all managed through a single endpoint:

PATCH /repos/{owner}/{repo}
{
    "description": "An updated description",
    "homepage": "https://example.com",
    "has_issues": true,
    "allow_squash_merge": true
}

GitHub also lets you host a dedicated website for your repository using GitHub Pages. Setting this up involves a different set of fields: the source branch for the website, the directory to publish from, and an optional custom domain. Since each repository can only have one Pages site, you might be tempted to include these fields on the main resource:

PATCH /repos/{owner}/{repo}
{
    "description": "An updated description",
    "pages_source_branch": "main",
    "pages_source_path": "/docs",
    "pages_cname": "www.example.com"
}

The problem is that these are two separate processes. Updating a repository's core settings is not the same as configuring GitHub Pages. If you combine them, the server has to inspect every PATCH request to decide whether to trigger a Pages deployment or just update the repository's description. This also hides the intent from anyone reading the request URL.

GitHub avoids this by breaking Pages out into its own sub-resource:

POST   /repos/{owner}/{repo}/pages
GET    /repos/{owner}/{repo}/pages
PUT    /repos/{owner}/{repo}/pages
DELETE /repos/{owner}/{repo}/pages

This way, configuring a Pages site becomes a focused, self-contained call:

PUT /repos/{owner}/{repo}/pages
{
    "source": {
        "branch": "main",
        "path": "/docs"
    },
    "cname": "www.example.com"
}

The request above makes the intent much clearer. The business process is obvious from the URI: you are updating the Pages site for the repository. The server-side endpoint is also simpler, since it only needs to validate fields related to Pages.

💡 Sub-Resources vs. Query Parameters
A common point of confusion when organizing child entities is deciding between a sub-resource path (`GET /invoices/{invoice_id}/payments`) and a query parameter (`GET /payments?invoice_id={invoice_id}`). It boils down to context and global relevance. If a child entity strictly belongs to its parent and you will only ever access it through that parent's context, use a sub-resource. However, if the entity needs to be queried globally, for example, if an accounting team needs to search across all payments regardless of which invoice they belong to, it should be a root-level resource. In that case, use query parameters to filter the global list down to a specific parent ID.

💡 Sub-Resources vs. Query Parameters

A common point of confusion when organizing child entities is deciding between a sub-resource path (GET /invoices/{invoice_id}/payments) and a query parameter (GET /payments?invoice_id={invoice_id}).

It boils down to context and global relevance. If a child entity strictly belongs to its parent and you will only ever access it through that parent's context, use a sub-resource. However, if the entity needs to be queried globally, for example, if an accounting team needs to search across all payments regardless of which invoice they belong to, it should be a root-level resource. In that case, use query parameters to filter the global list down to a specific parent ID.

📐 Principle 2
Look for groups of fields on a resource that serve a different purpose or process from the rest. If updating those fields is a distinct action (i.e., performed by different people, done at different times, or for different reasons), promote them to a sub-resource with its own URI.

Model Actions as Sub-Resources

At this point, you've identified your resources and sub-resources. So far, everything fits neatly into standard CRUD operations: create, read, update, and delete. But what if you need to support actions that go beyond these basics?

Many business processes require actions beyond simple field updates. For example, a customer might pay an invoice, or an admin might issue a refund. These aren't simple field updates. They're events that happen to a resource, often with their own data and side effects.

PayPal's Invoicing API handles this well. Consider what happens when a customer pays an invoice. A naive approach might model this as a status update:

PATCH /v2/invoicing/invoices/{invoice_id}
{
    "status": "paid",
    "payment_method": "bank_transfer",
    "amount": 150.00
}

The approach above has several drawbacks. First, the request URL suggests you're just updating the invoice, but the fact that you're recording a payment is hidden in the request body. The server has to inspect every request to determine whether a payment's being made and which side effects to trigger. This method also only supports single payments, even though invoices can often be paid in multiple installments.

PayPal avoids this by turning the action of paying an invoice into a noun and modeling it as a sub-resource:

POST /v2/invoicing/invoices/{invoice_id}/payments
{
    "method": "BANK_TRANSFER",
    "amount": {
        "currency_code": "USD",
        "value": "150.00"
    }
}

Now, the intent is clear from the request URL, and the server-side logic only needs to handle payments. Using a POST to this endpoint also makes it clear that you can record multiple payments for the same invoice.

This approach encourages you to think of a payment not as an update to the invoice's status, but as creating a new payment on the invoice. The verb 'pay' becomes the noun 'payment.' Once you identify this noun, you may realize it deserves its own data model, with its own fields, history, and lifecycle.

You can also apply this technique to actions that only happen once. For example, if an invoice needs to be approved before being sent, you can model this state change with the following endpoint:

PUT /v2/invoicing/invoices/{invoice_id}/approval
{
    "notes": "Reviewed and approved."
}

Notice how the example uses a PUT request. This is because an invoice can only be approved once. The PUT verb signals that this action is idempotent: if you try to approve an invoice that is already approved, nothing changes.

A good example of this in action is the GitHub REST API, which uses PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge to merge a PR. The PUT method clearly indicates that this can be done only once. Sending the same request again won't create multiple merges.

📐 Principle 3
When modeling custom actions on a resource, try to identify a noun to represent that action and then map it as a sub-resource. Use the `POST` verb if calling the same endpoint is not idempotent, meaning it triggers the action with every call. If an endpoint is idempotent and produces no additional changes when called multiple times, the `PUT` verb can convey this.

Promote Complex Actions to Root-Level Resources

The previous approach works well when an action is tied to a single resource. But sometimes, an action doesn't fit neatly under one resource and instead coordinates several resources at once. If you try to attach such an action as a sub-resource, the API becomes awkward. The action is larger than its parent, and the URI doesn't make this clear.

Consider sending money internationally. You need to lock in an exchange rate with a quote, define the recipient, and then actually execute the transfer. You could try modeling this as a sub-resource on one of the entities involved:

POST /v1/quotes/{quote_id}/execute

This doesn't feel right. A quote is just a snapshot of an exchange rate; it's not something you execute. The real action is the transfer itself.

Wise's API models this particular action as a root-level resource: a transfer. Take a look at their endpoint implementation:

POST /v1/transfers
{
    "targetAccount": 12345678,
    "quoteUuid": "4da8f7f2-6f73-4dad-b1dd-0a5e67bf2fc1",
    "customerTransactionId": "b07d1633-60ef-4852-bd8e-1a321b8f25c4",
    "details": {
        "reference": "Invoice 12345"
    }
}

The transfer refers to the quote and the recipient, but it's not a child of either. It's an entity with its own ID, status, and lifecycle. You can retrieve it later using GET /v1/transfers/{transfer_id}. It also appears in both the sender's and receiver's transaction history.

A helpful way to decide whether an action should be its own root-level resource is to consider how people refer to it in the business. If you say things like 'check the status of transfer X,' 'cancel order Y,' or 'look up booking Z,' you're talking about root-level entities. If you say 'close the customer's account,' the closure is an action on the customer and should probably be a sub-resource.

📐 Principle 4
When an action doesn't naturally belong to a single parent resource, don't force it into one. If the action can have its own identity, status, and lifecycle, promote it to a root-level resource.

Fall Back to Verbs When Nouns Don't Fit

The last two sections showed how to turn an action verb into a noun, such as turning 'pay' into 'payments.' However, sometimes there's no meaningful noun for a particular action.

In those cases, it's acceptable to use the verb directly.

Stripe's Invoicing API is a good example. They let you void an invoice that's no longer valid and shouldn't be paid. If you try to map this to a noun, you might end up coming up with nouns that actually don't clearly communicate the action anymore.

For example,

POST /v1/invoices/{invoice_id}/voidances

What's a voidance? Most business users wouldn't use that term. They simply refer to the action itself. In this situation, forcing a noun actually makes the API less clear.

To solve this, Stripe just uses the verb directly:

POST /v1/invoices/{invoice_id}/void

This URI clearly conveys the action as business users would describe it.

While this isn't strictly RESTful, leaning more toward an RPC (Remote Procedure Call) design, it is a pragmatic, highly effective alternative when nouns fail. Remember, RESTful principles are meant to help you create a clear API contract. If following them strictly makes your API harder to understand, it's better to make a practical compromise.

If you really don't want verbs in your URI path, you can also consider following Google's AIP-136, which advocates for splitting the URI resource and action with a colon, like this:

POST /v1/invoices/{invoice_id}:void

This is another clear way to add the verb to the URL, and it separates the resource from the action. While this pattern isn't as common as the slash syntax, it's a solid alternative you can consider.

📐 Principle 5
Not every action has a noun hiding behind it. If a noun doesn't clearly communicate the action anymore, just stick to the verb.

Conclusion

The five patterns in this guide give you a set of steps to follow when designing API endpoints. Each pattern is a tool for a specific situation:

Start with your root resources. Identify the main entities in your domain and scope child entities beneath them.
Break out sub-resources when a group of fields on a resource represents a different process from the rest.
Model actions as sub-resources when a verb can become a noun. In these instances, your action will usually have its own data and parameters.
Promote to root-level resources when an action doesn't map neatly to a single resource.
Fall back to the verb when there's no meaningful noun behind a verb.

It's best to follow these steps in order. Start by identifying your high-level resources before moving on to the other steps. Only use verbs in the URI as a last resort, after you've tried all other options.

Remember, your API should communicate business intent to its consumers, not just reflect implementation details. Your API is not simply a wrapper around your database. It's an interface for your business processes.

8 NDepend Rules to Enforce Domain-Driven Design in .NET

Ivan Kahl — Fri, 20 Mar 2026 07:14:00 +0000

Disclosure: NDepend provided a complimentary 1-year license for me to test the software featured in this article.

When you first start implementing Domain-Driven Design (DDD) in your project, you invest considerable effort in clearly defining Bounded Contexts, identifying Aggregates, and ensuring your abstraction layers are properly defined.

Fast-forward six months, however, and you'll likely find your initial structure has degraded. A domain service now calls an ORM directly. Value objects have become mutable. While code reviews catch obvious violations, subtle architectural drift slips through the cracks when reviewers focus on business logic rather than structural rules. These small violations compound, eventually turning your DDD project into a Big Ball of Mud unless you actively prevent it.

The solution is to implement fitness functions, which are automated checks that detect when new code deviates from your DDD principles.

One tool that enables this is NDepend, a powerful .NET static analyzer that integrates with your IDE and code pipelines. It offers CQLinq (Code Query LINQ), which lets you write your own static analysis code rules using LINQ. In this article, you'll learn how to build eight CQLinq rules that enforce DDD patterns for Entities, Value Objects, and Aggregates.

A Brief Overview of NDepend and CQLinq

While NDepend is known as a metrics and quality analyzer, its real power for DDD teams lies in CQLinq, which lets you write custom static analysis rules using LINQ syntax. Think of it as querying your codebase like a database. You can ask "Which entity classes have public setters?" or "Which domain services reference infrastructure assemblies?" and get violations back instantly.

This matters because DDD patterns are harder to enforce than style rules. A linter can check brace placement, but only a custom static analyzer rule can verify that an Aggregate Root holds no direct references to other Aggregates, or that all Value Objects are immutable. These custom rules shift feedback from slow, subjective code reviews to fast, objective build failures.

In the sections that follow, you'll learn how to build eight CQLinq rules, each targeting a specific DDD pattern you can implement in your own codebase.

Protecting Architectural Boundaries

Before you can apply tactical DDD patterns, you must isolate the domain. Whether you use Clean Architecture, Hexagonal Architecture, or a traditional layered approach, a core principle of DDD is that your domain logic must remain pure and free of external concerns, such as infrastructure implementations, UI frameworks, and third-party libraries.

Rule 1: No Third-Party Dependencies in the Domain Layer

The only dependency you might consider having is a seedwork project containing a collection of base interfaces and classes that help you scaffold your domain. Some teams also allow specific, lightweight libraries for foundational patterns, like MediatR for dispatching Domain Events.

For example, consider the following entity in an Insurance.Domain project. It violates the dependency rule by referencing an external library to generate a policy document from directly within an entity:

using Insurance.SharedKernel.Base;
using Insurance.Domain.Common;
using QuestPDF.Fluent;
using QuestPDF.Helpers;
using QuestPDF.Infrastructure;

namespace Insurance.Domain.Aggregates.Policies;

public class Policy : BaseEntity, IAggregateRoot
{
    private readonly List<InsuredItem> _insuredItems = [];

    public string PolicyNumber { get; private set; }
    public Guid CustomerId { get; private set; }
    public PolicyPeriod PolicyPeriod { get; private set; }
    public Coverage Coverage { get; private set; }
    public IReadOnlyCollection<InsuredItem> InsuredItems => _insuredItems.AsReadOnly();

    // Constructor and other methods...

    public byte[] GeneratePolicyDocument()
    {
        return Document.Create(container =>
        {
            container.Page(page =>
            {
                page.Size(PageSizes.A4);
                page.Margin(2, Unit.Centimetre);
                page.PageColor(Colors.White);
                page.DefaultTextStyle(x => x.FontSize(20));

                page.Header()
                    .Text("Policy Document")
                    .SemiBold();

                // Continue building document...
            });
        }).GeneratePdf();
    }
}

This violates the Dependency Inversion Principle by coupling domain logic to a PDF-generation library. The typical solution is to define an IPolicyDocumentGenerator interface in the application layer and implement it in the infrastructure layer, keeping the domain pure.

You can detect such violations using the following CQLinq rule. Notice how you can easily add exceptions like MediatR to the allowedPrefixes array:

// <Name>Domain Project Third-Party Assembly References</Name>
// <Description>
// The Domain project should not depend on any third-party assemblies.
// </Description>
warnif count > 0

// 1. Define the allowed assemblies for the Domain
let allowedPrefixes = new[] { "Insurance.SharedKernel", "Insurance.Domain" }
let systemPrefixes = new[] { "System", "Microsoft", "mscorlib", "netstandard" }

from t in Application.Types
where t.ParentAssembly.Name == "Insurance.Domain" && !t.IsGeneratedByCompiler

// 2. Identify and group illegal types by their parent assembly
let illegalTypeUsages = t.TypesUsed
    .Where(tu => !allowedPrefixes.Any(p => tu.ParentAssembly.Name.StartsWith(p)) && 
                 !systemPrefixes.Any(p => tu.ParentAssembly.Name.StartsWith(p)))
    .GroupBy(tu => tu.ParentAssembly)

where illegalTypeUsages.Any()

// 3. Flatten the results so you see one row per (Domain Type + Illegal Assembly)
from usageGroup in illegalTypeUsages
let assembly = usageGroup.Key
let typesUsedInThisAssembly = usageGroup.Distinct()
let debt = (10 + (typesUsedInThisAssembly.Count() * 2)).ToMinutes().ToDebt()

select new { 
   DomainType = t, 
   IllegalAssembly = assembly, 
   UsedTypes = typesUsedInThisAssembly, 
   Debt = debt,
   Severity = Severity.High 
}

Below is a screenshot showing the violation in NDepend:

Enforcing Entity Encapsulation

Entities are objects defined by a unique identity and a lifecycle. They store state as properties that can only be modified through methods defined on the entity itself. This ensures the entity is always responsible for maintaining its own invariants and preventing invalid states.

The following sections contain CQLinq rules that help enforce entity encapsulation.

Rule 2: Require Private Setters

Entity properties must only be modifiable through domain methods, not by external code. Public setters bypass validation logic, making it trivial to leave an entity in an invalid state.

For example, consider the following entity class, which breaks this rule:

using Insurance.SharedKernel.Base;

namespace Insurance.Domain.Aggregates.Customers;

public class Customer : BaseEntity, IAggregateRoot
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }
    public string PhoneNumber { get; set; }
    public Address Address { get; set; }

    // Constructors and methods...
}

This class exposes public setters for all properties, allowing external code to bypass domain validation entirely.

Here's a CQLinq rule to catch such violations automatically:

// <Name>Entity Properties Must Have Private Setters</Name>
// <Description>
// Entities should protect their state by using private setters,
// forcing state changes through domain methods.
// </Description>

warnif count > 0

// 1. Find all Entity types in the Domain project
from t in Application.Types
where t.ParentAssembly.Name == "Insurance.Domain" &&
      t.DeriveFrom("Insurance.SharedKernel.Base.BaseEntity")

// 2. Flag properties with a non-private, non-protected setter
from p in t.Properties
where p.SetMethod != null && 
      !p.SetMethod.IsPrivate &&
      !p.SetMethod.IsProtected
select new { 
  t, 
  Property = p,
  Issue = "Property has public/internal setter",
  Debt = 10.ToMinutes().ToDebt(),
  Severity = Severity.High
}

Below is a screenshot showing the violations from the Customer entity:

Clicking any result takes you directly to the violation in the code.

Rule 3: Ban Public Parameterless Constructors

When implementing DDD entities in C#, you often need a private parameterless constructor so that libraries like EF Core can rehydrate instances via reflection. However, these constructors should usually never be public since entities typically require initial data via constructor parameters to be valid when used from application code.

Consider this Customer class with a public parameterless constructor:

public class Customer : BaseEntity, IAggregateRoot
{
    public string FirstName { get; private set; }
    public string LastName { get; private set; }
    public string Email { get; private set; }
    public string PhoneNumber { get; private set; }
    public Address Address { get; private set; }

    public Customer()
    {
    }

    // Other methods...
}

The public parameter makes it possible for application code to create a customer with no required information like name and contact details:

var customer = new Customer();
// No name or other details.

Here's a CQLinq rule that detects public parameterless constructors on entities:

// <Name>Entities must not have Public Parameterless Constructors</Name>
// <Description>
// Entities should only expose a non-public constructor for libraries
// like EF Core.
// </Description>
warnif count > 0

// 1. Find all non-abstract Entity types
let entities = Application.Types
    .Where(t => t.DeriveFrom("Insurance.SharedKernel.Base.BaseEntity") && !t.IsAbstract)

// 2. Flag constructors that are public and take no parameters
from t in entities
from c in t.Constructors
where c.IsPublic && c.NbParameters == 0

select new { 
   Entity = t, 
   Constructor = c,
   Issue = "Entity has a public parameterless constructor. This allows creating entities in an invalid/empty state.",
   Debt = 2.ToMinutes().ToDebt(),
   Severity = Severity.Medium
}

Below is a screenshot of the finding in NDepend:

Rule 4: Enforce Immutable Collections

Exposing mutable collection properties in your entities lets consumers call .Add() or .Clear() directly, bypassing the entity's methods. Look at this Policy class:

using Insurance.SharedKernel.Base;
using Insurance.Domain.Common;

namespace Insurance.Domain.Aggregates.Policies;

public class Policy : BaseEntity, IAggregateRoot
{
    public string PolicyNumber { get; private set; }
    public Guid CustomerId { get; private set; }
    public PolicyPeriod PolicyPeriod { get; private set; }
    public Coverage Coverage { get; private set; }
    public List<InsuredItem> InsuredItems { get; private set; }

    // Constructors and other methods...
}

Even though InsuredItems only exposes a public getter, consumers can still manipulate it by calling List<T> methods directly:

// Add an insured item without going through the policy
policy.InsuredItems.Add(anotherInsuredItem);

// Clear all insured items on a policy in the list directly
policy.InsuredItems.Clear();

A better approach is to store the mutable collection in a private field on the entity and expose it only through a read-only collection type, such as IReadOnlyList<T>.

This CQLinq rule flags mutable collection and dictionary properties on entities:

// <Name>Entity properties must use Immutable Collections</Name>
// <Description>
// Entities should always expose collections or dictionaries as immutable types
// so that consumers cannot modify the collection using its API directly.
// </Description>
warnif count > 0

// Common mutable collection types to ban
let mutableCollections = new [] { 
    "System.Collections.Generic.List", 
    "System.Collections.Generic.Dictionary", 
    "System.Collections.Generic.HashSet",
    "System.Collections.ObjectModel.Collection"
}

// Fetch all Entity objects
from t in Application.Types
where t.DeriveFrom("Insurance.SharedKernel.Base.BaseEntity") 
      && !t.IsAbstract

from p in t.Properties

// Check 1: Is it a banned generic type? (e.g., List<string>)
let typeName = p.PropertyType.Name
let isBannedType = mutableCollections.Any(banned => 
    p.PropertyType.FullName != null && p.PropertyType.FullName.StartsWith(banned))

// Check 2: Is it an Array? (e.g., string[])
let isArray = typeName.EndsWith("[]")

where isBannedType || isArray

select new { 
   Entity = t, 
   Property = p,
   Type = p.PropertyType.Name,
   Issue = "Property exposes a mutable collection. Use 'IReadOnlyList<T>', 'IReadOnlyDictionary<TKey, TValue>', 'ImmutableList<T>', or 'IEnumerable<T>'.",
   Debt = 5.ToMinutes().ToDebt(),
   Severity = Severity.High
}

Notice how the rule highlights the InsuredItems violation on Policy:

Enforce Value Object Integrity

Value objects represent objects without identity in DDD. Rather than being defined by an ID, they are defined by the values they hold. This creates two core requirements: immutability (properties cannot change after construction) and value-based equality (two value objects with identical properties must be considered equal, regardless of object identity).

In C#, you can implement value objects as records (which provide immutability and structural equality automatically) or as classes with proper encapsulation and equality overrides. Either way, the pattern requirements must be enforced consistently throughout your domain.

Rule 5: Prevent Mutable Fields and Properties on Value Objects

Value objects must never expose mutable state, whether through fields or properties. Immutability must be enforced at all levels. Any public or unencapsulated field can be modified directly, and any property with a setter can be changed after construction.

Breaking the immutability of a value object in DDD can lead to an unpredictable domain. Since value objects are often shared and passed around as parameters, making them mutable means that changing the state of a value object in one part of your application might inadvertently change the state of other entities that also reference that particular value object. This can lead to side effects that are difficult to trace.

Consider this Money value object, which violates immutability in multiple ways:

using Insurance.SharedKernel.Base;

namespace Insurance.Domain.Common;

public class Money : IValueObject
{
    public string Currency;  // Public field - anyone can change this!
    public decimal Amount { get; set; }  // Public setter - mutable!

    public Money(decimal amount, string currency)
    {
        if (amount < 0)
            throw new ArgumentException("Amount cannot be negative.", nameof(amount));

        if (string.IsNullOrWhiteSpace(currency))
            throw new ArgumentException("Currency is required.", nameof(currency));

        Amount = amount;
        Currency = currency;
    }

    // Equals() and GetHashCode()...
}

Now, external code can mutate this value object despite your constructor validations:

var salary = new Money(50000, "USD");
salary.Currency = "EUR";  // Changed the currency without validation!
salary.Amount = -75000;    // Changed the amount directly!

This CQLinq rule flags mutable (non-readonly) fields and properties with setters on value objects:

// <Name>Value Objects must not expose mutable fields or properties</Name>
// <Description>
// Value objects should only expose immutable state through read-only properties.
// Any public/internal fields, mutable (non-readonly) fields, or properties with setters break immutability.
// </Description>
warnif count > 0

let valueObjects = Application.Types.Where(t => 
    t.Implement("Insurance.SharedKernel.Base.IValueObject") 
    && !t.IsAbstract)

from t in valueObjects
// Flatten fields and properties into a single stream of violations
from m in t.Members.Where(m => 
    (m is IField && !m.IsGeneratedByCompiler && (m.IsPublic || m.IsInternal || !((IField)m).IsInitOnly)) ||
    (m is IProperty && ((IProperty)m).SetMethod != null && !((IProperty)m).SetMethod.IsPrivate)
)

select new { 
   ValueObject = t, 
   Member = m,
   Issue = m is IField ? 
           (m.IsPublic ? "Public field" : m.IsInternal ? "Internal field" : "Mutable field") :
           "Property has a setter. Value objects must be immutable.",
   Recommendation = m is IField ? 
           "Make the field readonly and expose via a read-only property." :
           "Remove the setter or change it to 'private set;' or 'init;'.",
   Severity = Severity.High,
   Debt = 5.ToMinutes().ToDebt()
}

Below is a screenshot showing the violation:

Rule 6: Enforce Structural Equality on Value Objects

Because value objects are defined by their values rather than identity, two value objects with identical properties must be considered equal. With C# records, this equality is automatic. When implementing value objects as classes, however, you must override Equals() and GetHashCode() to enable value-based comparison.

Look at this PolicyPeriod class, which lacks proper value equality:

using Insurance.SharedKernel.Base;

namespace Insurance.Domain.Aggregates.Policies;

public class PolicyPeriod : IValueObject
{
    public DateTime StartDate { get; private set; }
    public DateTime EndDate { get; private set; }

    public bool IsActive => DateTime.UtcNow >= StartDate && DateTime.UtcNow <= EndDate;
    public int DurationInDays => (EndDate - StartDate).Days;

    public PolicyPeriod(DateTime startDate, DateTime endDate)
    {
        if (endDate <= startDate)
            throw new ArgumentException("End date must be after start date.");

        StartDate = startDate;
        EndDate = endDate;
    }

    // Missing Equals() and GetHashCode() implementations!
}

Without these overrides, the class uses reference equality. Here's what happens:

var period1 = new PolicyPeriod(new DateTime(2026, 1, 1), new DateTime(2027, 1, 1));
var period2 = new PolicyPeriod(new DateTime(2026, 1, 1), new DateTime(2027, 1, 1));

// Identical values, but comparisons fail
if (period1.Equals(period2)) // false: different memory objects
{
    Console.WriteLine("Periods are equal");
}

// Collections break too
var periods = new HashSet<PolicyPeriod> { period1 };
periods.Contains(period2); // false: values are identical but objects differ

This CQLinq rule detects value objects lacking proper equality:

// <Name>Value Objects must implement structural equality</Name>
// <Description>
// Non-record value objects must override Equals() and GetHashCode() 
// to ensure value-based equality comparisons work correctly.
// </Description>
warnif count > 0

// Find all value objects that are implemented as classes
let valueObjects = Application.Types.Where(t => 
    t.Implement("Insurance.SharedKernel.Base.IValueObject") 
    && !t.IsAbstract
    && !t.IsRecord)

// Determine if any of the value objects are missing an overridden Equals or
// GetHashCode method.
from t in valueObjects
let hasEqualsOverride = t.Methods.Any(m => m.Name == "Equals")
let hasHashCodeOverride = t.Methods.Any(m => m.Name == "GetHashCode")

where !hasEqualsOverride || !hasHashCodeOverride

select new { 
   ValueObject = t, 
   MissingEquals = !hasEqualsOverride,
   MissingHashCode = !hasHashCodeOverride,
   Issue = "Value Object does not implement structural equality. Override both Equals() and GetHashCode().",
   Recommendation = "Either make this a 'record' or implement Equals() and GetHashCode() to compare by value.",
   Severity = Severity.High,
   Debt = 10.ToMinutes().ToDebt()
}

This rule targets only non-record value objects, since records provide structural equality automatically. For class-based value objects, missing implementations are flagged as high-severity violations.

Here's what this violation looks like in NDepend:

Enforcing Aggregate Root Consistency

Aggregate roots must maintain clear boundaries and control read/write access to their internal state. This ensures the aggregate root doesn't cause side effects on other entities, and that external code cannot directly modify its state.

Rule 7: Aggregate Roots Should Have Behavioural Methods

Anemic entities are classes with only data properties and no methods. They signal a design where external services validate and modify entity data. In DDD, entities are responsible for validating and updating their own state, meaning aggregate roots should contain methods to modify state rather than just expose properties.

When a class implements IAggregateRoot, it declares itself as a transactional boundary for state mutations. An IAggregateRoot with no behavioral methods is almost certainly an Anemic Domain Model. If the class exists only to represent data for a CQRS read query, it's a Read Model (or DTO) and should not implement IAggregateRoot at all.

This Claim class has a mutable state but defines no methods to manage it:

using Insurance.SharedKernel.Base;
using Insurance.Domain.Common;

namespace Insurance.Domain.Aggregates.Claims;

public class Claim : BaseEntity, IAggregateRoot
{
    public string ClaimNumber { get; private set; }
    public Guid PolicyId { get; private set; }
    public ClaimStatus Status { get; private set; }
    public DateTime FiledDate { get; private set; }

    private readonly List<ClaimItem> _claimItems = [];
    private readonly List<AdjusterNote> _adjusterNotes = [];

    public IReadOnlyCollection<ClaimItem> ClaimItems => _claimItems.AsReadOnly();
    public IReadOnlyCollection<AdjusterNote> AdjusterNotes => _adjusterNotes.AsReadOnly();

    public Claim(string claimNumber, Guid policyId)
    {
        if (string.IsNullOrWhiteSpace(claimNumber))
            throw new ArgumentException("Claim number is required.", nameof(claimNumber));

        if (policyId == Guid.Empty)
            throw new ArgumentException("Policy ID is required.", nameof(policyId));

        ClaimNumber = claimNumber;
        PolicyId = policyId;
        Status = ClaimStatus.Pending;
        FiledDate = DateTime.UtcNow;
    }
}

This CQLinq rule flags such violations:

// <Name>Aggregate Roots should have Public Behavioral Methods</Name>
warnif count > 0

// 1. Identify Aggregate Roots (Adjust the string to match your base interface/class)
let aggregateRoots = Application.Types
    .Where(t => t.Implement("Insurance.SharedKernel.Base.IAggregateRoot") 
             && !t.IsAbstract 
             && !t.IsInterface)

from t in aggregateRoots

// 2. Filter for "Real" Public Methods (Behavior)
// We exclude constructors, property accessors, and standard object overrides.
let publicBehaviorMethods = t.Methods.Where(m => 
    m.IsPublic && 
    !m.IsConstructor && 
    !m.IsPropertyGetter && 
    !m.IsPropertySetter && 
    !m.IsOperator && 
    !m.IsStatic &&
    // Exclude standard object overrides as they don't count as "Domain Logic"
    m.Name != "ToString" && 
    m.Name != "GetHashCode" && 
    m.Name != "Equals" &&
    m.Name != "GetType"
)

// 3. The Violation Condition:
// If the count is 0, the Aggregate Root is just a data structure.
where publicBehaviorMethods.Count() == 0

select new { 
   AggregateRoot = t, 
   Issue = "Aggregate Root has no public behavioral methods. It appears to be an Anemic Domain model.",
   Recommendation = "Encapsulate logic by adding public methods (e.g., 'Activate()', 'Cancel()') instead of relying on services to manipulate properties.",
   Severity = Severity.Medium,
   Debt = 30.ToMinutes().ToDebt()
}

Here's a screenshot of the query results showing the Claim:

Rule 8: Aggregate Roots Should Reference Other Aggregates by ID Only

Each aggregate root is a consistency boundary, meaning it owns and controls everything inside it. When one aggregate root holds a direct object reference to another, you risk loading and modifying both within a single transaction, blurring boundaries and creating unintended coupling. Referencing by ID keeps boundaries clean: to work with another aggregate, load it separately through its own repository.

If you're using an ORM like EF Core, you might be tempted to ignore this rule. EF Core navigation properties make it easy to link aggregates together and manage foreign keys behind the scenes. However, this convenience is exactly what leads to issues such as accidental lazy-loading, large memory footprints from eager loading, and the modification of multiple aggregates in a single database transaction. By enforcing ID-only references, you force developers to load other aggregates separately, preserving performance and transactional boundaries.

This Claim class violates the rule by holding a direct reference to Policy instead of storing its ID:

using Insurance.SharedKernel.Base;
using Insurance.Domain.Common;
using Insurance.Domain.Aggregates.Policies;

namespace Insurance.Domain.Aggregates.Claims;

public class Claim : BaseEntity, IAggregateRoot
{
    public string ClaimNumber { get; private set; }
    public Policy Policy { get; private set; }
    public ClaimStatus Status { get; private set; }
    public DateTime FiledDate { get; private set; }

    private readonly List<ClaimItem> _claimItems = [];
    private readonly List<AdjusterNote> _adjusterNotes = [];

    public IReadOnlyCollection<ClaimItem> ClaimItems => _claimItems.AsReadOnly();
    public IReadOnlyCollection<AdjusterNote> AdjusterNotes => _adjusterNotes.AsReadOnly();

    // Constructors and methods...
}

This CQLinq rule detects such violations by scanning aggregate root properties for direct references to other aggregate roots:

// <Name>Aggregate Roots should reference other Aggregates by ID only</Name>
warnif count > 0

// 1. Identify all Aggregate Roots
let aggregateRoots = Application.Types
    .Where(t => t.Implement("Insurance.SharedKernel.Base.IAggregateRoot") 
             && !t.IsAbstract)

from t in aggregateRoots
from p in t.Properties

// 2. Check if the Property Type is an Aggregate Root
// This includes the type itself
let propertyType = p.PropertyType
where aggregateRoots.Contains(propertyType)

select new { 
   AggregateRoot = t, 
   Property = p,
   ReferencedType = propertyType,
   Issue = propertyType == t 
       ? "Self-Reference: Aggregate Root holds a reference to itself. Use an ID (e.g., ParentId) to avoid deep recursion."
       : "Cross-Aggregate Reference: Aggregate Root holds a hard reference to another Aggregate. Use an ID to keep boundaries clean.",
   Recommendation = "Replace property '" + p.Name + "' with '" + p.Name + "Id'.",
   Severity = Severity.High,
   Debt = 1.ToHours().ToDebt()
}

The screenshot below shows how the Policy property violation is identified:

Conclusion

Implementing DDD is an investment in long-term maintainability. However, ensuring the design is preserved over time is a challenge. This article explored eight powerful CQLinq rules you can use to safeguard your domain.

These rules act as fitness functions, which monitor your project's overall structure with every change. By integrating these NDepend rules into your CI/CD pipeline, you can quickly fail builds that violate DDD principles.

Start by auditing your current codebase against one or two of these rules today. As you resolve the most painful violations, you’ll see your "Big Ball of Mud" begin to transform back into a clean, expressive Domain Model.

Decompiling the New C# 14 field Keyword

Ivan Kahl — Mon, 05 Jan 2026 11:00:00 +0000

Properties in C# are a powerful tool for encapsulating data inside a class. They let you specify getter and setter logic that’s automatically applied when reading from or writing to the property. They’ve been supported since C# 1.0, which required manual backing fields for storage. C# 3.0 then introduced auto-implemented properties to remove these boilerplate backing fields. However, it came with a trade-off: if you needed custom logic in your get or set method, you still had to use a manual backing field.

C# 14 introduces the new field keyword, which combines the flexibility of a manual backing field with the simplicity of an auto-implemented property. In the sections that follow, you'll see how the compiler handles this new keyword in practice. We'll also cover some important caveats to keep in mind as you start using it.

A Brief Overview of the `field` Keyword

Before C# 14, backing fields were necessary whenever a property needed logic beyond just retrieving and setting a field value. The snippet below demonstrates how a manual backing field is required for the Email property, since it cleans up the incoming value before storing it:

public class User
{
    // Auto-property: simple getter and setter
    public string Name { get; set; }

    // Field-backed property: more complex getter and setter
    private string _email;
    public string Email
    {
        get => _email;
        set => _email = value.Trim().ToLower();
    }

    public User(string name, string email)
    {
        Name = name;
        Email = email;
    }
}

Auto-implemented properties are convenient for simple scenarios, but as shown above, they fall short when you attempt to add custom logic. The new field keyword in C# 14 fills this gap. It lets you keep your code concise, while still allowing for custom logic in your property accessors.

The above snippet can be simplified in C# 14 as follows:

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

-   private string _email;
    public string Email
    {
-       get => _email;
+       get;
-       set => _email = value.Trim().ToLower();
+       set => field = value.Trim().ToLower();
    }

    public User(string name, string email)
    {
        Name = name;
        Email = email;
    }
}

Notice how the manual backing field is no longer needed. But what actually happens behind the scenes? In the next section, we'll look at the disassembled Intermediate Language (IL) code to see exactly how the compiler handles the field keyword.

Inspecting the IL Code

To demonstrate how the compiler handles different implementations of properties, we’ll use SharpLab to examine the following code snippet, which contains a standard auto-implemented property (Name), a manual backing field (Email), and the new C# 14 property implementation (Username):

public class User
{
    // Auto-property: simple getter and setter
    public string Name { get; set; }

    // Field-backed property: more complex getter and setter
    private string _email;
    public string Email
    {
        get => _email;
        set => _email = value.Trim().ToLower();
    }

    // New C# 14 'field' property
    public string Username
    {
        get => field;
        set => field = value.Trim().ToLower();
    }
}

You can view the compiler-generated code for this example on SharpLab. When you examine the IL code, you'll see how a property using the field keyword is very similar to an auto-implemented property behind the scenes.

Identical Backing Fields

When you use the field keyword, the compiler automatically creates a private backing field. This generated field is identical to what you'd get with a standard auto-implemented property.

Here is the IL code for the standard auto-implemented property, Name:

.field private string '<Name>k__BackingField'
.custom instance void [System.Runtime]System.Runtime.CompilerServices.CompilerGeneratedAttribute...
.custom instance void [System.Runtime]System.Diagnostics.DebuggerBrowsableAttribute...

And here’s the IL code for the C# 14 field property, Username:

.field private string '<Username>k__BackingField'
.custom instance void [System.Runtime]System.Runtime.CompilerServices.CompilerGeneratedAttribute...
.custom instance void [System.Runtime]System.Diagnostics.DebuggerBrowsableAttribute...

In both cases, the compiler takes the same approach:

It uses the same <Property>k__BackingField naming format for the underlying field name. The angle brackets make the name illegal in C# source code, preventing naming conflicts between user code and compiler-generated code.
It adds the CompilerGenerated attribute to mark the field as an artifact of the build process.
It adds the DebuggerHidden attribute to hide the field in the debug window.

The Getter Implementation

All three properties have simple get implementations that return the underlying field value. If you look at the IL code for each, you'll see they're essentially the same, except that the Email property uses the manual _email field, while the others use a compiler-generated field.

Here’s the get method for the Email property, which uses a manual backing field:

.method public hidebysig specialname instance string get_Email () cil managed 
{
    // ...
    IL_0000: ldarg.0
    IL_0001: ldfld string User::_email
    IL_0006: ret
}

And here’s the get method for the Username property, which uses the field keyword:

.method public hidebysig specialname instance string get_Username () cil managed 
{
    // ...
    IL_0000: ldarg.0
    IL_0001: ldfld string User::'<Username>k__BackingField'
    IL_0006: ret
}

Both sets of instructions do the same thing: they load the value from the backing field and return it. The only difference is which field is used to store the value.

The Setter Implementation

How about the set method implementation? Both the Username and Email properties perform processing on the incoming value before storing it.

Here’s the IL code for setting the Email property, which uses a backing field:

.method public hidebysig specialname instance void set_Email (string 'value') cil managed 
{
    // ...
    IL_0000: ldarg.0
    IL_0001: ldarg.1
    IL_0002: callvirt instance string [System.Runtime]System.String::Trim()
    IL_0007: callvirt instance string [System.Runtime]System.String::ToLower()
    IL_000c: stfld string User::_email
    IL_0011: ret
}

Then, here’s the set method for the Username property:

.method public hidebysig specialname instance void set_Username (string 'value') cil managed 
{
    // ...
    IL_0000: ldarg.0
    IL_0001: ldarg.1
    IL_0002: callvirt instance string [System.Runtime]System.String::Trim()
    IL_0007: callvirt instance string [System.Runtime]System.String::ToLower()
    IL_000c: stfld string User::'<Username>k__BackingField'
    IL_0011: ret
}

In both code snippets:

The method loads the current class instance onto the stack
It then loads the incoming value parameter on the stack
It performs the processing on the value parameter, in this case, trimming the string and converting it to lowercase
It updates the underlying field with the processed value.

This shows that the field keyword is purely syntactic sugar. When you compile your code, it produces the same underlying IL code as manual and auto-implemented properties.

Potential Pitfalls to Consider When Refactoring to the `field` Keyword

Before you start refactoring your codebase to use the new keyword, there are a few important caveats to keep in mind. While the underlying IL code is essentially the same, how your code accesses the backing field can affect your application in subtle ways.

Magic Strings and Reflection Will Break

If you use reflection to access private members, removing manual backing fields in favour of compiler-generated fields will break reflection. This is because the underlying field name changes. As shown above, the compiler uses a mangled naming convention, such as <Property>k__BackingField, for compiler-generated fields. If your code, or libraries you use, rely on finding a specific private field by name via reflection, it will crash at runtime when you refactor your code.

The sections below highlight two common scenarios where reflection might cause issues: Entity Framework Core and AutoMapper.

Entity Framework Core

EF Core supports writing to private fields in a class using reflection so that you can bypass logic in your property’s set method when hydrating the entity.

For example, say you refactor your EF Core model class by utilizing the field keyword:

public class OrderLineItem
{
-   private int _quantity;

    // …
    public int Quantity
    {
-       get => _quantity;
+       get;
        set
        {
            ArgumentOutOfRangeException.ThrowIfNegativeOrZero(value);
-           _quantity = value;
+           field = value;
        }
    }
}

If your EF Core configuration class references the field by name, it will fail since the field doesn’t exist anymore with that name:

public class OrderLineItemConfiguration : IEntityTypeConfiguration<OrderLineItem>
{
    public void Configure(EntityTypeBuilder<OrderLineItem> builder)
    {
        // …

        builder.Property(p => p.Quantity)
            .HasColumnName("quantity")
            .HasField("_quantity");

        // ...
    }
}

Here’s an example of the exception you can expect to see in this scenario, which reports that EF Core cannot find the underlying field for the property.

System.InvalidOperationException: The specified field '_quantity' could not be found for property 'OrderLineItem.Quantity'.
   at Microsoft.EntityFrameworkCore.Metadata.Internal.PropertyBase.GetFieldInfo(String fieldName, TypeBase type, String propertyName, Boolean shouldThrow)
   at Microsoft.EntityFrameworkCore.Metadata.Internal.InternalPropertyBaseBuilder`2.CanSetField(String fieldName, Nullable`1 configurationSource)
   at Microsoft.EntityFrameworkCore.Metadata.Internal.InternalPropertyBaseBuilder`2.HasField(String fieldName, ConfigurationSource configurationSource)
   at Microsoft.EntityFrameworkCore.Metadata.Internal.InternalPropertyBuilder.HasField(String fieldName, ConfigurationSource configurationSource)
   at Microsoft.EntityFrameworkCore.Metadata.Builders.PropertyBuilder.HasField(String fieldName)
   at Microsoft.EntityFrameworkCore.Metadata.Builders.PropertyBuilder`1.HasField(String fieldName)
   at EfCoreFields.OrderLineItemConfiguration.Configure(EntityTypeBuilder`1 builder) in C:\Code\EfCoreFields\EfCoreFields\OrderLineItemConfiguration.cs:line 16
   at Microsoft.EntityFrameworkCore.ModelBuilder.ApplyConfiguration[TEntity](IEntityTypeConfiguration`1 configuration)
   at InvokeStub_ModelBuilder.ApplyConfiguration(Object, Span`1)
   at System.Reflection.MethodBaseInvoker.InvokeWithOneArg(Object obj, BindingFlags invokeAttr, Binder binder, Object[] parameters, CultureInfo culture)

This error only appears at runtime and not build time, so you’ll have to carefully update your EF Core entity configuration files as you refactor your model classes.

Fortunately, fixing your EF Core configuration classes is straightforward. Instead of looking for the backing field by name, you instruct it always to access the property using its underlying backing field with the UsePropertyAccessMode method:

public class OrderLineItemConfiguration : IEntityTypeConfiguration<OrderLineItem>
{
    public void Configure(EntityTypeBuilder<OrderLineItem> builder)
    {
        // …

        builder.Property(p => p.Quantity)
            .HasColumnName("quantity")
-           .HasField("_quantity");
+           .UsePropertyAccessMode(PropertyAccessMode.Field);

        // ...
    }
}

This approach avoids hardcoding a field name. By removing HasField, EF Core reverts to its default conventions, which are capable of locating the compiler-generated backing field. The UsePropertyAccessMode method then ensures EF Core uses the located field rather than the property.

AutoMapper

A similar issue exists when using object mappers that rely on reflection, such as AutoMapper. For example, consider the following class, which has been refactored to use the field keyword:

public class Product : AuditableEntity
{
-   private decimal _price;

    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price
    {
-       get => _price;
+       get;
        set
        {
            AuditPropertyChanged("Price", field, value);
-           _price = value;
+           field = value;
        }
    }
}

It’s possible that your AutoMapper Profile class still refers to the old field by name, which will cause issues:

public class ProductProfile : Profile
{
    public ProductProfile()
    {
        ShouldMapField = fi => !fi.IsDefined(typeof(System.Runtime.CompilerServices.CompilerGeneratedAttribute));

        CreateMap<CreateProductDto, Product>()
            // Hard-coded field name in the string below
            .ForMember("_price", opt => opt.MapFrom(src => src.Price))
            .ForMember(dest => dest.Name, opt => opt.MapFrom(src => src.Name));
    }
}

Whenever you try to map objects or validate your configuration, you’ll run into an exception similar to this:

System.ArgumentOutOfRangeException: Cannot find member _price of type AutoMapperFields.Product. (Parameter 'name')
   at AutoMapper.Internal.TypeExtensions.GetFieldOrProperty(Type type, String name)
   at AutoMapper.Configuration.MappingExpression`2.ForMember(String name, Action`1 memberOptions)
   at AutoMapperFields.ProductProfile..ctor() in C:\Code\AutoMapperFields\ProductProfile.cs:line 12
   at System.RuntimeType.CreateInstanceDefaultCtor(Boolean publicOnly, Boolean wrapExceptions)

The best solution I’ve found for finding reflection-based mapping issues is to assert your mappings at application startup. That way, you can find invalid mapping configurations as soon as your application starts, rather than when the actual mapping occurs.

var app = builder.Build();

// …

app.Services.GetRequiredService<IMapper>().ConfigurationProvider.AssertConfigurationIsValid();

// …

await app.RunAsync();

If you want to avoid this issue altogether, consider using a source generator library like Mapster. That way, mapping issues can be caught at build time rather than at runtime.

Be cautious when using magic strings and reflection. These patterns can make your codebase fragile and more likely to break during refactoring, such as switching to using the field keyword.

The `field` Keyword Is Restricted to the Property

When you declare a private backing field, that variable is available throughout the class. The field keyword, on the other hand, is only available inside the property's accessor methods.

This can cause issues if you have methods that need to directly manipulate the underlying field value. For example, take a look at the Reset method in the class below:

public class Counter
{
    private int _count;

    public int Count
    {
        get => _count;
        set
        {
            ArgumentOutOfRangeException.ThrowIfNegative(value);
            _count = value;
        }
    }

    public void Reset()
    {
        _count = 0;
    }
}

When you refactor the class to use the field keyword, you’ll run into the following error if you try set the underlying field value in a method:

The only way to fix this is to use the set method on the property as well:

public class Counter
{
-   private int _count;
-    
    public int Count
    {
-       get => _count;
+       get;
        set
        {
            ArgumentOutOfRangeException.ThrowIfNegative(value);
-           _count = value;
+           field = value;
        }
    }

    public void Reset()
    {
-       _count = 0;
+       Count = 0;
    }
}

In general, this is considered best practice, since it ensures your value is always validated before being stored. But what if your set method has side effects you want to avoid in certain cases?

For example, the following class raises an event every time the FirstName or LastName properties are updated:

public class Customer
{
    private string _firstName;
    private string _lastName;

    public string FirstName
    {
        get => _firstName;
        set
        {
            _firstName = value;
            RaiseEvent(new FirstNameUpdated(Id, _firstName));
        }
    }

    public string LastName
    {
        get => _lastName;
        set
        {
            _lastName = value;
            RaiseEvent(new LastNameUpdated(Id, _lastName));
        }
    }

    public void Anonymize()
    {
        _firstName = "ANONYMIZED";
        _lastName = "ANONYMIZED";
        RaiseEvent(new CustomerAnonymized(Id));
    }
}

If you need to set the first and last name values without triggering side effects in the set method, for example, from an Anonymize method, then you'll need to stick with manual backing fields.

Targeting Fields with Attributes

If you previously applied attributes to your private backing fields, you need to use slightly different syntax when using auto-implemented and field properties. Consider the following code sample, which applies a custom [WatchField] attribute to the backing field.

public class Order
{
    [WatchField]
    private string _deliveryAddress;

    public string DeliveryAddress
    {
        get => _deliveryAddress;
        set
        {
            ValidateDeliveryAddress(value);
            _deliveryAddress = value;
        }
    }

    private void ValidateDeliveryAddress(string address)
    {
        // Validation logic throws exception if invalid.
    }
}

When you refactor the property, you have to use the field: prefix so that the attribute targets the underlying field rather than the property:

public class Order
{
    [field: WatchField]
    public string DeliveryAddress
    {
        get;
        set
        {
            ValidateDeliveryAddress(value);
            field = value;
        }
    }

    private void ValidateDeliveryAddress(string address)
    {
        // Validation logic throws exception if invalid.
    }
}

Notice how the attribute is applied directly to the compiler-generated backing field in the compiled code:

public class Order
{
    [CompilerGenerated]
    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    [WatchField]
    private string <DeliveryAddress>k__BackingField;

    // ...
}

Naming Conflicts with Existing Class Members

The field keyword hasn’t always been a contextual keyword, and you could use it as an identifier in previous versions of C#. For example, the following code compiles in C# 13 and earlier:

class ResearchProject(string field)
{
    private string field = field;

    public string Field
    {
        get => field;
        set => field = value ?? throw new ArgumentNullException(nameof(value));
    }
}

In the snippet above, the field variable used within the Field accessor methods references the private field defined immediately above.

However, when updating your project to use C# 14, you’ll run into the following warning, indicating that using the field keyword inside the accessor will reference a compiler-generated field rather than the existing field member.

To fix this, you can refer to the existing field member using this.field or @field:

class ResearchProject(string field)
{
    private string field = field;

    public string Field
    {
        // Example of using the `this.` syntax to refer to the backing field
-       get => field;
+       get => this.field;
        // Example of using the `@` prefix to avoid naming conflicts
-       set => field = value ?? throw new ArgumentNullException(nameof(value));
+       set => @field = value ?? throw new ArgumentNullException(nameof(value));
    }
}

Conclusion

The field keyword in C# 14 helps you avoid unnecessary boilerplate by removing the need for explicit private backing fields. It lets you use auto-implemented properties even when you need custom logic.

As we inspected the generated IL code, it became clear that the keyword is syntactic sugar. The compiler still generates the same backing field and connects it to your property accessors. However, the abstraction does come with trade-offs, which we unpacked in the second half of the article.

This new feature moves C# toward less verbose code by making auto-implemented properties more flexible. Most codebases will benefit from adopting it. Just remember the caveats, especially if you're working with legacy code or reflection-based libraries. Proceed with caution, and ensure you have good test coverage to catch any issues during refactoring.

Mastering the C# Dispose Pattern

Ivan Kahl — Mon, 13 Oct 2025 11:43:29 +0000

The .NET runtime comes with efficient resource management, helping you build robust applications. It can allocate, manage, and reclaim memory efficiently for objects, helping prevent memory leaks and memory exhaustion. Most cleanup is done automatically. However, there are scenarios where you, as the developer, need to manually clean up unmanaged resources that the runtime cannot see.

This guide will briefly explain how .NET's resource management works and its limitations when it comes to dealing with unmanaged resources. You'll then see how the IDisposable interface can be implemented in different scenarios to ensure resources are cleaned up properly.

Resource Management in .NET

The .NET runtime manages a memory heap for your application's reference types. While the runtime handles the allocation, the Garbage Collector (GC) is responsible for automatically reclaiming memory from objects that are no longer in use. It is also responsible for optimizing memory by compacting the heap. This entire process frees you from manually deallocating memory.

ℹ️ What are Reference Types?
Reference types are any .NET types whose values get stored on the heap instead of the stack. When you assign such a type to a variable, the variable stores a reference to the object on the heap. This is unlike value types, which store the actual value in the variable.

Since the runtime manages the memory for reference types, it's called managed memory. However, applications can often use unmanaged resources. The memory for these resources sits outside the runtime's control and visibility. Such resources can include file handles, database connections, and network sockets. Because it has no visibility of these resources, the GC has no way of compacting or reclaiming this memory automatically. Instead, the class itself needs to release these unmanaged resources to prevent memory leaks.

To solve this problem, .NET provides the IDisposable interface to deterministically cleanup resources. The following section demonstrates a simple IDisposable implementation that is most commonly used.

The Basic Dispose Pattern: A Simple Implementation

In most cases, your classes will work with unmanaged resources that are already wrapped in their own IDisposable classes.

For instance, your class might use the NpgsqlConnection class to establish a connection to a PostgreSQL database. Even though the database connection is an unmanaged resource, the NpgsqlConnection class already implements a Dispose() method to manage those resources. Your class's Dispose() method simply needs to call the database's Dispose() method.

This is demonstrated in the code snippet below:

public class CustomerRepository : IDisposable
{
    private bool _disposed = false;

    private readonly NpgsqlConnection _connection;

    public CustomerRepository(string connectionString)
    {
        _connection = new NpgsqlConnection(connectionString);
        _connection.Open();
    }

    // Methods that use the database connection...

    public void Dispose()
    {
        if (_disposed)
            return;

        _disposed = true;

        // Call the database Dispose() method to handle cleanup
        _connection.Dispose();
    }
}

Notice how the CustomerRepository.Dispose() method makes a call to the underlying database connection to dispose it. Now the unmanaged resource is taken care of. Nothing too complicated!

The _disposed field also keeps track of whether the dispose method has been called already. This is important, since your Dispose() method should always be idempotent, otherwise exceptions might be thrown.

ℹ️ Cascading Dispose() Calls
Whenever your class owns a class that implements IDisposable, it must cascade dispose calls down to those owned objects to ensure proper cleanup.

However, this is not necessary if your class doesn't own the resource (e.g., it was passed in as a dependency in the constructor).

Consuming the `IDisposable` Class

When consuming the class above, you should use the using block as it automatically calls Dispose() for you when you're finished with the object:

using (var repository = new CustomerRepository(_connectionString))
{
    // Use repository here...
} // Calls repository.Dispose() automatically

Notice how the Dispose() method is called as soon as you reach the end of the using block.

You can also remove the block, in which case the Dispose() method will be called when the surrounding code block ends:

private Customer? FindCustomer(int id)
{
    // Create repository with `using var`
    using var repository = new CustomerRepository(_connectionString);

    return repository.Get(id);
} // Calls repository.Dispose() automatically

In the snippet above, the Dispose() method will be called automatically after the function returns.

The Full Dispose Pattern: Handling Unmanaged Resources

The implementation above will suffice for most of your IDisposable implementations. However, there might be times when you're dealing with unmanaged resources directly (i.e., they aren't wrapped in their own IDisposable). In those cases, there are a couple more things to consider in your implementation.

Take a look at the implementation below:

using Microsoft.Win32.SafeHandles;
using System.ComponentModel;
using System.Runtime.InteropServices;

public class UnmanagedFileHandler : IDisposable
{
    // Raw, unmanaged resource pointer
    private IntPtr _handle;

    // Managed resource
    private readonly MemoryStream _buffer;

    private bool _disposed = false;

    // Using a constant for the invalid handle value for clarity.
    private static readonly IntPtr INVALID_HANDLE_VALUE = new(-1);

    // Import the CreateFile function from the Windows API.
    [DllImport("kernel32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
    private static extern IntPtr CreateFile(
        string lpFileName,
        uint dwDesiredAccess,
        uint dwShareMode,
        IntPtr lpSecurityAttributes,
        uint dwCreationDisposition,
        uint dwFlagsAndAttributes,
        IntPtr hTemplateFile);

    // Import the CloseHandle function.
    [DllImport("kernel32.dll", SetLastError = true)]
    [return: MarshalAs(UnmanagedType.Bool)]
    private static extern bool CloseHandle(IntPtr hObject);

    // Constants for file access from the Windows API.
    private const uint GENERIC_WRITE = 0x40000000;
    private const uint CREATE_ALWAYS = 2;
    private const uint NO_SHARING = 0;
    private const uint DEFAULT_ATTRIBUTES = 0;

    public UnmanagedFileHandler(string filePath)
    {
        // Call the unmanaged Windows API to get a file handle.
        _handle = CreateFile(
            filePath,
            GENERIC_WRITE,
            NO_SHARING,
            IntPtr.Zero,
            CREATE_ALWAYS,
            DEFAULT_ATTRIBUTES,
            IntPtr.Zero);

        _buffer = new MemoryStream();

        // Check if the handle is valid. If not, throw an exception.
        if (_handle == INVALID_HANDLE_VALUE)
            throw new Win32Exception(Marshal.GetLastWin32Error(), "Failed to create the file handle.");
    }

    // File methods here...

    public void Dispose()
    {
        Dispose(true);
        GC.SuppressFinalize(this);
    }

    ~UnmanagedFileHandler()
    {
        Dispose(false);
    }

    protected virtual void Dispose(bool disposing)
    {
        if (_disposed)
            return;

        if (disposing)
        {
            // Dispose managed resources if called from Dispose()
            _buffer.Dispose();
        }

        // Always dispose unmanaged resources
        if (_handle != IntPtr.Zero && _handle != INVALID_HANDLE_VALUE)
        {
            CloseHandle(_handle);
            _handle = IntPtr.Zero;
        }

        _disposed = true;
    }
}

That's a bit more code!

First, notice how the class has an IntPtr pointing to a file, which is created using Window's low-level CreateFile method. This pointer is an unmanaged resource that has to be cleaned up manually.

A MemoryStream is also created to act as a buffer. This is another unmanaged resource. However, because the MemoryStream class implements IDisposable, you only need to call the Dispose() method on that field.

There's also a new Dispose(bool disposing) method. It cleans up managed and unmanaged resources. This method can be called from two places in the class: the IDisposable.Dispose() method, or the class finalizer.

ℹ️ What are Finalizers?
Finalizers are another name for destructors in C#. These methods have a simple signature: public ~ClassName() {}

The GC calls the finalizer before reclaiming the object's memory.

When calling the new Dispose(bool disposing) method, the disposing parameter is determined by the origin of the method call:

When called from IDisposable.Dispose(), then disposing is true, meaning both managed and unmanaged resources should be cleaned up.
When called from the finalizer (i.e., ~UnmanagedFileHandler()), then disposing is false, so only unmanaged resources are cleaned up. This is because the GC will finalize the owned managed resources, so no need to Dispose() them ourselves.

GC.SuppressFinalize() is also called on the current object in the Dispose() method. This tells the GC that it does not need to call the finalizer method on this class.

This is necessary for performance reasons, since finalizers are not exactly efficient. When the GC encounters a class with a finalizer that needs to be reclaimed, it first places that finalizer on a queue to execute later. This is to prevent the current GC run from being potentially delayed by calling the finalizer immediately. Once the current GC run is finished, the finalizer is executed. Only after the finalizer is executed does the class become eligible to be reclaimed.

So by suppressing the finalizer on the class, the memory for that class can be immediately reclaimed without waiting for the finalizer to execute first.

Finally, you'll see the Dispose(bool disposing) method is virtual. In the next section, you'll find out why this is necessary when it comes to class inheritance with IDisposable.

Disposing of Inherited Classes

What happens if a class inherits from your IDisposable class and uses its own unmanaged resources? The child class's resources also need to be cleaned up, along with the parent class's resources.

Fortunately, since the Dispose(bool disposing) method is virtual, a child class can execute its own cleanup logic when the class is disposed.

The code snippet below is for a LogFileHandler class, which inherits from the UnmanagedFileHandler class referenced above.

public class LogFileHandler : UnmanagedFileHandler
{
    private bool _disposed = false;

    private readonly MemoryStream _logBuffer;

    public LogFileHandler(string filePath) : base(filePath)
    {
        _logBuffer = new MemoryStream();
    }

    // Log methods here...

    // Override the parent class Dispose method to clean up the additional resource.
    protected override void Dispose(bool disposing)
    {
        if (_disposed)
            return;

        _disposed = true;

        if (disposing)
        {
            // Dispose the additional managed resource
            _logBuffer.Dispose();
        }

        // No unmanaged resources to clean up in this child class

        // Call the base class Dispose method
        base.Dispose(disposing);
    }
}

The LogFileHandler class has its own MemoryStream field, which is used to buffer log messages. This resource implements the IDisposable interface, so the LogFileHandler must override the Dispose(bool disposing) method from the parent class to dispose of the buffer. When overriding the method, the base class Dispose(bool disposing) method must still be called.

Since the Dispose(bool disposing) method is already called from the IDisposable.Dispose() and finalizer in the base class, there's no need to implement them in the LogFileHandler class.

ℹ️ What If I Never Plan On Inheriting?
If your IDisposable class will never be inherited from, mark the class as sealed and remove the virtual flag from the Dispose(bool disposing) method.

Best Practices

When implementing any of the patterns above, keep these things in mind to ensure your disposal logic is robust.

Ensure Idempotency

Calls to Dispose() should always be idempotent to avoid exceptions from being thrown. This can happen if part of disposing of a property sets it to an invalid value (like null):

public void Dispose()
{
    _connection.Dispose();
    _connection = null;
}

If, for any reason, the Dispose() method above is called again, a NullReferenceException will be thrown because _connection was set to null previously.

So it's best to always use a _disposed private field to track if the dispose has already been run:

public void Dispose()
{
    if (_disposed)
        return;

    _disposed = true;

    _connection.Dispose();
    _connection = null;
}

Now the method will return early if it's ever called multiple times.

Don't Throw Exceptions in Finalizers

When implementing a finalizers that dispose resources, it's crucial to avoid throwing any exceptions as they can have unintended side effects, like causing the entire application to crash.

Always write your finalizers as defensively as possible to prevent unhandled exceptions from surfacing.

Cascade Dispose Calls to Owned Resources

Any class that owns resources that implement IDisposable must implement the IDisposable interface and call the Dispose() method on those resources in its own Dispose() method. If not done, owned resources won't be released, which could cause memory leaks.

Always Call Base Class Dispose

If a class inherits from another class implementing IDisposable, make sure you override the Dispose(bool disposing) method to release any unmanaged resources in the inherited class.

Also, always call the base class's Dispose(bool disposing) method from the overridden method.

Use `SafeHandle` to Managed Those Unmanaged Resources

The full Dispose pattern is necessary if your class deals with unmanaged resources directly (i.e., the resources don't have an existing IDisposable wrapper, such as IntPtr). However, the .NET runtime comes with SafeHandle classes that can wrap any raw unmanaged IntPtr in an IDisposable. These wrapper classes manage the pointer for you, meaning your class only needs to implement the Basic Dispose pattern.

The official documentation goes into great detail on SafeHandles and how they simplify disposing of a class.

Disposing Asynchronously with `IAsyncDisposable`

When your class holds resources that involve asynchronous operations during cleanup (like closing a database connection or releasing a lock), you should implement the IAsyncDisposable instead of (or in addition to) IDisposable. This allows for non-blocking cleanup, keeping your application responsive.

The IAsyncDisposable interface expects a ValueTask DisposeAsync() method to be implemented.

Below is an example of implementing the IAsyncDisposable interface:

public class CustomerRepository : IAsyncDisposable
{
    // ... 

    public async ValueTask DisposeAsync()
    {
        // Implement asychronous cleanup logic
        await _connection.DisposeAsync();

        // Also implement any synchronous cleanup here as well
        _buffer.Dispose();
    }
}

Consuming an IAsyncDisposable class is similar to the IDisposable class. You just need to add await to your using statement:

await using (var repository = new CustomerRepository(_connectionString))
{
    // Use repository here
} // Calls repository.DisposeAsync() automatically

Conclusion

While the .NET GC does a great job of managing memory, it cannot clean unmanaged resources, like low-level file handles or database connections. The IDisposable interface helps ensure all managed and unmanaged resources are cleaned up deterministically.

Hopefully, this guide has shed some light on the Dispose pattern in C#. In most cases, you'll stick to the first, simple implementation. However, if you ever have to clean up unmanaged resources manually, a bit more code is needed to make it work.

By implementing the IDisposable interface properly, you'll reduce the number of potential memory leaks, resulting in a robust and stable end product.

Stop Spaghetti SQL: Simplify Complex Queries with Postgres CTEs in Supabase

Ivan Kahl — Thu, 02 Oct 2025 13:14:16 +0000

Modern web applications deal with massive amounts of complex data, and relational databases are a popular choice for keeping everything organized. But even with structured data, queries can turn into nightmares when you need to retrieve large amounts of interconnected information.

Take a music streaming app that wants to retrieve song suggestions by combining a user's listening history, genre preferences, and favorite artists. The SQL query quickly becomes unwieldy with endless subqueries and WHERE clauses, resulting in what's known as "spaghetti SQL" - code that's nearly impossible to read, maintain, or debug.

Common table expressions (CTEs) is one way to solve this problem. They let you break down complex queries into separate, manageable steps. Each step is a simple SQL query with clear results, labeled so you actually know what each part does. This can completely transform how readable and maintainable your queries become.

In this post, I'll show you how CTEs work in Postgres and how they can turn convoluted spaghetti SQL into clean, clearly defined statements. I’ll take you through practical demonstrations of CTEs used in a music streaming app. The demo app is hosted on Supabase, a backend service that offers a Postgres database for apps with built-in auth and edge functions. The CTEs will simplify logic used in some of the app’s queries. I'll also cover some advanced use cases and best practices.

What Are CTEs?

CTEs, defined in SQL using the WITH clause, let you create one or more temporary named result sets that can be used within a single SELECT, INSERT, UPDATE, or DELETE statement. The expressions are executed in sequential order and can reference previous result sets in the same statement.

Below is an example of a SQL statement that utilizes a CTE to filter out archived song tracks, which is then used in the final query:

WITH undeleted_tracks AS (
    SELECT track_id, title, artist_id, genre_id
    FROM tracks
    WHERE is_deleted = false
)
SELECT ut.title, a.name as artist_name, g.name as genre_name
FROM undeleted_tracks ut
    INNER JOIN artists a ON a.artist_id = ut.artist_id
    INNER JOIN genres g ON g.genre_id = ut.genre_id

First, a CTE is created to store a temporary collection called undeleted_tracks with all the undeleted songs in the tracks table. The CTE is then used in the final query. Notice you don't need to check if a track is deleted in the final query because the CTE already filtered them out.

Now, why would you use a CTE to achieve this? You could retrieve the same results using a predefined view or SQL subquery. CTEs, views, and subqueries do share some similarities; however, they have differences that make each appropriate for distinct scenarios:

Subqueries are nested SQL queries placed within a larger query. These nested queries can span multiple levels, which makes it difficult to follow the logical flow of the data and understand how the query is constructed.
Views are predefined SQL queries that are stored as persistent database objects. They are ideal for encapsulating query logic that spans multiple database tables and needs to be reused across different queries. Postgres lets you define a regular view, which runs its query each time it's accessed, and materialized views, which execute the query once and store the results for fast retrieval. Since materialized views store data, they require manual refreshes to update with the latest information.
CTEs are temporary "views" that only exist for the execution of a SQL statement. They are effective at replacing complex, nested subqueries, improving the readability and maintainability of the overall query by breaking it down into logical, named steps.

With these distinctions in mind, CTEs can be invaluable for writing recursive queries, which repeatedly reference their own output to retrieve hierarchical or network data. Imagine trying to debug an SQL query that has several levels of embedded SELECT statements, each dependent on the statement before it. The query's complexity obscures its intent, making it challenging to identify the underlying issue. In this case, CTEs' modularity makes the query's intent clear, which makes debugging and modifying the query a straightforward task as your application evolves.

Additionally, since much of Supabase's functionality is built on top of a Postgres database, you can use CTEs to query and manage your application's data if you're hosting your service there, as is the case with this music streaming app. This ensures that your backend remains easy to modify as requirements evolve and more features are implemented.

The following section will demonstrate how a complex query can be enhanced by replacing subqueries with CTEs.

The Problem with Complex SQL Queries

A key feature of a music streaming app is compiling personalized song recommendations based on the user's most-listened-to genre over the last month, excluding any songs they have already listened to or liked.

Without CTEs, a query to achieve this would consist of multiple subqueries:

SELECT t.title, ar.name AS artist_name
FROM tracks t
    INNER JOIN artists ar ON t.artist_id = ar.artist_id
WHERE 
    t.track_id NOT IN (
        -- Hardcode user_id (would be supplied as a parameter in the function)
        SELECT lh.track_id 
        FROM listening_history lh 
        WHERE lh.user_id = 'a1b2c3d4-e5f6-7890-1234-567890abcdef'
 )
    AND t.track_id NOT IN (
        -- Hardcoded user_id (would be supplied as a parameter in the function)
        SELECT ls.track_id 
        FROM liked_songs ls 
        WHERE ls.user_id = 'a1b2c3d4-e5f6-7890-1234-567890abcdef'
 )
    AND t.genre_id = (
        -- Subquery to find the user's top genre
        SELECT g.genre_id
        FROM genres g
        JOIN tracks t_inner ON g.genre_id = t_inner.genre_id
        JOIN (
            -- Sub-subquery to count plays per track for the user
            SELECT lh_inner.track_id, COUNT(*) as play_count
            FROM listening_history lh_inner
            WHERE lh_inner.user_id = 'a1b2c3d4-e5f6-7890-1234-567890abcdef'
                  AND lh_inner.listened_at >= NOW() - INTERVAL '30 days'
            GROUP BY lh_inner.track_id
 ) AS user_track_plays ON t_inner.track_id = user_track_plays.track_id
        GROUP BY g.genre_id
        ORDER BY SUM(user_track_plays.play_count) DESC
        LIMIT 1
 )
-- Show newest songs first
ORDER BY t.release_date DESC
LIMIT 5;

You'd have to spend some time analyzing the spaghetti SQL to figure out how it works. Debugging would also be a nightmare as you have to extract each subquery, mock dependent values that come from other queries, and then analyze the results. If you modify a subquery, you must be careful not to break another part of the query that relies on that subquery. Finally, performance can suffer because, while Postgres's optimizer is smart, deeply nested and correlated subqueries can generate less optimal execution plans.

Solving Spaghetti SQL with CTEs

The query presented above is a perfect candidate for CTEs. It has multiple nested queries that obscurely depend on one another. The CTE will rewrite the subqueries, separating each into its own named query, which will improve the original's readability and performance.

To begin, you'll first write a CTE that counts the number of times a user has listened to different tracks in the last thirty days. You can also use a CTE to store the user ID so that it's not duplicated across queries. When written, these two CTEs will look like this:

WITH user_data AS (
    -- Unnecessary if user id is an incoming parameter
    SELECT 'a1b2c3d4-e5f6-7890-1234-567890abcdef'::uuid as user_id
),
user_recent_play_count AS (
    SELECT lh.track_id, COUNT(*) as play_count
    FROM listening_history lh
        JOIN user_data ud ON lh.user_id = ud.user_id
    WHERE lh.listened_at >= NOW() - INTERVAL '30 days'
    GROUP BY lh.track_id
)
SELECT * 
FROM user_recent_play_count
ORDER BY play_count DESC;

Notice how you can write a SELECT statement at the end of your CTE to debug the results before moving on to the next subquery. If you run the query above, you'll see a list of track IDs and the number of times each was played by the user:

You can perform some spot checks on the results to ensure the data being returned by the CTE is correct. If it's not, you can easily modify the CTE and re-execute it until it's right. In this case, everything looks good, so you can continue with extracting the following subquery, which finds the user's top genre:

WITH user_data AS (
    SELECT 'a1b2c3d4-e5f6-7890-1234-567890abcdef'::uuid as user_id
),
user_recent_play_count AS (
    SELECT lh.track_id, COUNT(*) as play_count
    FROM listening_history lh
        JOIN user_data ud ON lh.user_id = ud.user_id
    WHERE lh.listened_at >= NOW() - INTERVAL '30 days'
    GROUP BY lh.track_id
),
user_top_genre AS (
    SELECT g.genre_id, g.name
    FROM genres g
    JOIN tracks t ON g.genre_id = t.genre_id
    -- Reference the previous CTE instead of a subquery
    JOIN user_recent_play_count urpc ON urpc.track_id = t.track_id 
    GROUP BY g.genre_id
    ORDER BY SUM(urpc.play_count) DESC
    LIMIT 1
)
SELECT * 
FROM user_top_genre;

The new query selects data from the new CTE, which should return the user's most popular genre:

Now, you can select tracks from that genre to recommend to the user. However, remember that the requirements specify that songs the user has already listened to or liked should be excluded. The next CTE you'll create will contain a list of track IDs that should not be recommended:

WITH user_data AS (
    SELECT 'a1b2c3d4-e5f6-7890-1234-567890abcdef'::uuid as user_id
),
user_recent_play_count AS (
    SELECT lh.track_id, COUNT(*) as play_count
    FROM listening_history lh
        JOIN user_data ud ON lh.user_id = ud.user_id
    WHERE lh.listened_at >= NOW() - INTERVAL '30 days'
    GROUP BY lh.track_id
),
user_top_genre AS (
    SELECT g.genre_id, g.name
    FROM genres g
    JOIN tracks t ON g.genre_id = t.genre_id
    JOIN user_recent_play_count urpc ON urpc.track_id = t.track_id 
    GROUP BY g.genre_id
    ORDER BY SUM(urpc.play_count) DESC
    LIMIT 1
),
user_excluded_tracks AS (
    SELECT lh.track_id
    FROM listening_history lh
        JOIN user_data ud ON lh.user_id = ud.user_id
    UNION
    SELECT ls.track_id
    FROM liked_songs ls
        JOIN user_data ud ON ls.user_id = ud.user_id
)
SELECT uet.*, t.title
FROM user_excluded_tracks uet
    INNER JOIN tracks t ON t.track_id = uet.track_id;

If you run the query above, you'll see a list of track IDs and titles of songs the user has already heard or liked, similar to the result set below:

Finally, combine all your CTEs into a single query to retrieve five song recommendations for the user:

WITH user_data AS (
    SELECT 'a1b2c3d4-e5f6-7890-1234-567890abcdef'::uuid as user_id
),
user_recent_play_count AS (
    SELECT lh.track_id, COUNT(*) as play_count
    FROM listening_history lh
        JOIN user_data ud ON lh.user_id = ud.user_id
    WHERE lh.listened_at >= NOW() - INTERVAL '30 days'
    GROUP BY lh.track_id
),
user_top_genre AS (
    SELECT g.genre_id, g.name
    FROM genres g
    JOIN tracks t ON g.genre_id = t.genre_id
    JOIN user_recent_play_count urpc ON urpc.track_id = t.track_id 
    GROUP BY g.genre_id
    ORDER BY SUM(urpc.play_count) DESC
    LIMIT 1
),
user_excluded_tracks AS (
    SELECT lh.track_id
    FROM listening_history lh
        JOIN user_data ud ON lh.user_id = ud.user_id
    UNION
    SELECT ls.track_id
    FROM liked_songs ls
        JOIN user_data ud ON ls.user_id = ud.user_id
)
SELECT t.title, a.name AS artist_name
FROM tracks t
  INNER JOIN artists a ON t.artist_id = a.artist_id
  -- Only consider songs in the user's favourite genre
  INNER JOIN user_top_genre utg ON t.genre_id = utg.genre_id
  -- Left join songs to find tracks NOT in the excluded list
  LEFT JOIN user_excluded_tracks uet ON uet.track_id = t.track_id
WHERE uet.track_id IS NULL -- Make sure track_id is NOT in excluded tracks
ORDER BY t.release_date DESC -- Show newest songs first
LIMIT 5;

Notice how each step in the CTE functions as a variable that holds a collection of temporary data. Even though the final query above might still look a bit complicated, it doesn't contain any complex subqueries. Rather, each CTE acts as a variable that stores a clearly defined set of results. These result sets are then combined in the final query using straightforward JOIN statements. The WHERE clause in the final query is also easier to read because it doesn't use subqueries. Overall, these factors make the query self-documenting and easy to debug and enhance in the future.

Optimizing CTE Performance

While the above CTE is easier to understand than the original query with nested subqueries, it does not always result in better performance.

Postgres's query planner is smart and in-lines CTEs if they are only referenced once, treating them as subqueries. However, if a CTE is referenced multiple times, in-lining becomes inefficient, and Postgres then opts to materialize the results. It does this by creating a temporary result set that can be reused across different subqueries.

Suppose you want to override the default behavior. You can do this by explicitly instructing Postgres to optimize the query using a materialized result set with the following syntax:

WITH user_data AS MATERIALIZED (...)

Likewise, you can use the following syntax to force it to in-line the query:

WITH user_data AS NOT MATERIALIZED (...)

If you're interested in how Postgres optimizes your queries, use the EXPLAIN ANALYZE command to view the execution plan:

EXPLAIN ANALYZE WITH user_data AS (...)
SELECT ...;

Below is a screenshot of a portion of the execution plan for the CTE developed above:

So while the query planner will try its best to find the most optimal method of running a CTE, keep in mind that you can always fine-tune it if needed.

Advanced CTE Use Cases

CTEs can massively improve the readability of your query, but they're also able to do a whole lot more. Below are some more advanced use cases where CTEs excel.

Recursive CTEs

Relational databases, such as Postgres, allow tables to have self-referential fields, where a field in a table refers to another record within the same table. This is useful when storing hierarchical or network data. Recursive CTEs let you query all the rows that make up these relationships.

In music, genres are often further categorized into subgenres. Suppose you want to find all the subgenres under "Pop" and list all the tracks in those genres. You can use the following CTE:

WITH RECURSIVE genre_hierarchy (genre_id, name, parent_genre_id, parent_genre_name, level) AS (
    -- Anchor Member: Start with the upper-most parent genre
    SELECT g.genre_id, g.name, g.parent_genre_id, NULL, 0 AS level
    FROM genres g
    WHERE g.name = 'Pop'
    UNION ALL
    -- Recursive Member: Find child genres by joining back to genre_hierarchy
    SELECT child_g.genre_id, child_g.name, child_g.parent_genre_id, gh.name, gh.level + 1
    FROM genres child_g
    JOIN genre_hierarchy gh ON child_g.parent_genre_id = gh.genre_id
)
SELECT gh.parent_genre_name,
       gh.name AS genre_name,
       gh.level,
       t.title AS track_title,
       ar.name AS artist_name
FROM genre_hierarchy gh
  LEFT JOIN tracks t ON gh.genre_id = t.genre_id
  LEFT JOIN artists ar ON t.artist_id = ar.artist_id
ORDER BY gh.level, gh.name, t.title;

This returns the following:

Notice how the CTE is defined using the WITH RECURSIVE syntax. This instructs Postgres that the CTE will reference itself. When building the CTE query, you use the following layout:

<non-recursive query>
UNION [ALL]
<recursive query>

As the example above demonstrates, CTEs make querying hierarchical or network data straightforward. For example, they make it possible to query organizational hierarchies where employees are managed and can manage others, retrieve a file system hierarchy where each file and folder is stored as a record linked to another record, or query categories and their nested subcategories. A word of warning when working with recursive CTEs: make sure you specify an explicit termination clause that'll stop the recursive loop; otherwise, your query will loop indefinitely.

Batch Updates

CTEs are not restricted to SELECT statements. You can also modify records using INSERT, UPDATE, or DELETE statements within a CTE. These let you perform sequential data-manipulation operations and query the results.

The CTE below demonstrates how a user's old listening_history is archived:

WITH deleted_history AS (
    -- Delete old listening history and return the deleted rows
  DELETE FROM listening_history
    WHERE listened_at < NOW() - INTERVAL '2 years'
    RETURNING user_id, track_id, listened_at
),
archived_data AS (
    -- Insert the deleted rows into an archive table
 INSERT INTO archived_listening_history (user_id, track_id, listened_at)
    SELECT user_id, track_id, listened_at FROM deleted_history
    RETURNING user_id
)
-- Report number of deleted rows per user_id
SELECT ad.user_id, COUNT(*) AS archived_tracks_count
FROM archived_data ad
GROUP BY ad.user_id
ORDER BY archived_tracks_count DESC;

First, records from the listening_history table that are older than two years are deleted. The deleted records are returned using the RETURNING statement. The following CTE inserts these records into an archive table and returns the user ID for each archived record. Finally, a summary is generated to count the number of records archived for each user.

The query results will look something like this:

Structure Business Logic into SQL Functions Using CTEs

CTEs can help you break down complex business logic into sequential, descriptive steps. To reuse these CTEs, you can then consider wrapping them in a SQL function.

Consider the song-recommendation CTE from earlier. This can be encapsulated in an SQL function like the one below:

CREATE OR REPLACE FUNCTION get_user_track_recommendations(p_user_id UUID, p_limit INT)
RETURNS TABLE (track_title TEXT, artist_name TEXT)
LANGUAGE sql
AS $$
    WITH user_recent_play_count AS (
        SELECT lh.track_id, COUNT(*) as play_count
        FROM listening_history lh
        WHERE lh.listened_at >= NOW() - INTERVAL '30 days'
              AND lh.user_id = p_user_id
        GROUP BY lh.track_id
    ),
 user_top_genre AS (
        SELECT g.genre_id, g.name
        FROM genres g
        JOIN tracks t ON g.genre_id = t.genre_id
        JOIN user_recent_play_count urpc ON urpc.track_id = t.track_id 
        GROUP BY g.genre_id
        ORDER BY SUM(urpc.play_count) DESC
        LIMIT 1
    ),
 user_excluded_tracks AS (
        SELECT lh.track_id
        FROM listening_history lh
        WHERE lh.user_id = p_user_id
        UNION
        SELECT ls.track_id
        FROM liked_songs ls
        WHERE ls.user_id = p_user_id
    )
    SELECT t.title,
 a.name AS artist_name
    FROM tracks t
      INNER JOIN artists a ON t.artist_id = a.artist_id
      -- Only consider songs in the user's favourite genre
      INNER JOIN user_top_genre utg ON t.genre_id = utg.genre_id
      -- Left join songs to find tracks NOT in the excluded list
      LEFT JOIN user_excluded_tracks uet ON uet.track_id = t.track_id
    WHERE uet.track_id IS NULL -- Make sure track_id is NOT in excluded tracks
    ORDER BY t.release_date DESC -- Show newest songs first
    LIMIT p_limit;
$$;

The function accepts the user ID and the number of recommendations to return as input parameters. The result is a table with a track and the artist's name.

You can now simply call this complex CTE with the following function call:

SELECT *
FROM get_user_track_recommendations('a1b2c3d4-e5f6-7890-1234-567890abcdef', 5);

This returns the same results as before:

Using CTEs Instead of Temporary Tables

Temporary tables are a common method for storing intermediate results in a multistep query. You'll often find this used in complex queries or SQL functions that need to perform multiple steps and queries to compile the final results. However, CTEs can often provide a cleaner solution.

Consider the temporary tables below, which store a list of songs the user has listened to and their top genre:

CREATE TEMP TABLE temp_user_listens AS SELECT ...;
CREATE TEMP TABLE temp_top_genre AS SELECT ...;
SELECT ... FROM temp_top_genre JOIN ...;
DROP TABLE temp_top_genre;
DROP TABLE temp_user_listens;

CTEs offer a cleaner approach:

WITH user_listens AS (SELECT ...),
     top_genre AS (SELECT ...)
SELECT ... FROM temp_top_genre JOIN ...;

Each CTE functions like a temporary table but is limited to a single query and is automatically removed after use. The entire CTE expression is cleaned up automatically, even if an error occurs. This saves you from having to manually drop the temporary tables when finished.

However, if you need to compile intermediate results that multiple subsequent queries will access, a temporary table may be a better choice. But if those results are only necessary for a single query, CTEs are a better option.

Best Practices and Pitfalls

Before you start refactoring all your Postgres code to use CTEs, it's best to keep a few best practices and pitfalls in mind.

Choosing Between CTEs, Views, and Functions

Knowing when to choose between CTEs, views, and functions is important for writing clean SQL.

Use CTEs for single queries that involve multistep data manipulation and aggregation. Also, consider using a CTE within a view or function if the query logic warrants it.

Views are ideal for simplifying queries that retrieve data from complex, multitable data structures. The view encapsulates the complex query logic and defines a stable interface that other queries can use when selecting the view. Unlike CTE expressions, they are not temporary and are often created once and then reused.

Functions are ideal for encapsulating business logic, especially when multiple input parameters are required. The function has a descriptive name and can be queried like a view or table. As you saw above, a function can still utilize a view or CTE internally to clearly define the query.

Considering Performance

Remember that CTEs don't automatically improve performance. Use the EXPLAIN ANALYZE command to investigate your CTE's performance gaps.

While Postgres does try to create and manage the CTE intelligently, you can give it hints on how to create and consume the CTE. These hints are MATERIALIZED and NOT MATERIALIZED.

MATERIALIZED indicates to Postgres to create a temporary result set for that CTE query. NOT MATERIALIZED hints at the query engine to in-line the CTE queries before running them.

Don't assume CTEs perform better. Double-check them yourself and make the necessary optimizations if necessary.

Common Mistakes and How to Avoid Them

You'll want to avoid these common mistakes that you might run into while using CTEs.

Firstly, don't overuse CTEs. They are a powerful tool when dealing with complex query logic but can complicate a simple query unnecessarily.

Take the CTE below as an example:

WITH user_data AS (
    SELECT * 
    FROM users 
    WHERE email = 'alice@example.com'
)
SELECT *
FROM listening_history lh
  INNER JOIN user_data ud ON ud.user_id = lh.user_id;

It's much simpler to write as such:

SELECT *
FROM listening_history lh
  INNER JOIN users u ON u.user_id = lh.user_id
WHERE u.email = 'alice@example.com';

Secondly, ensure your CTEs have appropriate names. Misleading names make it difficult to understand each query's purpose. Choosing suitable names goes a long way in clarifying the intent of each CTE.

Finally, don't use the names of existing views and tables in the database to name your CTEs. Below is an example:

WITH users AS (
  SELECT username FROM users
)
SELECT * FROM users;

Some relational database management systems (RDBMS) might throw an error or warn you about naming collisions between tables and CTEs, such as the one above between the users table and the users CTE. However, other RDBMS software might not, in which case the CTE will take precedence over other tables in the database, leading to potentially confusing results. Save yourself future confusion and use a different name.

Tips for Testing and Debugging CTEs

When building CTEs, make sure you're debugging early and often. After writing each CTE query, run a SELECT on that CTE to verify it returns the data you expect it to return. Since CTEs often build upon one another, it's much easier to identify and resolve issues as you go rather than trying to locate the root cause of a problem after completing all the queries.

For example, you saw in the walkthrough above how each CTE was tested before moving on to the next:

WITH user_data AS (
    -- Unnecessary if user id is an incoming parameter
    SELECT 'a1b2c3d4-e5f6-7890-1234-567890abcdef'::uuid as user_id
),
user_recent_play_count AS (
    SELECT lh.track_id, COUNT(*) as play_count
    FROM listening_history lh
        JOIN user_data ud ON lh.user_id = ud.user_id
    WHERE lh.listened_at >= NOW() - INTERVAL '30 days'
    GROUP BY lh.track_id
)
SELECT * 
FROM user_recent_play_count
ORDER BY play_count DESC;

Save yourself the headache of debugging a monolithic query by testing each CTE as you build it.

Conclusion

CTEs are an essential tool for transforming spaghetti SQL into well-structured, readable, and maintainable queries. They allow you to break down subqueries into named, sequential steps, which clarifies the data manipulations occurring to produce the final results. The article illustrated how a particularly convoluted query can become much easier to read when using CTEs. Additionally, it explored some advanced use cases for CTEs, such as recursive and batch-update CTEs and using them to organize business logic while replacing temporary tables. Finally, some pitfalls and best practices were highlighted to ensure your CTEs remain both readable and efficient.

What's New in C# 14: Null-Conditional Assignments

Ivan Kahl — Thu, 11 Sep 2025 11:00:00 +0000

If you've ever developed in C#, you've likely encountered a snippet like the one below:

if (config?.Settings is not null) 
{
    config.Settings.RetryPolicy = new ExponentialBackoffRetryPolicy();
}

This check is necessary because, if config or config.Settings is null, a NullReferenceException is thrown when trying to set the RetryPolicy property.

But no more endless ifs! The latest version of C#, scheduled for release later this year with .NET 10, introduces the null-conditional assignment operators, which are designed to solve this exact issue.

Wait, Doesn't C# Already Have Null-Conditionals?

Yes! The null-conditional and null-coalescing operators have been around for a while. They simplify checking if a value is null before assigning or reading it.

// Null-conditional (?.)
if (customer?.Profile is not null) 
{
    // Null-coalescing (??)
    customer.Profile.Avatar = request.Avatar ?? "./default-avatar.jpg";
}

However, these operators only worked when reading a value, not setting one. With C# 14, you'll be able to use it on the left-hand side of the = operator! Depending on your codebase, this can drastically clean up your code by reducing the number of if statements needed to assign values.

Prerequisites

C# 14 is still in development. This means that the syntax might change slightly before the final release of .NET 10. However, I'll update this article if anything does change before the final release.

You'll need to download and install the latest .NET 10 preview SDK to run the snippets below. Next, create a new C# project (using a Console project in this article) and ensure it targets .NET 10. You'll also need to enable preview language features by opening your *.csproj file and adding the <LangVersion>preview</LangVersion> tag:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <!-- Add the LangVersion tag below. -->
    <LangVersion>preview</LangVersion>
  </PropertyGroup>
</Project>

You're all set to follow along with the snippets below.

Null-Conditional Assignments With Object Properties

The introduction illustrated a typical pattern you'll find in C# projects when assigning values to object properties: first check if the object itself is not null. If you don't, a frustrating NullReferenceException gets thrown, and those are no fun to debug.

Take the snippet you saw at the beginning of this article:

if (config?.Settings is not null) 
{
    config.Settings.RetryPolicy = new ExponentialBackoffRetryPolicy();
}

This becomes a one-liner in C# 14:

config?.Settings?.RetryPolicy = new ExponentialBackoffRetryPolicy();

Now, the compiler will first make sure that config?.Settings is not null before proceeding to assign the RetryPolicy property. If config?.Settings is null, the assignment is skipped.

Null-Conditional Assignments With Indexer Elements

The new operator also works on indexers. This is useful when you're unsure whether a dictionary or list is null before assigning a value.

Below is how you'd currently check if a dictionary is defined before assigning a value to it:

if (customerData is not null)
{
    customerData["LastLogin"] = DateTime.UtcNow;
}

Again, this is much simpler in C# 14:

customerData?["LastLogin"] = DateTime.UtcNow;

Similar to the first example, the compiler will first check if properties is defined. If it is, the assignment is executed; otherwise, it's ignored.

Null-Conditional Assignments with Compound Assignments

You're not limited to just using standard = assignments. You can also use the new operator with compound assignment operators like += and -=.

Previously, you would have probably written something similar to the snippet below:

if (results is not null)
{
    results.ItemsProcessed += 5;
}

This now becomes:

results?.ItemsProcessed += 5;

You can even combine it with other operators, like the null-coalescing assignment operator (??=), to handle cases where the object exists but the property itself is null.

customer?.Name ??= "Guest";

In the one-liner above, if customer is null, the entire assignment is skipped. Otherwise, if customer is defined, but Name is null, then the property is assigned "Guest".

Things To Keep In Mind

Before applying null-conditional assignments throughout your codebase, keep these things in mind.

Side-Effect Prevention

When a null-conditional statement assignment is evaluated, the right-hand side of the expression is not executed unless the left-hand side is defined. This is to prevent side effects arising from the right-hand side executing, but then resulting value is being discarded when performing the assignment.

For example, you might have a function that generates the next ID in a sequence and returns it:

customer?.Id = GenerateNextCustomerId();

If customer is null, then GenerateNextCustomerId() won't be executed. This is logical, since you don't want to unnecessarily increment your customer ID counter if the value isn't going to be used. Nevertheless, it's good to keep in mind when utilizing the operator.

Increment and Decrement Operators Aren't Supported

Sometimes it's convenient to increment a value using the ++ or -- operators. However, those won't work if you're using a null-conditional assignment operator.

For example, this code snippet will break:

// Will fail as ++ and -- are not supported with null-conditional assignments
customer?.TotalOrders++;

Why not support it? The C# design team decided that these operators would be more challenging to implement and might not yield the expected results. Hence, a decision was taken not to support it.

Don't Overuse It

This is my personal preference: avoid overusing the operator, as it might make it unclear why a specific value isn't being assigned.

For example, consider the snippet below:

customer?.Orders?.FirstOrDefault()?.OrderNumber = GenerateNewOrderNumber();

If a customer reports that the order number is not showing, you would need to look at this single line of code and determine:

Did the GenerateNewOrderNumber() method return null
Was customer set to null? Maybe the query to retrieve it is incorrect.
Was customer.Orders set to null? Maybe the ORM never attached the order list to the customer entity.
Was the customer.Orders list empty, so FirstOrDefault() returned a null value?
Was the first value in the Orders list a null? This could indicate some deserialization issue somewhere.

It's too many "what ifs" for one line. So, if your code looks like that, seriously consider refactoring it to be easier to debug. Perhaps to something like this:

if (customer is null)
{
    logger.LogWarning("Customer is null for {CustomerId}", customerId);
    return;
}

var firstOrder = customer.Orders?.FirstOrDefault();
if (firstOrder is null)
{
    logger.LogWarning("Could not find an order for customer {CustomerId}", customerId);
    return;
}

firstOrder.OrderNumber = GenerateNewOrderNumber();

This code makes it much easier to determine why an order number was not assigned, simply by reviewing the application logs.

Conclusion

The new null-conditional assignment operator is a convenient feature coming in C# 14. It lets you avoid nesting assignments inside if statements, making your code easier to read. However, keep in mind the limitation of not supporting ++ and -- operators, and try not to overuse the new operator.

This is just one of several enhancements being introduced with C# 14. When you do update your projects to .NET 10, which is the next LTS version of the SDK, consider how you can take advantage of these quality-of-life improvements to neaten your codebase.

What's New in C# 14: User-Defined Compound Assignments

Ivan Kahl — Tue, 05 Aug 2025 21:48:40 +0000

.NET 10 is scheduled to be released later this year and, with it, comes the next iteration of C#. C# 14 has several cool features planned, such as extension members and field-backed properties. However, one, perhaps lesser-known, feature is the new user-defined compound assignment.

Prerequisites

The code snippets in this article are for C# 14, which is still in development. This means that the syntax might change slightly before the final release of .NET 10. However, I will endeavor to keep this article updated if it does.

To run the code snippets yourself, you need to download and install the latest .NET 10 preview SDK. Next, create a new C# project (using a Console project in this article) and ensure it targets .NET 10. You'll also need to enable preview language features by opening your *.csproj file and adding the <LangVersion>preview</LangVersion> tag:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <!-- Add the LangVersion tag below. -->
    <LangVersion>preview</LangVersion>
  </PropertyGroup>
</Project>

That's it! You'll now be able to run the snippets.

Compound Assignments in C# 13 and Earlier

To understand how user-defined compound assignments will work, you should understand how compound assignments currently work in C# 13 and below. Traditionally, compound assignments like x += y are simply shorthand for x = x + y. Classes and structs can override the + operator, and this override is then automatically used when using a compound assignment:

public record struct Vector3(decimal X, decimal Y, decimal Z)
{
    public static Vector3 operator +(Vector3 left, Vector3 right)
    {
        return new Vector3(
            left.X + right.X,
            left.Y + right.Y,
            left.Z + right.Z
        );
    }
}

var one = new Vector3(1, 2, 3);
var two = new Vector3(4, 5, 6);

// Uses the operator overload
one = one + two;

// Also uses the + operator overload
one += two;

Using the + operator implementation makes sense for the compound assignment; however, it does have a slight performance impact.

The Hidden Costs of Compound Assignments

Each time the + operator is called, a new object is created within the override and returned. This means that even if you write: one += two, the operator method creates a third object containing the result of one + two and returns it, which is then assigned back to one. The previous object assigned to one is then marked for garbage collection.

This performance issue is usually minor. However, it can still cause noticeable effects in certain situations. Luckily, C# 14 addresses this by allowing you to create a self-assignment operator method.

A More Efficient Compound Assignment in C# 14

C# 14 introduces a new feature that lets you define a += operator override. This lets you define a more efficient, in-place compound assignment operator than the default + operator

Below is an example of a class with both the + and += operators overridden:

public record struct Vector3(decimal X, decimal Y, decimal Z)
{
    // Static + operator overload that returns a new instance
    public static Vector3 operator +(Vector3 left, Vector3 right)
    {
        return new Vector3(
            left.X + right.X,
            left.Y + right.Y,
            left.Z + right.Z
        );
    }

    // More efficient compound operator overload that does in-place
    // addition
    public void operator +=(Vector3 right)
    {
        X += right.X;
        Y += right.Y;
        Z += right.Z;
    }
}

var one = new Vector3(1, 2, 3);
var two = new Vector3(4, 5, 6);

// Uses the compound assignment operator
one += two;

// Uses the addition operator
var three = one + two;

Notice how the new operator overload is an instance method on the class instead of a static method. The return type is also void because no object needs to be created and returned. Instead, you can see how the right object's properties are added to the current object's properties.

You can also have a + operator override and a += compound assignment override for the same class. C# will automatically pick the most appropriate method when performing operations on the class. This lets you retain existing functionality exposed by an operator override while implementing a more efficient implementation for self-assignment operators.

Tips and Gotchas

While this can be really useful, there are a few things to consider when defining your compound assignment methods.

Maintain Logical Consistency

When defining both + and += overrides, it's best to ensure the logic remains consistent between the two methods. While you can intentionally make them different, doing so is a terrible idea and would confuse developers using the operators.

The purpose of the compound assignment override is to provide an efficient, self-assignment override that still matches the behaviour of the regular operator.

Know When to Use It

The new compound operator is designed to make self-assignment operations on objects faster and more efficient. You will see the most benefits from this feature when using it in classes or structs that handle a lot of data. It helps you avoid unnecessary memory use and copying entire objects.

In other situations, you might not notice much difference in performance. If that’s the case, it is probably easier to just implement the operator overload and let C# manage compound assignments for you.

Beware Fallbacks

You don't just have to write operator overrides for objects of the same type. C# allows you to implement multiple overloads for operators that enable operations between different types. The same applies to compound assignment overrides.

However, be careful that you don't inadvertently call an operator override because of a missing compound assignment override for that particular type. For example, the class below implements a compound assignment and operator override for int. However, only the operator method is defined for decimal.

public record struct Vector3(decimal X, decimal Y, decimal Z)
{
    public void operator *=(int right)
    {
        // ...
    }

    public static Vector3 operator *(Vector3 left, int right)
    {
        // ...
    }

    public static Vector3 operator *(Vector3 left, decimal right)
    {
        // ...
    }
}

var one = new Vector3(1, 2, 3);
var two = new Vector3(4, 5, 6);

// Uses the compound assignment method
one *= 2;

// Uses the operator override
two *= 3.4m;

When you call one *= 2, the compound assignment method for int is used correctly. However, two *= 3.4m will fall back to the operator override because no compound assignment operator is defined for decimal.

Conclusion

User-defined compound assignments are a small but powerful feature. If you have large data classes or structs and want to support operations, or if you're a library author aiming for efficiency, this is definitely worth considering. However, since you might be duplicating logic, consider how important the performance benefits are compared to the cost of duplicated code.

Beyond the Random Class: Cryptographic Randomness in .NET 6+

Ivan Kahl — Tue, 14 Jan 2025 11:00:00 +0000

We live in a naturally unpredictable world. Shuffling a deck of cards, picking lottery numbers, and weather patterns are all random. Software often needs to mimic this unpredictability, such as spawning enemies at random intervals in a game, selecting a random sample of data for training a machine learning model, or generating a random OTP code when authenticating a user. Computers, however, are deterministic machines. Given a particular input, the computer will always produce the same output. This makes replicating the unpredictability we live in a challenge in code.

C# offers a couple of APIs for generating random numbers, with the Random class being a common choice. However, while useful in many scenarios, its implementation isn't always appropriate, especially in security contexts where its predictability can be exploited. In those cases, alternatives like the RandomNumberGenerator, which offer a higher degree of unpredictability, are better suited.

In this article, you will learn how the Random class functions in C#, when it's appropriate to use, when and why it's not always suitable, and what alternatives to consider.

Why Computers Aren't Truly Random

Computers follow a strict set of instructions to perform a task. Given the same input, the process will yield the same output. This is great for computers, and it's what's needed for them to perform computations accurately.

When it comes to randomness, the computer has to cheat by relying on algorithms that generate seemingly random numbers. These algorithms are called Pseudo-Random Number Generators (PRNGs) and consist of mathematical formulas to produce a sequence of numbers that appear random but are still deterministic. PRNGs start with a seed value, which is the starting point for the sequence generation. Given the same seed value, a PRNG will always produce the same sequence of numbers. While not completely random, this predictability can sometimes be helpful where reproducibility is desired, like in unit tests or where reproducing the sequence carries little risk.

However, there are cases where you don't want this reproducibility. If an attacker can figure out the seed used to generate the number sequence, they can "predict" the next numbers. In specific contexts, like security, this can result in a system getting compromised. For example, if you use a PRNG to generate OTP codes for authentication, an attacker could compromise the system by figuring out the seed and generating the same codes. This is why true randomness, which is unpredictable, is essential for security-sensitive tasks.

Did you know?
Cloudflare, one of the world's leading CDN providers, generates completely random encryption keys using a wall of 100 lava lamps. A camera mounted to capture all the lava lamps takes regular pictures of the lamps and sends them to Cloudflare servers, where the image pixels are used to generate the next encryption key. Read more about it on their blog.

The Random Class: "Good-Enough" Randomness

The Random class is the de facto way of generating random numbers in most applications. It's a PRNG that's been around since the beginning of the .NET Framework. Although its underlying implementation has changed over the years, its API has remained relatively unchanged. It's intuitive, efficient, and works well in most cases.

Generating Random Integers

To use it, all you need to do is create a new instance of the class and then get the next random numbers:

var random = new Random();
Console.WriteLine(random.Next());
Console.WriteLine(random.Next());

// Output:
// 1472324096
// 2138638347

The Next() method generates a non-negative random integer. You can also pass in parameters to restrict the result if necessary:

var random = new Random();

// Generate random integer no larger than 9
Console.WriteLine(random.Next(10));

// Generate random integer between 10 and 19 (inclusive)
Console.WriteLine(random.Next(10, 20));

// Output:
// 7
// 14

When using the overloads, the start number is inclusive (if specified), and the end number is exclusive.

The Random class also has methods to generate random bytes, doubles, longs, and even pick random items from an array.

Seeding the Generator

You'll notice that no seed value was specified when instantiating the Random class above. When one isn't specified, .NET will generate the seed for you. How that seed is generated has changed over the years. In .NET Framework, the current time is used to create the seed. However, .NET Core and 5+ have improved on this by making an interop call to the operating system to generate a random seed using hardware, which is much less predictable.

You can pass in a seed using one of the constructor overloads. This is useful if you want to control the sequence of numbers generated. The snippet below demonstrates this:

// Use 78 as the seed
var random = new Random(78);

Console.WriteLine(random.Next());
Console.WriteLine(random.Next());

// Output:
// 1020951901
// 1511780237

You should get the same output as the snippet if you run the code below.

When To Use It

The Random class is simple and very efficient since all the numbers are generated by software (and not hardware, as you'll see in the next section). The generated numbers are spread across your desired range and will seem random enough for most applications. An end user shouldn't pick up any patterns.

You'll want to avoid it, though, if being able to predict values will compromise the security of your application or the integrity of your data. For example, generating password salts, nonces, and OTPs should not use the Random class since predicting those values will be disastrous. Similarly, you might not want to use the Random class for applications like gambling and picking winners for a draw since predicting the numbers could ruin the integrity of the game.

Warning on Instantiation and Thread Safety

The official Microsoft documentation advises not to re-instantiate the Random class every time you need a number. This makes sense, especially if you're working with .NET Framework, since seeds are generated using the system time. Two generators can have the same seed value if they are instantiated close together.

However, even if you're working in modern .NET (i.e., .NET 5 and up), re-instantiating the generator doesn't make sense. The generator is guaranteed to choose from a range of numbers with equal probability, meaning no number is more likely to be generated than another. This is good! But you lose that guarantee if you re-instantiate the Random class every time.

Also, keep in mind that the Random class is not thread-safe. To overcome this challenge, the documentation demonstrates how you can use locks to make sure the Random object is never called illegally.

The RandomNumberGenerator Class: Cryptographically Secure Randomness

Since computers are deterministic, generating truly random numbers is difficult. You need to incorporate entropy into the algorithm. This entropy typically comes from something in real life that exhibits random, unpredictable behaviour. Cloudflare gets entropy from a wall of lava lamps; C# gets entropy from the operating system, which, in turn, relies on underlying hardware for randomness. You can access this more secure random number generator using the RandomNumberGenerator class.

Microsoft recommends using the static implementation of the class, which will be demonstrated in this article.

Generating Random Integers

Unlike the Random class above, you need to specify the upper bound for the number you want to generate with the RandomNumberGenerator class. Another overload also lets you choose the lower bound:

// Get a cryptographically random number between 0 and 9
Console.WriteLine(RandomNumberGenerator.GetInt32(10));

// Get a cryptographically random number between 10 and 19
Console.WriteLine(RandomNumberGenerator.GetInt32(10, 20));

// Output:
// 8
// 16

Notice how the output is similar to our previous example, where we used the Random class. However, these are far less predictable, and because of entropy, it's practically impossible to repeat the sequence of numbers generated.

Generating Random Strings (.NET 8+)

The release of .NET 8 introduced several new helper methods to the RandomNumberGenerator class. One such method lets you provide a source string and desired length and then generates a random string of that length using the characters in the source string:

var availableCharacters = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890";

// Get a cryptographically random string 20 characters long
Console.WriteLine(RandomNumberGenerator.GetString(availableCharacters, 20));

// Output:
// "5LZFSEVZTPI7LTFTPIJJ"

This is useful if you need to create passwords or OTPs.

Generating Random Hexadecimal Strings (.NET 8+)

The hexadecimal number system lets you represent numbers in base 16. It does this using characters 0-9 and A-F. From .NET 8 and up, you can generate random hexadecimal numbers using the GetHexString static method on the RandomNumberGenerator class:

// Get a cryptographically random hex string 5 characters long with 
// uppercase characters
Console.WriteLine(RandomNumberGenerator.GetHexString(5));

// Get a cryptographically random hex string 8 characters long with
// lowercase characters.
Console.WriteLine(RandomNumberGenerator.GetHexString(8, lowercase: true));

// Output:
// "F23BB"
// "7c92dfa5"

When To Use It

After seeing RandomNumberGenerator in action, you might wonder why you would use the Random class. But wait! As great as the RandomNumberGenerator class is, it has additional overhead. Whenever it generates a number, it calls the operating system to add entropy. This call does make the RandomNumberGenerator much slower, which you'll see in this benchmark.

The additional overhead means you should only use the RandomNumberGenerator when you actually need cryptographically random numbers. For any other use case, stick to the Random class.

Conclusion

This article explored the intricacies of generating random numbers in code, focusing specifically on the Random and RandomNumberGenerator classes in C#. You first learned how computers are deterministic and need to use PRNGs to generate seemingly random numbers. You then saw how to pick random numbers from the Random class, a PRNG generator. While simple and efficient, the Random class has limitations, especially regarding cryptographic operations.

You were then introduced to the RandomNumberGenerator, which uses entropy from the underlying operating system to generate cryptographically secure numbers which are practically impossible to predict. The article also demonstrated newer methods added to the class in .NET 8 and up, simplifying generating random strings and hexadecimal numbers.

As I looked through the source code for these classes, it's clear that very clever engineers have done much of the heavy lifting for us. However, it's still essential to understand how these classes work to use them effectively in your code base.

If you have any comments or feedback, please leave a comment below.

C# Null-Conditional (?.) & Null-Coalescing (??) Operators Explained

Ivan Kahl — Sat, 04 Jan 2025 14:10:29 +0000

You've likely bumped into the pesky NullReferenceException if you've developed anything in C#. This exception usually happens when you try to access a member of a variable that contains a null reference, disrupting the flow of your application.

Fortunately, C# offers some handy tools to help you navigate these null reference issues: the null-conditional and null-coalescing operators. These operators provide ways to handle potential null values gracefully while keeping your code clean and readable.

In this article, you will learn precisely how each operator works, when they should be used, and code samples demonstrating them in action.

What is the Null-Conditional Operator?

The null-conditional operator (?.) is a unary operator in C# that checks if a variable is null before accessing its members. If the variable is null, the expression short-circuits and evaluates to null, preventing a NullReferenceException from being thrown.

Short-circuiting means that if any part of a chained expression evaluates to null, the remaining parts are skipped, and the entire expression evaluates to null.

For example, if customer?.ContactDetails is null in the expression customer?.ContactDetails?.Email?.Work, then Email?.Work is never evaluated, and the expression returns null.

This operator is handy when retrieving values from deeply nested properties in an object. For example, suppose you have an object with nested properties. You can use the null-conditional operator to safely access properties deep within the object without explicitly checking for null at each level. This makes your code more concise and readable, especially when dealing with complex data structures.

// Without null-conditional operator
string? name = null;
if (customer != null && customer.Address != null)
{
    name = customer.Address.StreetName;
}

// With null-conditional operator
var? name = customer?.Address?.StreetName;

In the example above, the second statement using the null-conditional operator achieves the same result as the first, but in a much more succinct way. If either customer or Address is null, the expression will evaluate to null, preventing a potential NullReferenceException.

A word of caution: while the null-conditional operator is quite helpful, you should only use it when it makes sense for a property to be null. Otherwise, you might run into some nasty surprises. For example, in the code snippet below, you already know customer is not null, so it's unnecessary to use the operator on that variable:

// Previously in the same code block:
if (customer is null) throw new CustomerNotFoundException();

// With null-conditional operator on everything (bad)
var streetNumber = customer?.Address?.Street?.Number;

// With null-conditional operator on nullable properties (good)
var streetNumber = customer.Address?.Street?.Number;

While the example above might be harmless, there are cases where it can lead to strange bugs. For example, an expression might be evaluated as null, but it could be caused by a property in the expression chain you don't expect.

What is the Null-Coalescing Operator?

The null-coalescing operator is a binary operator that offers a concise method to manage null values. If the left operand if it is not null, it returns that; otherwise, it returns the right operand.

The syntax looks like this:

result = value1 ?? value2;

In this case, if value1 is not null, the result will be assigned the value of value1. However, if value1 is null, the result will be assigned the value of value2.

This is useful when providing a default value for a nullable variable. For example, you might want to display a default value if a customer's address is a null string:

var customerAddress = customer?.Address;
var displayAddress = customerAddress ?? "Unknown Address";

If the customer's address is specified, it'll be assigned to displayAddress. Otherwise, "Unknown Address" will be assigned to the variable.

You can even use the null-coalesce operator with the null-conditional operator shown above. For example, the above snippet could be combined into a single line like this:

var displayAddress = customer?.Address ?? "Unknown Address";

Now, if the customer variable is null, the null-conditional operator will short-circuit the expression and return null. However, since we have a null-coalesce operator in the same line, "Unknown Address" is assigned to the displayAddress variable instead.

You can also use the null-coalescing operator in an assignment operation (??=). This is useful if you have an existing variable and only want to assign a value if the current value is null. The snippet below demonstrates this:

var customerName = customer?.Name;

// Without null-coalesce assignment operator
customerName = customerName ?? "No name provided";

// With null-coalesce assignment operator
customerName ??= "No name provided";

Like the null-conditional operator, only use this operator when it makes sense. It's easy to fall into the habit of blindly assigning default values without considering whether they make sense. Sometimes a null is the best option:

// Here we assign "0" if a street number is not specified in
// an address... but does that make sense?
address.StreetNumber = request.Address.StreetNumber ?? "0";

In the example above, a default value of "0" is assigned to StreetNumber if none is specified in the request object. However, this can be confusing. Imagine that the address is used for a delivery, and the driver mistakenly gets lost looking for a house with street number 0. In this case, it's probably better to leave it blank or null if it's not applicable.

Conclusion

You've undoubtedly bumped into NullReferenceExceptions, and they can be frustrating. Fortunately, C# provides operators specifically designed to streamline null handling and prevent those pesky exceptions from being thrown.

The null-conditional operator (?.) lets you safely access members of potentially null objects, while the null-coalescing operator (??) provides a concise way to supply default values when encountering nulls. Understanding and using these operators appropriately helps you write clear, robust C# code that gracefully handles null values.

Extension Methods in C#

Ivan Kahl — Mon, 21 Mar 2022 13:05:19 +0000

Have you ever needed to extend a class provided by a third-party library? Perhaps you want to add additional functionality or simplify a particular set of methods in the library.

A common approach to solving this problem might be to create a class that inherits the third-party class and has the additional functionality you need.

public class ExtendedThirdPartyClass : ThirdPartyClass
{
    // Add my extra functionality here.
}

While this is a potential solution, we will run into problems if the class we're trying to inherit from is sealed. This is because a sealed class prevents any other classes from being able to inherit it (read more here).

Our next solution could be to write a wrapper class and then add our additional functionality there. This would look something like this:

public class ExtendedThirdPartyClass
{
     private ThirdPartyClass _underlyingClass;

     // Add method from ThirdPartyClass here which forward the
     // calls to _underlyingClass;

     // Add my extra functionality here.
}

This could work, but it's a lot of effort! We will have to rewrite each of the methods in ThirdPartyClass in our ExtendedThirdPartyClass and forward the method calls to our underlying ThirdPartyClass. While there are tools that can assist with this (ReSharper), it could result in a lot of unnecessary code and make it harder to see what functionality is part of ThirdPartyClass and what functionality is our own when looking at the ExtendedThirdPartyClass code. On top of that, we might also have to implement the underlying interfaces that ThirdPartyClass implements in our ExtendedThirdPartyClass which can also get messy.

I am by no means trying to bash either of the above approaches. There might be a use case that requires one of the above solutions in which case it would be better to use one of those. We are simply looking at a common problem and possible solutions for that problem so that we can provide context for another potential solution: Extension Methods!

Extension methods are methods that allow you to add extra functionality/methods to an existing type without having to inherit the type or write a wrapper around it. These methods give us a powerful way of writing additional functionality with minimal effort and code.

Structure of an extension method

Let's look at three rules on how extension methods are structured before diving into some examples.

Extension methods live in static classes

Extension methods can only be created inside static classes in .NET. This might seem a bit frustrating (especially if we already have another class with related logic), but it helps a lot! Having a separate class for extension methods helps with code organization and helps us clearly identify methods which are extension methods for other types.

Extension methods are static methods

Since extension methods aren't called on an instance of the class that they're in (this would never be possible since the class is static), we need to also make the method static.

The "this" parameter keyword

The this keyword on the first parameter of the method is what makes this method an extension method. By adding the this keyword to the first parameter, we can now call this method on any object (whose type matches the type of the first parameter) as if this method is an instance method on that object.

When we call the extension method on an object, the object which we call the extension method on becomes the first parameter of the extension method. If this sounds a bit confusing, the diagram below might provide some clarity:

Examples

We now have an idea of how an extension method is structured in C#. Let's move onto some examples!

IsIn string extension method

In this first example, let's write a .IsIn(...) extension method for a string that will check whether the specified string is equal to one of the strings in the parameter list. A boolean is returned indicating if the specified string is equal to one of the strings in the parameter list.

To do this, we will use the params keyword in our parameters. You can read more about this here.

StringExtensions.cs

public static class StringExtensions
{
    public static bool IsIn(this string s, params string[] options)
    {
        // Very simple... we just call the .Contains method on the
        // array of strings. 
        return options.Contains(s);
    }
}

We can now call our extension method on any string. For example,

Program.cs

var day = "Monday";

Console.WriteLine(day.IsIn("Monday", "Tuesday", "Wednesday", "Thursday", "Friday"));
// Output: True

Console.WriteLine(day.IsIn("Saturday", "Sunday"));
// Output: False

Generic IsIn extension method

What if we wanted to be able to call our extension method on more than just strings. C# lets us use type parameters which allow us to create generic methods. The good news is that we can make use of generic types in extension methods as well!

IsInExtension.cs

public static class IsInExtension
{
    public static bool IsIn<T>(this T s, params T[] options)
    {
        return options.Contains(s);
    }
}

We can now call our .IsIn(...) method on almost any type:

Program.cs

/*
 * Example 1: With a string
 */

var day = "Monday";

Console.WriteLine(day.IsIn("Monday", "Tuesday", "Wednesday", "Thursday", "Friday"));
// Output: True

Console.WriteLine(day.IsIn("Saturday", "Sunday"));
// Output: False

/*
 * Example 2: With an enum
 */

var level = Levels.High;

Console.WriteLine(level.IsIn(Levels.High, Levels.SuperHigh));
// Output: True

Console.WriteLine(level.IsIn(Levels.SuperLow, Levels.Low));
// Output: False

enum Levels 
{
    SuperLow,
    Low,
    Medium,
    High,
    SuperHigh
};

Look how neat and versatile that is! By writing a very simple extension method, we are able to write neater code. And by making it generic, we have a flexible method that we only need to write once and can then use with multiple types.

You'll notice that we don't specify the type explicity when calling the .IsIn<>(...) method. This is because .NET is able to determine the generic type based on the arguments provided to the method.

Bonus example: A fluent API for MailMessage

Have you ever worked with the System.Net.Mail API? If so, you've probably written code that might look something like this:

Program.cs

using System.Net.Mail;

var message = new MailMessage();

message.To.Add(new MailAddress("ivan@example.com", "Ivan Kahl"));
message.From = new MailAddress("system@example.com", "System")
message.Subject = "System Usage Notification";
message.Body = "<p>Hi there Ivan,</p><p>This is just a notification for you.</p>";
message.IsBodyHtml = true;

var smtpClient = new SmtpClient();
smtpClient.Send(message);

That's okay, but what if we had a fluent API for MailMessage that let us chain methods together to build an email? Would that not look a bit neater? I think so!

Let's give it a shot. Here are the extension methods:

MailMessageExtensions.cs

using System.Net.Mail;

public static class MailMessageExtensions
{
    public static MailMessage AddTo(this MailMessage message, string address,
        string? name = null)
    {
        message.To.Add(name == null
            ? new MailAddress(address)
            : new MailAddress(address, name));

        return message;
    }

    public static MailMessage SetFrom(this MailMessage message, string address,
        string? name = null)
    {
        message.From = name == null
            ? new MailAddress(address)
            : new MailAddress(address, name);

        return message;
    }

    public static MailMessage SetSubject(this MailMessage message, string subject)
    {
        message.Subject = subject;
        return message;
    }

    public static MailMessage SetHtmlBody(this MailMessage message, string html)
    {
        message.Body = html;
        message.IsBodyHtml = true;
        return message;
    }

    public static MailMessage SetPlaintextBody(this MailMessage message, string plaintext)
    {
        message.Body = plaintext;
        message.IsBodyHtml = false;
        return message;
    }

    public static void Send(this MailMessage message, SmtpClient client)
    {
        client.Send(message);
    }
}

We can now construct that same email message using the same MailMessage object but with our extension methods instead! Take a look:

Program.cs

using System.Net.Mail;

var smtpClient = new SmtpClient();

new MailMessage()
    .AddTo("ivan@example.com", "Ivan Kahl")
    .SetFrom("system@example.com", "System")
    .SetSubject("System Usage Notification")
    .SetHtmlBody("<p>Hi there Ivan,</p><p>This is just a notification for you.</p>")
    .Send(smtpClient);

The chained extension methods make the code much more descriptive and clear - and it was very easy to achieve with extension methods!

Closing

I hope this has given you some insight into what extension methods are in C# and how we can use them. They allow us to very easily add new functionality to an existing type without having to inherit from or write a wrapper around that type.

As with all design patterns, make sure you don't abuse it! There is a place for everything! While extension methods are neat, they might not always be the solution to your problem. So be careful with how and where you choose to use them.

I hope this article helped. If you have any questions or something to add, please leave a comment below.

Case-sensitive and Case-insensitive String Comparisons in PowerShell

Ivan Kahl — Sat, 18 Dec 2021 07:34:08 +0000

I wrote a PowerShell script the other day and, while doing so, discovered an interesting fact about string comparison in PowerShell that is quite contrary to .NET (and thus unfamiliar for me): string comparisons are case-insensitive by default.

This caught me off-guard since my particular use case required a case-sensitive comparison. I managed to get case-sensitive comparisons to work and thought I'd share it.

Using the Equals operator (-eq/-ceq)

When you would like to see if two strings are exactly the same, you can make use of the equals operator.

Case-Insensitive Equals (-eq)

You can use -eq to perform a case-insensitive string comparison.

❯ "Ivan Kahl's Blog" -eq "ivan kahl's BLOG"
True

Case-Sensitive Equals (-ceq)

If you would like to do a case-sensitive string comparison, you can use -ceq:

❯ "Ivan Kahl's Blog" -ceq "ivan kahl's BLOG"
False

Using the Like operator (-like/-clike)

You can also use patterns for string comparisons using the Like operator in Powershell.

Case-Insensitive Like (-like)

If you want to use a pattern for string comparison and not worry about the case, use -like:

❯ "Ivan Kahl's Blog" -like "ivan kahl's*"
True

Case-Sensitive Like (-clike)

If you do want to check case while using string patterns, you can make use of -clike:

❯ "Ivan Kahl's Blog" -clike "ivan kahl's*"
False

Closing

I hope you found this quick tip useful. If you have any questions or thoughts, please leave a comment below.

Logging .NET to AWS CloudWatch: Using NLog

Ivan Kahl — Tue, 14 Dec 2021 08:32:53 +0000

In the first post of this series, we used a low-level, first-principles approach to log messages to AWS CloudWatch. Now that we have an understanding of how the logging works under the hood, we are now going to see how we can configure NLog to log to AWS CloudWatch. This is recommended over trying to write your own logger as NLog is properly tested and has error handling for when it writes to AWS CloudWatch.

Video

Prerequisites

AWS Account

You will need an active AWS account that we can use to push logs from our .NET application to AWS CloudWatch. Our volumes will be minimal so we shouldn't exceed the free tier for AWS CloudWatch.

If you don't have an AWS account yet, you can sign up for one here.

AWS Profile

Since this article is just focusing on AWS CloudWatch, we won't be configuring any AWS credentials in our .NET application. Rather, we will let the AWS SDK automatically use our AWS profile that is set up when running the AWS CLI. This simplifies the demonstrations as we don't have to fumble around with permissions and credentials.

However, please note that you should always make sure to give applications their own IAM roles/users in production with minimal permissions according to AWS best practices.

Let's Go!

With that out the way, let's get started!

1. Create a new Console application

We will run this demo in a .NET 6 Console application. You can create it using either Visual Studio 2022 or the .NET 6 CLI. I will be using Visual Studio 2022.

2. Add the NLog package and set up a logger

Let's first add the NLog Nuget package and set up a basic logger. Afterwards, we'll configure this logger to also log to AWS CloudWatch.

Install the NLog Nuget package (4.7.13 at the time of writing).

We can now configure NLog and log some messages to our Console to test the configuration:

Program.cs

using NLog;
using NLog.Config;
using NLog.Targets;

// Setup the NLog configuration
var config = new LoggingConfiguration();
config.AddRule(LogLevel.Trace, LogLevel.Fatal, new ConsoleTarget());

LogManager.Configuration = config;

// Create a new logger and test it
var log = LogManager.GetCurrentClassLogger();

log.Trace("Writing introduction message...");

log.Info("Hi there! How are you?");

log.Trace("Wrote introduction message!");

You should see the following output:

3. Install the AWS.Logger.NLog

AWS provides a very nice NLog Target library that allows NLog to log directly to AWS CloudWatch. Let's install it now (we are installing 3.0.0 at the time of writing).

4. Setup the AWS CloudWatch Target on our logger

We can now create an NLog Target for AWS CloudWatch and our logger should start logging in there as well!

Program.cs

using NLog;
using NLog.AWS.Logger;
using NLog.Config;
using NLog.Targets;

// Setup the NLog configuration
var config = new LoggingConfiguration();
config.AddRule(LogLevel.Trace, LogLevel.Fatal, new ConsoleTarget());

// Add the AWS Target with minimal configuration
config.AddRule(LogLevel.Trace, LogLevel.Fatal, new AWSTarget()
{
    LogGroup = "/dotnet/logging-demo/nlog"
});

LogManager.Configuration = config;

// Create a new logger and test it
var log = LogManager.GetCurrentClassLogger();

log.Trace("Writing introduction message...");

log.Info("Hi there! How are you?");

log.Trace("Wrote introduction message!");

If you run the program, you should see the following logs appear in our AWS CloudWatch:

5. (Optional) Customising the AWS CloudWatch Target

We can customise the configuration for the AWS Target for NLog. Let's take a look at some of the configuration options available to us:

Program.cs

using Amazon.Runtime;
using NLog;
using NLog.AWS.Logger;
using NLog.Config;
using NLog.Layouts;
using NLog.Targets;

// Setup the NLog configuration
var config = new LoggingConfiguration();
config.AddRule(LogLevel.Trace, LogLevel.Fatal, new ConsoleTarget());

// Add the AWS Target with minimal configuration
config.AddRule(LogLevel.Trace, LogLevel.Fatal, new AWSTarget()
{
    LogGroup = "/dotnet/logging-demo/nlog",
    // (Optional) How often batches of log messages should be pushed to AWS CloudWatch
    BatchPushInterval = TimeSpan.FromSeconds(3),
    // (Optional) Whether NLog should try create the log group if it does not exist or not
    DisableLogGroupCreation = false,
    // (Optional) The maximum number of log events that are kept in memory before being pushed to
    // AWS CloudWatch
    MaxQueuedMessages = 10000,
    // (Optional) A string to prefix log stream names with
    LogStreamNamePrefix = "Prefix",
    // (Optional) A string to suffix log stream names with
    LogStreamNameSuffix = "Suffix",
    // (Optional) AWS credentials that should be used to log into AWS and access AWS CloudWatch
    // Credentials = new BasicAWSCredentials(accessKey, secretKey), (Optional) The region that AWS
    // CloudWatch logs should be logged in. In this case it defaults to the AWS Profile's region
    Region = "af-south-1",
    // (Optional) Custom layout that should be used when formatting log messages
    Layout = new SimpleLayout("[${date} ${level:uppercase=true:truncate=3}] ${message} ${exception}")
});

LogManager.Configuration = config;

// Create a new logger and test it
var log = LogManager.GetCurrentClassLogger();

log.Trace("Writing introduction message...");

log.Info("Hi there! How are you?");

log.Trace("Wrote introduction message!");

Closing

As you can see, logging to AWS CloudWatch using existing .NET logging libraries is fairly straightforward. In this article, we've demonstrated how easy it is to integrate AWS CloudWatch with NLog. This is especially useful when you have an application that already uses NLog.

If you would like to find out more about NLog then you can view their documentation here. You can also find out more about the AWS Target for NLog here.

DEV Community: Ivan Kahl

Beyond CRUD: A Practical Guide to Modeling Business Processes in REST APIs

Choose Your Resources Carefully

Break Resources Into Sub-Resources

Model Actions as Sub-Resources

Promote Complex Actions to Root-Level Resources

Fall Back to Verbs When Nouns Don't Fit

Conclusion

8 NDepend Rules to Enforce Domain-Driven Design in .NET

A Brief Overview of NDepend and CQLinq

Protecting Architectural Boundaries

Rule 1: No Third-Party Dependencies in the Domain Layer

Enforcing Entity Encapsulation

Rule 2: Require Private Setters

Rule 3: Ban Public Parameterless Constructors

Rule 4: Enforce Immutable Collections

Enforce Value Object Integrity

Rule 5: Prevent Mutable Fields and Properties on Value Objects

Rule 6: Enforce Structural Equality on Value Objects

Enforcing Aggregate Root Consistency

Rule 7: Aggregate Roots Should Have Behavioural Methods

Rule 8: Aggregate Roots Should Reference Other Aggregates by ID Only

Conclusion

Decompiling the New C# 14 field Keyword

A Brief Overview of the field Keyword

Inspecting the IL Code

Identical Backing Fields

The Getter Implementation

The Setter Implementation

Potential Pitfalls to Consider When Refactoring to the field Keyword

Magic Strings and Reflection Will Break

Entity Framework Core

AutoMapper

The field Keyword Is Restricted to the Property

Targeting Fields with Attributes

Naming Conflicts with Existing Class Members

Conclusion

Mastering the C# Dispose Pattern

Resource Management in .NET

The Basic Dispose Pattern: A Simple Implementation

Consuming the IDisposable Class

The Full Dispose Pattern: Handling Unmanaged Resources

Disposing of Inherited Classes

Best Practices

Ensure Idempotency

Don't Throw Exceptions in Finalizers

Cascade Dispose Calls to Owned Resources

Always Call Base Class Dispose

Use SafeHandle to Managed Those Unmanaged Resources

Disposing Asynchronously with IAsyncDisposable

Conclusion

Stop Spaghetti SQL: Simplify Complex Queries with Postgres CTEs in Supabase

What Are CTEs?

The Problem with Complex SQL Queries

Solving Spaghetti SQL with CTEs

Optimizing CTE Performance

Advanced CTE Use Cases

Recursive CTEs

Batch Updates

Structure Business Logic into SQL Functions Using CTEs

Using CTEs Instead of Temporary Tables

Best Practices and Pitfalls

Choosing Between CTEs, Views, and Functions

Considering Performance

Common Mistakes and How to Avoid Them

Tips for Testing and Debugging CTEs

Conclusion

What's New in C# 14: Null-Conditional Assignments

Wait, Doesn't C# Already Have Null-Conditionals?

Prerequisites

Null-Conditional Assignments With Object Properties

Null-Conditional Assignments With Indexer Elements

Null-Conditional Assignments with Compound Assignments

Things To Keep In Mind

Side-Effect Prevention

Increment and Decrement Operators Aren't Supported

Don't Overuse It

Conclusion

What's New in C# 14: User-Defined Compound Assignments

Prerequisites

A Brief Overview of the `field` Keyword

Potential Pitfalls to Consider When Refactoring to the `field` Keyword

The `field` Keyword Is Restricted to the Property

Consuming the `IDisposable` Class

Use `SafeHandle` to Managed Those Unmanaged Resources

Disposing Asynchronously with `IAsyncDisposable`