Khalid Abuhakmeh

C# 15 Union Types: Build Serializable Workflows

Mon, 12 Oct 2026 00:00:00 GMT

Every few years I end up flirting with the idea of a state machine, and every time I remember how complicated it gets. With C# 15, .NET ships union types (what many of us call a C# discriminated union), and I wanted to see if they could shrink that problem down to one state value and one method.

In this post, we’ll build a serializable workflow on .NET 11 where Next always returns a member of a union, and we’ll save and rehydrate it as JSON.

Everything here ran on 11.0.100-rc.1, so expect details to shift before general availability. Updated: October 2026.

What Are C# 15 Unions?

A C# 15 union declares a type that holds exactly one value from a closed list of case types.

public union Result(Success, Failure);

public record Success(string Message);
public record Failure(int Code);

These are type unions, not enum-style tagged cases. The cases are ordinary types you declare yourself, and records work well for them.
Cases are not nested in the union. You write Result r = new Success("ok"); and the compiler adds the implicit conversion.
The compiler generates a struct that stores the active case in a single object? Value.
A switch expression that covers every case is exhaustive, so there’s no default arm. If you need a refresher on the syntax, see my C# pattern matching quick guide.

static string Describe(Result r) => r switch
{
    Success(var message) => message,
    Failure(var code) => $"Error {code}",
};

That exhaustiveness is the reason I wanted unions for workflows. Add a new case, and the compiler points at every place that forgot to handle it.

To follow along, install the .NET 11 SDK and target net11.0. C# 15 is the default language version there, but I pin it to be explicit.

<PropertyGroup>
  <TargetFramework>net11.0</TargetFramework>
  <LangVersion>15.0</LangVersion>
</PropertyGroup>

If you use Homebrew on macOS, its dotnet may be first on your PATH and quietly use an older SDK. Check with dotnet --version.

Four Unions, One Method

A workflow, in my definition, is state plus a single method. Four small unions describe everything that moves through it:

Union	Question it answers	Cases
`OrderState`	Where is the workflow?	`Drafted`, `Submitted`, `InReview`, `Approved`, `Rejected`, `Fulfilled`
`StepInput`	What is the caller sending in?	`NoInput`, `ApprovalAnswer`
`InputRequest`	What does a waiting step need?	`ApprovalRequest`, `ManagerApprovalRequest`
`StepResult`	What should the caller do next?	`Advance`, `AwaitInput`, `Finish`, `Fail`

// Where the workflow is. Each case carries only the data that state needs.
public union OrderState(Drafted, Submitted, InReview, Approved, Rejected, Fulfilled);

public record Drafted(string OrderId, decimal Amount);
public record Submitted(string OrderId, decimal Amount);
public record InReview(string OrderId, decimal Amount);
public record Approved(string OrderId, decimal Amount);
public record Rejected(string OrderId, string Reason);
public record Fulfilled(string OrderId);

// What the caller sends in.
public union StepInput(NoInput, ApprovalAnswer);

public record NoInput;
public record ApprovalAnswer(bool Approved, string? Comment);

// What a waiting step asks the caller for.
public union InputRequest(ApprovalRequest, ManagerApprovalRequest);

public record ApprovalRequest(string Question);
public record ManagerApprovalRequest(string Question, decimal Amount);

// What Next() tells the caller to do.
public union StepResult(Advance, AwaitInput, Finish, Fail);

public record Advance(OrderState State);
public record AwaitInput(InputRequest Request);
public record Finish(OrderState State);
public record Fail(string Reason);

StepResult is the contract. Every call to Next returns one of four things, and the caller must handle all four:

Advance: the workflow moved, so the caller can call Next again.
AwaitInput: it needs an answer, so the caller should collect one.
Finish: it reached a terminal state, so the caller should stop.
Fail: the input didn’t belong to this step, so the caller should handle the error.

A Naming Rule That Avoids Collisions

Because union cases aren’t nested in the union, every case name shares a namespace with your other types. Naming by tense keeps them apart:

States are past tense, because they describe what has already happened: Submitted, Approved, Rejected, Fulfilled.
Results are present-tense instructions to the caller: Advance, AwaitInput, Finish, Fail.
Inputs and requests are nouns: ApprovalAnswer, ManagerApprovalRequest.

A state is a condition and a result is a command, so the sets never overlap, and the caller reads like a script. Fail is a technical failure, like input sent to the wrong step. A business “no” such as Rejected arrives as a Finish carrying a Rejected state.

How Do You Type Workflow Input?

Make the input a union too. The tempting alternative is Next(object? input) with type checks inside each step. That compiles, but the compiler can’t tell you what a step expects, and null ends up meaning both “no input” and “a mistake”.

With StepInput, there’s no null at all. NoInput means “I’m just asking what’s next”, and every step handles each input case. A waiting step also tells the caller what it wants with a typed InputRequest, instead of a prompt string.

The Workflow

Here’s the whole workflow class. Next is one switch expression, so the compiler checks that every state, and every input for a state that waits, is handled.

public sealed class OrderWorkflow
{
    public OrderState State { get; private set; }

    private OrderWorkflow(OrderState state) => State = state;

    public static OrderWorkflow Create(string orderId, decimal amount) =>
        new(new Drafted(orderId, amount));

    public static OrderWorkflow FromState(OrderState state) => new(state);

    public StepResult Next(StepInput input) => State switch
    {
        Drafted(var id, var amount) =>
            NoInputOnly(input, () => MoveTo(new Submitted(id, amount))),

        Submitted(var id, var amount) => input switch
        {
            NoInput => new AwaitInput(new ApprovalRequest("Approve submission for review?")),
            ApprovalAnswer(false, _) => EndWith(new Rejected(id, "Submission not approved for review.")),
            ApprovalAnswer(true, _) when amount > 1000m => MoveTo(new InReview(id, amount)),
            ApprovalAnswer(true, _) => MoveTo(new Approved(id, amount)),
        },

        InReview(var id, var amount) => input switch
        {
            NoInput => new AwaitInput(new ManagerApprovalRequest("Manager approval required.", amount)),
            ApprovalAnswer(false, _) => EndWith(new Rejected(id, "Manager rejected the order.")),
            ApprovalAnswer(true, _) => MoveTo(new Approved(id, amount)),
        },

        Approved(var id, _) => NoInputOnly(input, () => EndWith(new Fulfilled(id))),

        Rejected => EndWith(State),
        Fulfilled => EndWith(State),
    };

    private StepResult MoveTo(OrderState next)
    {
        State = next;
        return new Advance(State);
    }

    private StepResult EndWith(OrderState terminal)
    {
        State = terminal;
        return new Finish(State);
    }

    // Steps that don't wait for anything reject unexpected input.
    private static StepResult NoInputOnly(StepInput input, Func<StepResult> step) => input switch
    {
        NoInput => step(),
        ApprovalAnswer => new Fail("This step does not take input."),
    };
}

Add a new StepInput case, and every input switch above lights up with a warning until you handle it. Add a new state, and the outer State switch warns the same way.

Driving the Workflow

The caller loops until it gets a Finish or a Fail. Notice that the caller answers a request by switching on its type, which is exhaustive too.

static StepResult Run(OrderWorkflow wf, bool[] answers)
{
    var queue = new Queue<bool>(answers);
    StepInput input = new NoInput();

    while (true)
    {
        var result = wf.Next(input);

        switch (result)
        {
            case Finish:
            case Fail:
                return result;
            case AwaitInput(var request):
                input = Answer(request, queue.Dequeue()); // in real life: a person or a webhook
                break;
            case Advance:
                input = new NoInput();
                break;
        }
    }
}

static StepInput Answer(InputRequest request, bool approve) => request switch
{
    ApprovalRequest => new ApprovalAnswer(approve, null),
    ManagerApprovalRequest => new ApprovalAnswer(approve, "Reviewed by manager"),
};

For a $250 order, the workflow walks Drafted → Submitted → Approved → Fulfilled. For a $9,999 order, it takes a detour through InReview, and a “no” from the manager lands in Rejected:

state=InReview(id=order-3, amount=9999) -> AwaitInput(ManagerApprovalRequest: Manager approval required. (9999))
state=Rejected(id=order-3, reason=Manager rejected the order.) -> Finish(Rejected(id=order-3, reason=Manager rejected the order.))

Sending an answer to a step that isn’t waiting gives you a Fail rather than an exception:

Fail(This step does not take input.)

If you’ve ever written a C# state machine with an enum and a giant switch, the difference is that each state brings only the data it needs. A Rejected state has a reason, and a Drafted state doesn’t.

How Do You Serialize and Rehydrate a Union Workflow?

A workflow that can wait for a human is only useful if you can stop the process and pick it up later. That means serializing the current state and rehydrating it.

Serialize and rehydrate by persisting the State with an explicit discriminator. By default, System.Text.Json in .NET 11 serializes a union by writing only the active case’s JSON, so new Submitted("order-1", 250m) becomes {"OrderId":"order-1","Amount":250} with no tag. Reading it back works when the cases map to different JSON token types, such as a string and an object. Two object-shaped cases are ambiguous, so Deserialize<OrderState> throws:

JsonException: JSON value type 'Object' is ambiguous for union type 'OrderState'
because multiple case types can use this value type. Specify a custom type
classifier to support deserialization.

For stored workflow state, I don’t want to depend on shape-guessing. (If you’ve handled this for class hierarchies, it’s the same idea as polymorphic serialization with System.Text.Json.) I want an explicit tag that survives refactoring, so the state gets a small converter that wraps each case as {"$case": "...", "value": {...}}.

public sealed class OrderStateConverter : JsonConverter<OrderState>
{
    public override OrderState Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        using var doc = JsonDocument.ParseValue(ref reader);
        var kind = doc.RootElement.GetProperty("$case").GetString();
        var value = doc.RootElement.GetProperty("value");

        return kind switch
        {
            nameof(Drafted) => (OrderState)value.Deserialize<Drafted>(options)!,
            nameof(Submitted) => (OrderState)value.Deserialize<Submitted>(options)!,
            // ...one arm per case
            _ => throw new JsonException($"Unknown OrderState case '{kind}'"),
        };
    }

    public override void Write(Utf8JsonWriter writer, OrderState value, JsonSerializerOptions options)
    {
        writer.WriteStartObject();
        switch (value)
        {
            case Drafted d:
                writer.WriteString("$case", nameof(Drafted));
                writer.WritePropertyName("value");
                JsonSerializer.Serialize(writer, d, options);
                break;
            // ...one arm per case
        }
        writer.WriteEndObject();
    }
}

The persisted JSON is small and readable:

{"$case":"InReview","value":{"OrderId":"order-2","Amount":9999}}

Rehydrating is one line each way, because the whole workflow is its State:

var json = JsonSerializer.Serialize(wf.State, options);
wf = OrderWorkflow.FromState(JsonSerializer.Deserialize<OrderState>(json, options)!);

You don’t need to persist a pending question. After rehydrating a workflow that was waiting, call Next(new NoInput()) and it asks again with the same InputRequest.

To prove it works, the complete program at the end of this post serializes after every Next call, builds a brand-new OrderWorkflow from the JSON, and keeps driving that copy. It then asserts that the outcome matches an uninterrupted run. That holds for the approved path, the manager-review path, and the rejected path.

Things to Watch For

Prefer switch expressions. Only switch expressions get the union exhaustiveness check. A switch statement over a union isn’t treated as exhaustive, so a method ending in one fails with CS0161 unless you add a trailing throw.
Unions are structs, so default is a trap. default(OrderState).Value is null. With nullable reference types on, a switch expression over a union warns CS8655 because null isn’t covered, and switching on a default union throws SwitchExpressionException at run time. Always initialize union fields.
Value-type cases are boxed. Everything lives in an object? Value.
?. and nullable returns don’t compile on unions. You’ll see CS0023 for ?., and CS0508 if a JsonConverter<OrderState> override returns OrderState?. That’s another reason NoInput beats null.
Nested unions and overlapping JSON shapes aren’t supported by the built-in classifier, per the System.Text.Json docs.
It’s a release candidate. The “What’s new in C# 15” page still describes C# 15 as preview, while the RC1 release notes say unions are stabilized. Behavior may change before GA.

Where to Go From Here

A few things this post leaves open, if you want to take it further:

Closed hierarchies with [JsonDerivedType]. The docs describe explicit discriminators through [JsonDerivedType(typeof(X), "tag")], and .NET 11 can infer polymorphism from a closed hierarchy. That could replace the hand-written converter.
Native AOT and source generation. I haven’t checked the converter under either.
Versioning. Rename Submitted, and stored $case values stop matching. A real system needs a version field or a migration step.
Per-state inputs. StepInput is shared by every step, so a step can still receive an input meant for another and answers with Fail. Making that impossible needs per-state input types, which means generics or more than one method.

Conclusion

Four small unions and one Next method cover the whole workflow, and the compiler flags every state, input, and result you forget to handle. The persisted state is a tagged JSON object that rehydrates to the same outcome as an uninterrupted run.

Next, try replacing the hand-written converter with [JsonDerivedType] and see how much code you can delete. If it works for your cases, I’d like to hear about it.

Thanks to the C# language team for shipping this one.

Complete Program

Here’s the whole thing in one file. Run dotnet new console with the .NET 11 SDK, set <LangVersion>15.0</LangVersion> in the project file, replace Program.cs with the code below, and run it. It runs the workflow with and without serialization, then prints the JSON at every step.

using System.Text.Json;
using System.Text.Json.Serialization;

// ---------------------------------------------------------------------------
// Demo: run a workflow with and without serialize/rehydrate at every step.
// ---------------------------------------------------------------------------

Console.WriteLine("=== Run A: uninterrupted ===");
var outcomeA = Run(OrderWorkflow.Create("order-1", 250m), [true, true], rehydrate: false);

Console.WriteLine();
Console.WriteLine("=== Run B: serialize/rehydrate at every step ===");
var outcomeB = Run(OrderWorkflow.Create("order-1", 250m), [true, true], rehydrate: true);

Console.WriteLine();
Console.WriteLine($"Run A outcome: {Describe(outcomeA)}");
Console.WriteLine($"Run B outcome: {Describe(outcomeB)}");
if (Describe(outcomeA) != Describe(outcomeB))
{
    throw new Exception("Mismatch between uninterrupted and rehydrated runs!");
}

Console.WriteLine();
Console.WriteLine("=== Run C: large order needs manager review (approved) ===");
var outcomeC = Run(OrderWorkflow.Create("order-2", 9999m), [true, true], rehydrate: true);
Console.WriteLine($"Run C outcome: {Describe(outcomeC)}");

Console.WriteLine();
Console.WriteLine("=== Run D: manager rejects the order ===");
var outcomeD = Run(OrderWorkflow.Create("order-3", 9999m), [true, false], rehydrate: true);
Console.WriteLine($"Run D outcome: {Describe(outcomeD)}");
if (!Describe(outcomeD).StartsWith("Finish(Rejected("))
{
    throw new Exception("Expected a rejected outcome.");
}

Console.WriteLine();
Console.WriteLine("=== Run E: input sent to a step that doesn't take input ===");
var outcomeE = OrderWorkflow.Create("order-4", 50m).Next(new ApprovalAnswer(true, null));
Console.WriteLine($"Run E outcome: {Describe(outcomeE)}");
if (outcomeE is not Fail)
{
    throw new Exception("Expected Fail.");
}

Console.WriteLine();
Console.WriteLine("ALL ASSERTIONS PASSED.");

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

// The caller drives the workflow. Every AwaitInput carries a typed request, so
// the caller knows what kind of answer to build.
static StepResult Run(OrderWorkflow wf, bool[] answers, bool rehydrate)
{
    var queue = new Queue<bool>(answers);
    StepInput input = new NoInput();

    while (true)
    {
        var result = wf.Next(input);
        Console.WriteLine($"  state={DescribeState(wf.State)} -> {Describe(result)}");

        if (rehydrate)
        {
            // Serialize the workflow after every Next() call, then keep driving
            // a brand-new instance built from the JSON.
            var json = WorkflowJson.Serialize(wf);
            Console.WriteLine($"      json: {json}");
            var rehydrated = WorkflowJson.Deserialize(json);
            if (DescribeState(wf.State) != DescribeState(rehydrated.State))
            {
                throw new Exception("Round-trip mismatch!");
            }

            wf = rehydrated;
        }

        switch (result)
        {
            case Finish:
            case Fail:
                return result;
            case AwaitInput(var request):
                input = Answer(request, queue.Dequeue());
                break;
            case Advance:
                input = new NoInput();
                break;
        }
    }
}

// The request type decides which answer is valid; the switch is exhaustive.
static StepInput Answer(InputRequest request, bool approve) => request switch
{
    ApprovalRequest => new ApprovalAnswer(approve, null),
    ManagerApprovalRequest => new ApprovalAnswer(approve, "Reviewed by manager"),
};

static string Describe(StepResult r) => r switch
{
    Advance(var state) => $"Advance({DescribeState(state)})",
    AwaitInput(var request) => $"AwaitInput({DescribeRequest(request)})",
    Finish(var state) => $"Finish({DescribeState(state)})",
    Fail(var reason) => $"Fail({reason})",
};

static string DescribeRequest(InputRequest r) => r switch
{
    ApprovalRequest(var question) => $"ApprovalRequest: {question}",
    ManagerApprovalRequest(var question, var amount) => $"ManagerApprovalRequest: {question} ({amount})",
};

static string DescribeState(OrderState s) => s switch
{
    Drafted(var id, var amount) => $"Drafted(id={id}, amount={amount})",
    Submitted(var id, var amount) => $"Submitted(id={id}, amount={amount})",
    InReview(var id, var amount) => $"InReview(id={id}, amount={amount})",
    Approved(var id, var amount) => $"Approved(id={id}, amount={amount})",
    Rejected(var id, var reason) => $"Rejected(id={id}, reason={reason})",
    Fulfilled(var id) => $"Fulfilled(id={id})",
};

// =============================================================================
// Union declarations (C# 15 `union` feature)
//
// Naming: states are past tense (what has happened). Results are present-tense
// instructions to the caller. Inputs and requests are nouns.
// =============================================================================

// States. Each case carries only the data that state needs.
public union OrderState(Drafted, Submitted, InReview, Approved, Rejected, Fulfilled);

public record Drafted(string OrderId, decimal Amount);
public record Submitted(string OrderId, decimal Amount);
public record InReview(string OrderId, decimal Amount);
public record Approved(string OrderId, decimal Amount);
public record Rejected(string OrderId, string Reason);
public record Fulfilled(string OrderId);

// What the caller sends in.
public union StepInput(NoInput, ApprovalAnswer);

public record NoInput;
public record ApprovalAnswer(bool Approved, string? Comment);

// What a waiting step asks the caller for.
public union InputRequest(ApprovalRequest, ManagerApprovalRequest);

public record ApprovalRequest(string Question);
public record ManagerApprovalRequest(string Question, decimal Amount);

// What Next() tells the caller to do.
public union StepResult(Advance, AwaitInput, Finish, Fail);

public record Advance(OrderState State);
public record AwaitInput(InputRequest Request);
public record Finish(OrderState State);
public record Fail(string Reason);

// =============================================================================
// Workflow
// =============================================================================

public sealed class OrderWorkflow
{
    public OrderState State { get; private set; }

    private OrderWorkflow(OrderState state) => State = state;

    public static OrderWorkflow Create(string orderId, decimal amount) =>
        new(new Drafted(orderId, amount));

    public static OrderWorkflow FromState(OrderState state) => new(state);

    // The ONE method. Always returns a StepResult, and takes a typed StepInput.
    public StepResult Next(StepInput input) => State switch
    {
        Drafted(var id, var amount) => NoInputOnly(input, () => MoveTo(new Submitted(id, amount))),

        Submitted(var id, var amount) => input switch
        {
            NoInput => new AwaitInput(new ApprovalRequest("Approve submission for review?")),
            ApprovalAnswer(false, _) => EndWith(new Rejected(id, "Submission not approved for review.")),
            ApprovalAnswer(true, _) when amount > 1000m => MoveTo(new InReview(id, amount)),
            ApprovalAnswer(true, _) => MoveTo(new Approved(id, amount)),
        },

        InReview(var id, var amount) => input switch
        {
            NoInput => new AwaitInput(new ManagerApprovalRequest("Manager approval required.", amount)),
            ApprovalAnswer(false, _) => EndWith(new Rejected(id, "Manager rejected the order.")),
            ApprovalAnswer(true, _) => MoveTo(new Approved(id, amount)),
        },

        Approved(var id, _) => NoInputOnly(input, () => EndWith(new Fulfilled(id))),

        Rejected => EndWith(State),
        Fulfilled => EndWith(State),
    };

    private StepResult MoveTo(OrderState next)
    {
        State = next;
        return new Advance(State);
    }

    private StepResult EndWith(OrderState terminal)
    {
        State = terminal;
        return new Finish(State);
    }

    // Steps that don't wait for anything reject unexpected input.
    private static StepResult NoInputOnly(StepInput input, Func<StepResult> step) => input switch
    {
        NoInput => step(),
        ApprovalAnswer => new Fail("This step does not take input."),
    };
}

// =============================================================================
// JSON serialization support
// =============================================================================
//
// What was tried:
//
// 1. Default System.Text.Json behavior for a `union`. Serializing writes only the
//    active case's own JSON (no discriminator), and deserializing throws a
//    JsonException ("ambiguous for union type ... specify a custom type classifier")
//    when more than one case could match the JSON shape.
//
// 2. An explicit discriminator written by hand: every state is serialized as
//    { "$case": "<name>", "value": { ... } } via a custom JsonConverter<OrderState>.
//    This is what's used below.

public sealed class OrderStateConverter : JsonConverter<OrderState>
{
    public override OrderState Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        using var doc = JsonDocument.ParseValue(ref reader);
        var root = doc.RootElement;
        var kind = root.GetProperty("$case").GetString();
        var value = root.GetProperty("value");

        return kind switch
        {
            nameof(Drafted) => (OrderState)value.Deserialize<Drafted>(options)!,
            nameof(Submitted) => (OrderState)value.Deserialize<Submitted>(options)!,
            nameof(InReview) => (OrderState)value.Deserialize<InReview>(options)!,
            nameof(Approved) => (OrderState)value.Deserialize<Approved>(options)!,
            nameof(Rejected) => (OrderState)value.Deserialize<Rejected>(options)!,
            nameof(Fulfilled) => (OrderState)value.Deserialize<Fulfilled>(options)!,
            _ => throw new JsonException($"Unknown OrderState case '{kind}'"),
        };
    }

    public override void Write(Utf8JsonWriter writer, OrderState value, JsonSerializerOptions options)
    {
        writer.WriteStartObject();
        switch (value)
        {
            case Drafted d:
                writer.WriteString("$case", nameof(Drafted));
                writer.WritePropertyName("value");
                JsonSerializer.Serialize(writer, d, options);
                break;
            case Submitted s:
                writer.WriteString("$case", nameof(Submitted));
                writer.WritePropertyName("value");
                JsonSerializer.Serialize(writer, s, options);
                break;
            case InReview m:
                writer.WriteString("$case", nameof(InReview));
                writer.WritePropertyName("value");
                JsonSerializer.Serialize(writer, m, options);
                break;
            case Approved a:
                writer.WriteString("$case", nameof(Approved));
                writer.WritePropertyName("value");
                JsonSerializer.Serialize(writer, a, options);
                break;
            case Rejected r:
                writer.WriteString("$case", nameof(Rejected));
                writer.WritePropertyName("value");
                JsonSerializer.Serialize(writer, r, options);
                break;
            case Fulfilled c:
                writer.WriteString("$case", nameof(Fulfilled));
                writer.WritePropertyName("value");
                JsonSerializer.Serialize(writer, c, options);
                break;
            default:
                throw new JsonException($"Unknown OrderState case '{value.GetType()}'");
        }

        writer.WriteEndObject();
    }
}

public static class WorkflowJson
{
    private static readonly JsonSerializerOptions Options = new()
    {
        WriteIndented = false,
        Converters = { new OrderStateConverter() },
    };

    public static string Serialize(OrderWorkflow wf) =>
        JsonSerializer.Serialize(wf.State, Options);

    public static OrderWorkflow Deserialize(string json)
    {
        var state = JsonSerializer.Deserialize<OrderState>(json, Options)!;
        return OrderWorkflow.FromState(state);
    }
}

Sources

Directory.Build.props: Share Settings Across .NET Projects

Mon, 12 Oct 2026 00:00:00 GMT

Directory.Build.props is an MSBuild file that sets properties and package references once for every project below it in the folder tree. MSBuild finds it on its own, imports it before the project’s own settings, and lets any .csproj override a value by setting it again.

<Project>

  <PropertyGroup>
    <Nullable>enable</Nullable>
  </PropertyGroup>

</Project>

Drop that at the root of your solution, next to the .sln file, and every project below it gets Nullable enabled without you touching a single .csproj.

What Is Directory.Build.props and How Does MSBuild Find It?

MSBuild finds the file on its own, with no setup step. The SDK-style project format (Microsoft.NET.Sdk) imports a tiny bit of MSBuild logic (Sdk.props) at the very top of every project, and that logic searches upward from the project’s directory for a file named Directory.Build.props, stopping at the first one it finds. It does not keep walking further up and merging multiple copies; it imports exactly one.

Because the import happens near the top of the project file, before your project’s own <PropertyGroup> elements are evaluated, any property you set later in the .csproj wins. In my test, a root file set Nullable to enable and one project’s .csproj set it to disable. That project got disable, and its siblings kept enable. Put sensible defaults in the shared file and override them per project when you need to.

What Does a Typical Directory.Build.props Look Like?

Here’s one for Directory.Build.props a solution with a class library, a web API, and a test project:

<Project>

  <PropertyGroup>
    <LangVersion>latest</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <Authors>Khalid Abuhakmeh</Authors>
    <Company>Example Co</Company>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Roslynator.Analyzers" Version="5.0.1">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>

</Project>

After adding this, individual project files shrink down to just what’s actually different per project:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.12" />
  </ItemGroup>

</Project>

No more Nullable, ImplicitUsings, or Authors repeated in every project. Running dotnet msbuild -getProperty:Authors on each project showed all three picking up Khalid Abuhakmeh from the shared file, and the analyzer reference showed up in all three builds. For the other files that live next to your projects, see common files in a .NET solution.

What Happens When You Nest Directory.Build.props Files?

The closest file wins and nothing merges. If a subfolder has its own Directory.Build.props, MSBuild imports that one and never touches the root file.

To test it, I kept a root file that set Authors and TreatWarningsAsErrors, then added a second Directory.Build.props in one project’s parent folder with a single unrelated property. That project lost both values and fell back to MSBuild defaults, even though the root file sat a few folders up.

If you want a nested file to extend the root one instead of replacing it, import the parent explicitly:

<Project>

  <Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />

  <PropertyGroup>
    <!-- properties specific to this folder -->
  </PropertyGroup>

</Project>

With that Import line in the nested file, -getProperty:Authors and -getProperty:LangVersion returned the root values again, alongside the nested folder’s own property. It’s an easy mistake to add a nested file for one subdirectory and silently lose everything from the root.

When Should You Use Directory.Build.targets Instead?

Use Directory.Build.targets when your logic depends on values the project sets. Directory.Build.props is imported early, so it can’t see properties the project itself hasn’t set yet, like AssemblyName or TargetFramework as finalized by the SDK. If you need logic that reacts to those values, like a custom build target or a property that’s computed from something the project defines, put it in Directory.Build.targets instead. The SDK imports this file late, after the project body, so everything the project set is already in scope.

<Project>

  <Target Name="PrintBuildInfo" AfterTargets="Build">
    <Message Importance="high" Text="Building $(MSBuildProjectName) for $(TargetFramework), AssemblyName=$(AssemblyName)" />
  </Target>

</Project>

With this at the solution root, dotnet build printed each project’s real TargetFramework and AssemblyName, values that only exist after the project file is evaluated. Directory.Build.targets follows the same search rule as the props file, so a nested one replaces the root one unless you import it explicitly.

Use Directory.Packages.props for package versions. It’s a separate but related file: Directory.Packages.props, which enables central package management. Set ManagePackageVersionsCentrally to true and list versions once as PackageVersion items; your project files then reference packages by name only, no Version attribute.

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="Roslynator.Analyzers" Version="5.0.1" />
  </ItemGroup>
</Project>

Adding this file to my scratch solution immediately produced NuGet error NU1008 on every project that still had an explicit Version on a PackageReference. That includes the analyzer reference in the shared Directory.Build.props above, so remove its Version attribute once the version lives here. After that the split is simple: Directory.Build.props for compiler and analyzer settings, Directory.Packages.props for package versions.

File	Imported	Use it for
`Directory.Build.props`	Early, before the project body	Defaults projects can override, like `Nullable` or `LangVersion`
`Directory.Build.targets`	Late, after the project body	Targets and properties that depend on the project’s final values
`Directory.Packages.props`	With central package management enabled	Package versions, via `PackageVersion` items

If you publish packages, the shared Authors value also becomes your package’s author metadata. See the guide from idea to NuGet package for the rest of that workflow, and using environment variables in your .NET builds for pulling build-time values into properties.

How Do You Debug What Got Imported?

Two switches save you from guessing. First, ask MSBuild directly what value a property resolved to for a given project:

dotnet msbuild path/to/Project.csproj -getProperty:Nullable

Second, if you want to see the fully expanded project file, with every Import inlined, including Directory.Build.props and Directory.Build.targets, generate a preprocessed copy:

dotnet msbuild path/to/Project.csproj -pp:out.xml

I ran both against the scratch solution. -getProperty returned exactly the values each Directory.Build.props and .csproj combination should produce, and out.xml contained the flattened contents of the imported Directory.Build.props next to the project’s own elements. I tested on the .NET 10 SDK. -getProperty is a recent MSBuild switch, so on an older SDK check dotnet msbuild -h first.

For a view of the whole build, record a binary log and open it in MSBuildStructuredLog (project site), a free viewer by Kirill Osenkov. Pass -bl to dotnet build:

dotnet build -bl

That writes msbuild.binlog next to your solution. The log records the targets, tasks, and property and item values from the build, and the viewer lets you browse and search them. When a property comes out wrong, you can search the log for the property name and see where it was set, instead of guessing which file won.

Screenshot from the MSBuildStructuredLog repository, which is MIT licensed.

What Are the Common Gotchas?

Four things are easy to forget:

It applies to every project below it, including tests. If your test projects live under the same root as your main projects, they inherit everything from Directory.Build.props too, unless they’re under a nested folder with their own copy of the file.
Nesting replaces, it doesn’t merge. As shown above, a closer Directory.Build.props means the root one is skipped entirely unless you add the explicit Import.
File name casing matters on case-sensitive file systems. Windows and macOS default to case-insensitive file systems, so directory.build.props and Directory.Build.props are treated the same. On a case-sensitive Linux file system, the name has to match exactly, Directory.Build.props, or MSBuild won’t find it.
It’s imported before the project body, Directory.Build.targets after. Use .props for defaults you want projects to be able to override, and .targets for logic that needs to see the project’s final property values.

For the full reference on both files and how the SDK wires them in, see the official MSBuild docs on customizing your build.

Convert a String to an Int in C#

Mon, 05 Oct 2026 00:00:00 GMT

Converting a string to an int in C# is a daily chore, whether the value comes from user input, a query string, a config file, or a CSV. I’ll walk through the three built-in options—int.TryParse, int.Parse, and Convert.ToInt32—and when to reach for each.

int.TryParse : Convert a String Safely

When dealing with untrusted input, you’ll want to lean on int.TryParse. The method follows the typical TryX pattern found in other .NET APIs. On success, the method returns true and an out parameter containing the resulting value. On failure, it returns false and sets the out parameter to 0. This makes it easy to handle both success and failure cases without exceptions. Always branch on the bool return value, though: a failed parse leaves number at 0, which is indistinguishable from successfully parsing "0", so never infer success from the out value alone. It’s the same approach I reach for when reading and converting QueryCollection values in ASP.NET.

if (int.TryParse(input, out int number))
{
    // success — use `number`
}
else
{
    // failure — `number` is 0 here, but 0 is also a valid parse of "0",
    // so always check the bool, never the out value alone
}

int.TryParse is the best option for most developers when converting strings to integers, especially when the input may not be guaranteed to be valid.

int.Parse : Simple, but It Throws

When working with trusted input, int.Parse is your most straightforward option. Since you’re a developer either controlling the input or guaranteeing its format through strict validation, you can use int.Parse without worrying about exceptions (even though you should always worry about exceptions). Although, there are some edge cases as you can see in the example below.

int number = int.Parse("42");
// number == 42

// int.Parse("4a2")  -> throws FormatException
// int.Parse(null)   -> throws ArgumentNullException
// int.Parse("9999999999") -> throws OverflowException

Use int.Parse for quick prototypes and code samples for non-production code.

Convert.ToInt32 : The Null-Tolerant Option

You may be tempted to use the Convert class and its Convert.ToInt32 method. The key difference between the other approaches is this method treats null as 0 instead of throwing an exception. This can be useful in scenarios where a missing value should be interpreted as zero, but it can also lead to unexpected outcomes and bugs that will make you pull your hair out.

int a = Convert.ToInt32("42");   // 42
int b = Convert.ToInt32(null);   // 0  (no exception!)
// Convert.ToInt32("4a2")        -> throws FormatException

Leave this method in the toolbox and favor the other two approaches for more predictable behavior.

Why Does String-to-Int Parsing Fail?

Outside of parsing strings into integers, the biggest pain point you need to watch for is culture and format. By default, parsing uses the current culture and NumberStyles.Integer, which allows for a leading sign and surrounding whitespace only. This means that strings like "1,304" will fail unless you explicitly allow thousands separators and provide a culture. The .NET docs on parsing numeric strings cover the full set of NumberStyles rules.

You can use NumberStyles and CultureInfo to handle these cases properly. For example, the following code demonstrates how to parse a string with a thousands separator:

using System.Globalization;

int.TryParse("1,304", out var fails);          // false -> 0
int.TryParse("1,304",
    NumberStyles.Integer | NumberStyles.AllowThousands,
    CultureInfo.InvariantCulture,
    out var works);                             // true  -> 1304

If you’re hoping to deploy your code into multiple regions or region agnostic environments, consider using CultureInfo.InvariantCulture to ensure consistent parsing behavior across different locales. Culture sneaks into more string work than you’d expect—I ran into it again while writing a string numeric comparer with .NET 9.

Which Should You Use?

So given your options, which of these should you use? From personal experience, use int.TryParse by default. It is the safest and most efficient option for handling untrusted input, and it avoids exceptions that can disrupt your application’s flow. Use int.Parse only when you are certain the input is valid, and reserve Convert.ToInt32 for cases where you want to treat null as 0. Just remember to always consider the culture and format of the input string to avoid unexpected parsing issues.

Here is a quick reference for which method to use based on your input scenario:

Input Scenario	Recommended Method
Untrusted input	`int.TryParse`
Trusted / guaranteed	`int.Parse`
Need `null` to mean `0`	`Convert.ToInt32`

Thanks for reading! If you found this post helpful, you might also enjoy converting a C# object to almost any format and my other posts on C# and .NET development.

Rails to ASP.NET Core: A Developer's Map

Mon, 05 Oct 2026 00:00:00 GMT

While it feels like many software developers have picked their bread and butter frameworks these days, there are still opportunities to explore other technologies and ecosystems. What makes adoption difficult is fighting our muscle memory and looking for familiar signposts. Our experience can be both our biggest advantage and disadvantage when moving between stacks.

This guide maps Rails conventions, Action Pack, Hotwire, Active Record, Sidekiq, and the Rails CLI to their closest ASP.NET Core and .NET counterparts. It began as an answer to a Reddit user’s question and is a conceptual map rather than a migration guide.

It is for full-stack Rails developers and API-focused Rails developers who want to expand their technical toolbox, evaluate .NET for a future project, or simply see how the other side lives.

How Do Rails and ASP.NET Core Handle Convention Over Configuration?

Convention over configuration reduces ceremony by making predictable choices on a team’s behalf. Rails is strongly opinionated: its default directory layout, naming rules, ORM conventions, generators, and integrated components guide most applications toward a familiar shape. That consistency makes it easy to move between Rails projects and quickly recognize where code belongs.

ASP.NET Core also has opinions, but they are more loosely held. Think of it as “opinions lite.” Its templates provide conventional layouts, dependency injection, configuration, logging, routing, and framework-specific patterns such as MVC controllers or Razor Pages. Unlike Rails, however, ASP.NET Core expects you to compose the pieces you need and readily permits multiple valid approaches to the same problem.

For a Rails developer, this is the important adjustment: ASP.NET Core MVC will feel familiar because it has controllers, views, routing, conventions, and validation. But the framework will ask you to make more decisions about project structure, data access, background processing, and UI architecture. That flexibility is useful when a project needs it, but it also means teams should agree on their conventions early.

How Does Ruby’s Dynamic Typing Compare to C#?

The biggest difference Ruby developers will notice in .NET is C#’s static type system. Neither approach is inherently better, but they move feedback to different points in the development cycle. Ruby gives you flexibility at runtime and leans heavily on tests to verify an object’s shape and behavior. C# asks you to declare those shapes up front and lets the compiler catch many mismatches before the application runs.

In daily work, that means renaming a property or changing a method signature in C# usually produces a list of compiler errors that points to every affected caller. You will also encounter nullable reference types, which let the compiler warn when code might use a missing value. Tests are still essential in .NET, but the compiler becomes an additional quality gate alongside them.

Rails developers will most often model application concepts with classes or records, then use interfaces when they need to describe a contract independent of a particular implementation. At the edges of an application, it is common to use explicit request and response models instead of passing database entities directly between controllers, views, APIs, and persistence. This can initially feel more verbose than Ruby, but it makes those boundaries and their expected data clearer to both the compiler and the next developer reading the code.

What Is the ASP.NET Core Equivalent of Action Pack?

Rails’ core web framework system is called Action Pack. It provides the familiar request pipeline: routing accepts an incoming request, selects a controller action, binds input, and renders a response.

ASP.NET Core has multiple web frameworks built on its endpoint routing system. MVC, Razor Pages, Minimal APIs, and Blazor all use the same hosting, configuration, dependency injection, middleware, logging, and routing foundations. The programming model you select determines how you organize endpoints and render a response.

For a Rails developer looking for the closest mental model, start with ASP.NET Core MVC. The concepts will feel familiar:

Rails	ASP.NET Core MVC
`config/routes.rb`	Endpoint route configuration in `Program.cs` and route attributes
Controller action	Controller action method
Action Controller filters	Middleware, endpoint filters, and MVC filters
Strong parameters	Input models, model binding, and validation
Action View template	Razor view

The models are analogous, not identical. Rails supplies stronger defaults around its application structure, while ASP.NET Core gives teams more latitude to decide how routes, services, data access, and features are organized.

Other ASP.NET Core programming models are appropriate in specific situations:

Razor Pages is a good fit for page-centric, server-rendered applications, especially CRUD screens. A Razor Page keeps a page’s markup and its request-handling code together, but it does not replace your domain or persistence models.
Minimal APIs work well for small HTTP services, focused endpoint groups, and teams that prefer endpoint-first code without controllers.
Blazor is a component framework for interactive .NET user interfaces. It is a different model from Rails’ controller-and-template workflow and deserves consideration when your team wants to build UI components in C#.

Start with the ASP.NET Core fundamentals, then build the official MVC tutorial or review the Razor Pages introduction. When you want to study working applications instead of another tutorial, Awesome .NET provides a broad index of .NET projects. For focused ASP.NET Core examples, Practical ASP.NET Core has runnable samples covering MVC, Razor Pages, Minimal APIs, htmx, authentication, and hosted services.

What Is the .NET Equivalent of Action View and Hotwire?

The UI layer is where Rails developers are most likely to encounter overwhelming choice. You can continue building server-rendered HTML, use a small amount of JavaScript to update parts of a page, or adopt a fully interactive component model. ASP.NET Core supports each approach, but it does not prescribe a single default in the way Rails does. Again, “opinions lite” as opposed to Rails strong opinions.

Razor is ASP.NET Core’s server-side HTML templating syntax and is the closest counterpart to Action View. Razor views and Razor Pages render HTML on the server. For reusable pieces of UI, use partial views, View Components, or tag helpers, depending on whether the UI needs only markup, needs to run server-side code, or benefits from HTML-oriented conventions.

If your Rails team likes Hotwire and Turbo, htmx is worth evaluating. Both approaches keep the server responsible for rendering HTML and let the browser replace targeted portions of a page instead of requiring a JSON API and a client-side framework. They are similar, not interchangeable: Turbo provides its own conventions around navigation, frames, and streams, while htmx uses declarative HTML attributes to issue requests and swap returned HTML into a target.

I maintain HTMX.NET, an optional ASP.NET Core enhancement library that helps integrate htmx with server-side code. Start with the official htmx documentation, then see this site’s introductions to htmx with ASP.NET Core, htmx swapping techniques, and anti-forgery tokens in htmx requests.

If your team prefers a React-like component model but wants to build components in C#, ASP.NET Core ships with Blazor. Blazor supports static server-side rendering plus interactive server, WebAssembly, and auto render modes. It is a different architectural choice from controller-and-template applications, so choose it when stateful, reusable, interactive components are a primary part of the user experience rather than as a direct substitute for Turbo.

You can also combine these approaches where it makes sense. For example, Blazor server-rendered components can work with htmx when you want reusable components without committing every part of the UI to a single client interaction model.

What Is the ASP.NET Core Equivalent of Rails API Mode?

If you’re a Rails developer primarily building an API for a frontend, mobile client, or another service, ASP.NET Core offers two primary approaches: API controllers and Minimal APIs. Both use the same routing, model binding, validation, authentication, authorization, dependency injection, and JSON serialization features. The difference is primarily in how your application organizes endpoints.

Choose API controllers for larger APIs that benefit from established conventions, shared filters, and a familiar class-and-action structure. Choose Minimal APIs for smaller services, focused endpoint groups, or teams that prefer defining an endpoint close to the code that handles it. Neither approach is more capable by default; the right choice is the one your team can keep consistent as the application grows.

Here is a practical translation of common Rails API concepts:

Rails API mode	ASP.NET Core
`config/routes.rb`	Endpoint route configuration in `Program.cs`, route groups, or controller route attributes
Controller action	Controller action or Minimal API route handler
Strong parameters	Request models, model binding, and validation
`render json:`	Returning a result or typed response serialized as JSON
`before_action`	Middleware, endpoint filters, MVC filters, and authorization policies
Jbuilder or serializers	Response DTOs, anonymous projections, or dedicated serialization types

Avoid returning Entity Framework Core entities directly from API endpoints. Instead, accept request DTOs and return response DTOs or projections that describe the public API contract. This prevents database implementation details, navigation properties, and accidental fields from leaking into responses while giving you room to change persistence without breaking clients. For deeper Minimal API patterns, see endpoint filters in ASP.NET Core and generating HTTP endpoints with Minimal APIs.

The official ASP.NET Core Web API documentation and Minimal APIs quick reference cover the framework features in detail.

What Is the .NET Equivalent of Active Record?

Rails developers typically use Active Record, an object-relational mapper built around conventions and active record objects. Entity Framework Core serves a similar purpose in .NET: it maps .NET objects to relational data, tracks changes, manages relationships, and supports schema migrations. The two tools solve many of the same problems, but they organize persistence differently.

The important distinction is that EF Core generally follows a Data Mapper style. Instead of putting persistence methods directly on a Post object, you use a DbContext to query and save entity instances. The DbContext represents a session with the database, tracks changes to loaded entities, and coordinates SaveChanges calls. This can feel less magical than Active Record, but it makes the data-access boundary more explicit.

Rails	Entity Framework Core
Active Record model	Entity class plus `DbContext`
`rails db:migrate`	`dotnet ef database update`
Migration files	EF Core migrations
Associations	Navigation properties and relationship configuration
Scopes	LINQ queries, extension methods, or query objects
Callbacks	Explicit application/domain logic or EF Core interceptors when appropriate

LINQ is EF Core’s query language. Many LINQ expressions are translated to SQL and executed by the database, but not every .NET method can be translated. Learn to inspect generated SQL and project only the fields an endpoint needs. When loading relationships, be deliberate about eager loading with Include, projections, or separate queries so you do not introduce an N+1 query problem. For hands-on follow-up, see using Entity Framework Core in ASP.NET Core and adding EF Core migrations to .NET Aspire solutions.

The EF Core documentation and EF Core migrations documentation cover the underlying concepts and commands.

How Do Rails Generators and Bundler Map to .NET?

Rails has a famously cohesive command-line experience, particularly around generators and project conventions. The .NET CLI is strong at creating projects, building, testing, running, publishing, managing packages, and invoking tools, but it is less generator-centric. You will find scaffolding templates and third-party generators, but they are not as central to the day-to-day .NET workflow as rails generate is to Rails.

An uncomfortable truth for command-line-first Rails developers is that .NET developers often prefer IDE or editor tooling for discovery, refactoring, debugging, scaffolding, and project management. JetBrains Rider, Visual Studio, and Visual Studio Code with the C# Dev Kit are common parts of the workflow. You can build and ship entirely from the terminal, but the broader ecosystem often assumes you have capable editor tooling available, which may feel like a cultural adjustment when moving between the two communities.

Here are the most useful command-line translations:

Rails	.NET
`rails new`	`dotnet new`
`bundle add`	`dotnet add package`
`bundle exec`	`dotnet tool run` or a direct `dotnet` command
`rails db:migrate`	`dotnet ef database update`
`rails test`	`dotnet test`
`rails server`	`dotnet run` or `dotnet watch`

NuGet is the closest equivalent to RubyGems, but a .csproj file generally holds package references rather than a separate Gemfile. Larger .NET solutions may also use Central Package Management to declare package versions in one Directory.Packages.props file.

Learn more in the official documentation for the .NET CLI and NuGet package management.

What Is the .NET Equivalent of ActiveJob and Sidekiq?

Background work is essential whenever an operation should outlive an HTTP request: sending email, processing uploaded files, generating reports, or synchronizing with another service. Rails developers commonly use ActiveJob as an abstraction and Sidekiq as a durable job processor. .NET has no single built-in ActiveJob equivalent, so applications usually target a chosen job library directly or define an application-specific abstraction around it.

The right .NET choice depends on whether the work must survive process restarts and whether you are primarily queueing work or scheduling it:

BackgroundService is built into ASP.NET Core and works well for continuous, in-process work such as polling a source, consuming an already-durable queue, or running a periodic task. By itself, it does not provide Sidekiq-like durable job storage, retries, or a dashboard. Treat it as part of your application process, not as a reliable replacement for a job queue.
Hangfire is the closest of these options to a Sidekiq-style job system. It persists background jobs in supported storage, supports retries and recurring jobs, and includes a dashboard. It is a strong choice when application code needs to enqueue durable work and monitor it.
Quartz.NET is primarily a scheduler. It is well suited for recurring and calendar-based work, and can persist schedules and jobs when configured with durable storage. Use it when scheduling is the central problem rather than general-purpose background job processing.

For work that must not be lost, use durable storage or a message broker and design for retries, idempotency, observability, and failure handling. An in-memory queue or a fire-and-forget task can disappear when an application restarts or scales out.

How Does the .NET Open-Source Ecosystem Compare to RubyGems?

Rails developers are accustomed to a deep ecosystem of gems, where reaching for a well-known community package is a normal part of building an application. The .NET ecosystem has a different center of gravity. ASP.NET Core and .NET include many capabilities that Rails developers might otherwise expect to add through gems: dependency injection, configuration, logging, authentication and authorization primitives, background hosted services, caching, HTTP clients, health checks, and structured JSON serialization.

This means you may need fewer third-party packages to get an application running, but it also changes where you look when you need a capability. Start with the .NET and ASP.NET Core documentation to understand what is already available, then search NuGet for a package when the platform does not meet your requirements.

The open-source ecosystem is active, but it is less centralized around a small set of universally adopted gems. You will find excellent projects, commercial products, Microsoft-supported packages, and multiple competing options for common problems. Evaluate them the same way you would a Ruby gem: check maintenance activity, issue response, release cadence, documentation, security posture, licensing, and whether the project fits your deployment model.

The practical adjustment for Rails developers is not that .NET lacks open source. It is that the platform itself covers more of the common web-application baseline, while third-party choices are often more fragmented and problem-specific.

Rails to .NET Cheat Sheet

Rails	Closest .NET counterpart	Notes
Action Pack	ASP.NET Core MVC or Razor Pages	MVC is the closest controller-and-view analogue.
Action View	Razor	Partial views, View Components, and tag helpers compose reusable UI.
Hotwire/Turbo	htmx	Both favor server-rendered HTML; their navigation and update models differ.
Active Record	Entity Framework Core	EF Core uses `DbContext` and LINQ rather than persistence methods on each model.
ActiveJob/Sidekiq	Hangfire, Quartz.NET, or `BackgroundService`	Choose durable storage for jobs that must survive restarts.
Rails CLI/Bundler	.NET CLI/NuGet	.NET relies more heavily on editor and IDE tooling.

Conclusion

Rails and .NET share more ideas than their languages and communities suggest at a cursory glance. Rails offers a strongly opinionated path from a new application to a working product. ASP.NET Core offers familiar web-development building blocks with more opportunities for a team to decide how those blocks fit together.

If you want to try the .NET ecosystem, start small: create an ASP.NET Core MVC or Razor Pages application, build one CRUD feature with EF Core migrations, and choose htmx or Blazor only when the user experience calls for it. That exercise will show you where the frameworks overlap, where their tradeoffs differ, and which conventions your team needs to establish.

This map is a starting point, not a migration checklist. It began with a question on r/dotnet asking for Rails equivalents, and I hope it gives Rails developers enough context to explore .NET with fewer surprises. Bring the Rails practices that serve your team well, learn the .NET platform conventions, and make intentional choices where ASP.NET Core leaves room for them.

Server-Sent Events in ASP.NET Core and .NET 10

Tue, 22 Apr 2025 00:00:00 GMT

Like many .NET developers, I’m starting to look at the features coming in .NET 10, C# 14, and specifically ASP.NET Core. To my surprise, ASP.NET Core Minimal APIs now support Server-Sent Events (SSE). For folks who don’t know what Server-Sent Events are, they are a unidirectional channel from the server to a client where a client can subscribe to events. SSE is handy for building live news feeds, stock ticker applications, or any system that has real-time information.

Inevitably, folks will ask, what’s the difference between SSE and SignalR? The difference is that SSE is lighter than WebSockets, and you can implement an SSE solution using the HTTP protocol. Whereas WebSockets, SignalR’s default operating mode, is a different protocol entirely. WebSockets are great, but the bidirectional communication between server and client adds additional costs that are typically unnecessary for the systems I mentioned previously.

In this post, I’ll show you how to implement a straightforward SSE example using ASP.NET Core Minimal APIs, a background service, and some basic JavaScript.

The Anatomy of a SSE Endpoint

Starting in .NET 10, you can now use the TypedResults class to return a ServerSentEventsResult, which takes an IAsyncEnumerable<> instance and an event type.

using System.ComponentModel;
using System.Runtime.CompilerServices;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<FoodService>();
builder.Services.AddHostedService<FoodServiceWorker>();

var app = builder.Build();
app.UseDefaultFiles().UseStaticFiles();

app.MapGet("/orders", (FoodService foods, CancellationToken token) =>
    TypedResults.ServerSentEvents(
        foods.GetCurrent(token),
        eventType: "order")
);

app.Run();

In this example code, the foods.GetCurrent method call returns an IAsyncEnumerable of food-based emojis. The cancellation token allows the client to unsubscribe, stopping the enumeration and server-side computation.

That’s all you need; let’s see our IAsyncEnumerable implementation.

Implementing an IAsyncEnumerable Food Service

While implementing an IAsyncEnumerable is straightforward, I wanted to write an implementation that synced all subscribers to a single source of truth. I accomplish this task in two classes: FoodService and FoodServiceWorker.

The FoodService implements an INotifyPropertyChanged and allows all subscribers to sync to get a single food item’s Current value.

public class FoodService : INotifyPropertyChanged
{
    public FoodService()
    {
        Current = Foods[Random.Shared.Next(Foods.Length)];
    }

    public event PropertyChangedEventHandler? PropertyChanged;
    private static readonly string[] Foods = ["🍔", "🍟", "🥤", "🍤", "🍕", "🌮", "🥙"];

    private string Current
    {
        get;
        set
        {
            field = value;
            OnPropertyChanged();
        }
    }

    public async IAsyncEnumerable<string> GetCurrent(
        [EnumeratorCancellation] CancellationToken ct)
    {
        while (ct is not { IsCancellationRequested: true })
        {
            yield return Current;
            var tcs = new TaskCompletionSource();
            PropertyChangedEventHandler handler = (_, _) => tcs.SetResult();
            PropertyChanged += handler;
            try
            {
                await tcs.Task.WaitAsync(ct);
            }
            finally
            {
                PropertyChanged -= handler;
            }
        }
    }

    public void Set()
    {
        Current = Foods[Random.Shared.Next(Foods.Length)];
    }

    protected void OnPropertyChanged([CallerMemberName] string? propertyName = null)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

Now, I need a background service that updates the food choices at a timed interval.

public class FoodServiceWorker(FoodService foodService)
    : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            foodService.Set();
            await Task.Delay(1000, stoppingToken);
        }
    }
}

Now, let’s write the HTML subscribing to the SSE endpoint defined in my simple sample.

Subscribing to SSE using JavaScript

In a new index.html file in wwwroot, I’ll need to create a new EventSource object, listen for my order events to come through, and handle them appropriately.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<style>
    ul {
        display: flex;
        flex-direction: row;
        list-style: none;
        flex-wrap: wrap;
        width: 90%;
        gap: 1rem;
        padding: 0;
    }

    li {
        font-size: 2rem;
    }
</style>
<body>

<h1>Khalid's Fast-Food Fair</h1>
<ul id="orders">
</ul>

<script>
    const eventSource = new EventSource('/orders');
    const angelsList = document.getElementById('orders');

    eventSource.addEventListener('order', event => {
        const li = document.createElement('li');
        li.textContent = event.data;
        angelsList.appendChild(li);
    });

    eventSource.onerror = error => {
        console.error('EventSource failed:', error);
        eventSource.close();
    };
</script>

</body>
</html>

It’s that simple. When the browser loads the page, we’ll immediately subscribe to the SSE endpoint and start receiving food emojis. If you open two pages, you’ll see the emojis synced between the pages.

Try this quick sample, and let me know if you have any questions. Cheers.

Generic C# Methods with Enum Constraints for .NET

Tue, 04 Mar 2025 00:00:00 GMT

Every couple of years, I tend to write the same variation of an enum helper that reads metadata from an enumeration using reflection. Almost any .NET developer with a few years of experience has done the same. The implementation uses Generics to work for any enum defined in my solution, as there is typically more than one described in a typical .NET solution. Historically, generics and enums didn’t work well because of the limitations of generics when dealing with this particular type, but to my surprise, they do now!

In this post, we’ll explore how to write the helper method I’m describing while ensuring the generic constraints stop us from passing in arguments other than enums.

Straight To The Implementation

Since this post will be short, I’ll start with a sample you can play with.

using System.ComponentModel;
using System.Reflection;

// get all descriptions
{
    Console.WriteLine("Groceries:\n");
    var descriptions = Enums.GetDescriptions<Groceries>();
    foreach (var (value, description) in descriptions)
    {
        Console.WriteLine($"{value} - {description}");
    }
    Console.WriteLine();
}

// Get a description for a single value
{
    var (value, description) = Enums.GetDescription(Groceries.Fruit);
    Console.WriteLine($"Single value:\n{value} - {description}");
}

public enum Groceries
{
    [Description("Apples, Oranges, Bananas")]
    Fruit,
    [Description("Spinach, Kale, Broccoli, Cabbage")]
    Vegetables,
    [Description("Cheese, Milk, Yogurt")]
    Dairy,
    [Description("Chicken, Beef, Pork, Lamb, Turkey")]
    Meat,
    [Description("Anything not listed above")]
    Other
}

public static class Enums
{
    public static IEnumerable<(TEnum Value, string Description)> GetDescriptions<TEnum>()
        where TEnum : struct, Enum
    {
        var values = Enum.GetValues<TEnum>();
        foreach (var value in values)
        {
            yield return GetDescription(value);
        }
    }

    public static (TEnum Value, string Description) GetDescription<TEnum>(TEnum value)
        where TEnum : struct, Enum
    {
        var type = typeof(TEnum);
        var name = value.ToString();
        var info = type.GetMember(name)[0];
        var description = info.GetCustomAttribute<DescriptionAttribute>() is { } attr
            ? attr.Description
            : name;

        return (value, description);
    }
}

The helper code is here for people who don’t want to visualize the previous sample.

public static class Enums
{
    public static IEnumerable<(TEnum Value, string Description)> GetDescriptions<TEnum>()
        where TEnum : struct, Enum
    {
        var values = Enum.GetValues<TEnum>();
        foreach (var value in values)
        {
            yield return GetDescription(value);
        }
    }

    public static (TEnum Value, string Description) GetDescription<TEnum>(TEnum value)
        where TEnum : struct, Enum
    {
        var type = typeof(TEnum);
        var name = value.ToString();
        var info = type.GetMember(name)[0];
        var description = info.GetCustomAttribute<DescriptionAttribute>() is { } attr
            ? attr.Description
            : name;

        return (value, description);
    }
}

The essential part of our generic methods is our method declarations’ where clause.

where TEnum: struct, Enum

This line adds two crucial elements to our generic method.

It makes sure that TEnum is an Enum type. The struct ensures that TEnum is non-nullable.

The non-nullability of an Enum is essential since we are using the Enum.GetValues<TEnum> method to get known values. You could remove this constraint, but your implementation would require more boxing and defensive programming in the form of null checks. It’s more straightforward to enforce the struct requirement.

Conclusion

There you go, a constrained generic method implementation that can get metadata from an Enum value. If you’re still wondering, “where would I use this?” I find these methods helpful in web applications for creating a SelectListItem, but I stuck with Tuples for this post. What a time to be alive. Cheers!

Strongly-Typed Markdown for ASP.NET Core Content Apps

Tue, 25 Feb 2025 00:00:00 GMT

Every development career has milestone moments. One we all likely share is building a custom content management system, or CMS, as developers like to refer to it. A common approach to melding metadata and content is utilizing the old reliable Markdown format, which fuses YAML frontmatter with a simple content format. While YAML is flexible, it can be less than ideal when wanting to use that embedded data in your ASP.NET Core applications.

In this post, I’ll show you a quick experiment around processing Markdown files and their YAML into a strongly-type C# object. The example allows you to easily modify content while still having access to instances of data that you can strongly type.

The Magnificent Markdown

Markdown is a very flexible format whose strength comes from its simplicity. Let’s examine a document that defines a person’s profile.

---
name: "Khalid Abuhakmeh"
profession: "Software Developer"
hobbies: ["video games", "movies", "boxing"]
---

## Summary

I am writing a little about myself here and this should appear
in the page. Cool! Check me out at my [personal blog](https://khalidabuhakmeh.com).

The top of the document defines a data model with properties for Name, Profession, and Hobbies. The C# data model for this YAML would consist of three properties.

public class Asset
{
    public string Name { get; set; } = "";
    public string Profession { get; set; } = "";
    public string[] Hobbies { get; set; } = [];
}

Let’s build an object that will parse the Markdown file’s front matter while helping us render the content into HTML for use on a Razor page.

The MarkdownObject and Parsing Files

For my experiment, I created a MarkdownObject<T> class that takes a content string and parses the document into its parts. The T argument is up to the developer to determine.

To continue with the code, you must add the Markdig package and the YamlDotNet package.

<ItemGroup>
  <PackageReference Include="Markdig" Version="0.40.0" />
  <PackageReference Include="YamlDotNet" Version="16.3.0" />
</ItemGroup>

Let’s look at the implementation next.

using Markdig;
using Markdig.Extensions.Yaml;
using Markdig.Syntax;
using Microsoft.AspNetCore.Html;
using YamlDotNet.Serialization;
using Md = Markdig.Markdown;

namespace SuperContent.Models;

public class MarkdownObject<T>
{
    private static readonly MarkdownPipeline MarkdownPipeline
        = new MarkdownPipelineBuilder()
            .UseYamlFrontMatter()
            .UseAdvancedExtensions()
            .Build();
    private static readonly IDeserializer Deserializer
        = new DeserializerBuilder()
            .WithYamlFormatter(new YamlFormatter())
            .WithCaseInsensitivePropertyMatching()
            .Build();

    public MarkdownObject(string content)
    {
        var doc = Md.Parse(content, MarkdownPipeline);
        FrontMatter = default;

        if (doc.Descendants<YamlFrontMatterBlock>().FirstOrDefault() is { } fm)
        {
            var yaml = fm.Lines.ToSlice();
            FrontMatter = Deserializer.Deserialize<T>(yaml.Text);

            // we don't want front matter after it's processed
            doc.Remove(fm);
        }

        // turn it into HTML once
        Html = new HtmlString(doc.ToHtml());
    }

    public T? FrontMatter { get; private set; }

    public IHtmlContent Html { get; private set; }
}

In the case of this demo, we’ll create an instance of MarkdownObject<Asset>. Let’s see how to use this type in a Razor Page.

MarkdownObject in a Razor Page

In my demo, I have all my Markdown files in a Data directory. Each file in the data directory has a unique file name that we’ll use in our Razor Page as a slug. We’ll also use the Model to output the data and the processed HTML into a structured layout.

@page "/profile/{slug}"
@model SuperContent.Pages.Profile

<div class="row">
    <div class="col-12">
        <h1>@Model.Asset.FrontMatter?.Name</h1>
    </div>
</div>

<div class="row">
    <div class="col-3">
        <dl>
            <dt>Profession</dt>
            <dd>@Model.Asset.FrontMatter?.Profession</dd>
            <dt>Hobbies</dt>
            <dd>
                <ul>
                    @if (Model.Asset is { FrontMatter.Hobbies : { } hobbies })
                    {
                        @foreach (var hobby in hobbies)
                        {
                            <li>@hobby</li>
                        }
                    }
                </ul>
            </dd>
        </dl>
    </div>
    <div class="col-9">
        @Model.Asset.Html
    </div>
</div>

So, what does the page’s model look like?

using System.Text.RegularExpressions;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using SuperContent.Models;

namespace SuperContent.Pages;

public partial class Profile : PageModel
{
    [BindProperty(SupportsGet = true)]
    public string Slug { get; set; } = "";

    public MarkdownObject<Asset> Asset { get; set; }
        = null!;

    public IActionResult OnGet()
    {
        // read a file from the Data directory based on the slug
        // sanitize the slug first because people are mean
        var sanitizedSlug = SlugRegex.Replace(Slug, "");
        var path = Path.Combine("Data", $"{sanitizedSlug}.md");

        if (System.IO.File.Exists(path))
        {
            var content = System.IO.File.ReadAllText($"Data/{sanitizedSlug}.md");
            Asset = new(content);
            return Page();
        }

        return NotFound();
    }

    [GeneratedRegex("[^a-zA-Z0-9_-]")]
    private static partial Regex SlugRegex { get; }
}

public class Asset
{
    public string Name { get; set; } = "";
    public string Profession { get; set; } = "";
    public string[] Hobbies { get; set; } = [];
}

The OnGet method contains some protective code to prevent access to other files, but it’s ultimately pretty straightforward. When you go to /profile/Khalid, you’ll see a nicely formatted page that mixes data and content into predetermined HTML because we use the new MarkdownObject class. Sweet!

I’ve pushed the code to my GitHub repository so you can try this sample for yourself. Please give it a try and let me know what you think. As always, thanks for reading and sharing my posts. Cheers.

ConcurrentDictionary GetOrAdd and Closures in .NET

Tue, 18 Feb 2025 00:00:00 GMT

If ConcurrentDictionary.GetOrAdd is quietly allocating a closure every time you call it, your IDE is probably already nagging you about it. I was recently looking at the Duende Software codebase, and I kept seeing the same suggestion offered by the IDE tooling whenever I encountered a ConcurrentDictionary: “Closure can be eliminated: method has overload to avoid closure creation.”

While the suggestion appears in the tooling, there isn’t a quick fix action to apply the change. It left me scratching my head because there wasn’t an immediately obvious solution.

This post will define closures and explain their problems. We’ll also explain how to change your usage of ConcurrentDictionary to avoid closures altogether.

What Are Closures?

If you’ve ever worked with an Action, Func, delegate, or LINQ, then you’ve likely encountered a closure. A closure is a language mechanism that allows you to treat a function with free variables as if it were an object instance you may pass, invoke, or use in another context from when you first created it. Justin Etheredge has a great article explaining closures in-depth, but it’s when you use a lambda with a state outside the current scope of the lambda.

Let’s create a closure by capturing a variable in a straightforward example.

void SayHello(string name)
{
    var hello = () =>
    {
        // name is captured causing an allocation
        // and potential concurrency issues
        Console.WriteLine($"Hello {name}");
    };
    hello();
}

In the code above, the compiler needs to capture the name parameter to ensure all future calls to our hello lambda can execute. Capture can cause issues that may be difficult to predict until you execute your code.

Additional allocations are needed to capture a value and can have resource utilization implications.
A value captured from outside the closure scope may be alterable if it is a reference type. Unintended state change can lead to unpredictable behavior.
Long-lived references may lead to memory leaks in the long run.

To avoid capture, ensure all lambdas pass state required as arguments.

void SayHello(string name)
{
    var hello = (string n) =>
    {
        Console.WriteLine($"Hello {n}");
    };
    hello(name);
}

Now that we understand the basics, let’s examine the ConcurrentDictionary suggestion and see how we might fix it.

ConcurrentDictionary.GetOrAdd and Closure Creation

Let’s write a straightforward use of the GetOrAdd method on ConcurrentDictionary and see what the issue might be.

using System.Collections.Concurrent;

ConcurrentDictionary<string, Item> concurrentDictionary
    = new();

var key = "khalid";
var value = "awesome";

var result = concurrentDictionary.GetOrAdd(key, (k) => {
    Console.WriteLine($"Building {k}");
    return new Item(value, DateTime.Now);
});

Console.WriteLine(result);

Looking at the code, what variable do you think is creating the unnecessary closure?

If you guessed value, then you would be correct!

How do we fix the closure since our tooling now suggests that there is a solution to this issue?

Closure can be eliminated: method has overload
to avoid closure creation.

Well, let’s refactor and see how our code changes. I’ll add parameter prefixes to make clear what is happening.

using System.Collections.Concurrent;

ConcurrentDictionary<string, Item> concurrentDictionary = new();

var key = "khalid";
var value = "awesome";

var result = concurrentDictionary.GetOrAdd(
    key: key,
    valueFactory: (k, arg) =>
    {
        Console.WriteLine($"Building {k}");
        return new Item(arg, DateTime.Now);
    },
    factoryArgument: value);

Console.WriteLine(result);

record Item(string Value, DateTime Time);

So there is an overload on ConcurrentDictionary.GetOrAdd that takes three parameters:

The key to our value.
The lambda function responsible for creating our value when we do not find it.
A singular factory argument. You must wrap multiple arguments in a container class.

Using this overload, we now avoid closures, reduce allocations, and avoid potentially nasty concurrency or memory leak issues.

If you’re using ConcurrentDictionary check to see if you’re using GetOrAdd and see if you’re using the more efficient overload. Thanks for reading and sharing my posts with friends and colleagues. Cheers.

ASP.NET Core and Chunking HTTP Cookies

Tue, 11 Feb 2025 00:00:00 GMT

If you’ve spent time around web development or your grocery store’s baked goods aisle, you’ve probably dealt with cookies. Let’s discuss the web kind today. A cookie is a header key-value pair that is set on the server using the Set-Cookie key, and a value of <name>=<value>. Cookies persist on the client, where the client will send each cookie to the server on each subsequent request. It’s a simple way to persist state in the stateless web environment and avoid complex session management infrastructure. That said, cookies have limitations, mainly the 4kb size limit for each unique cookie. Size limits can be a serious problem for ASP.NET Core applications, which rely heavily on maintaining user session data in an encrypted and encoded cookie.

In this post, we’ll look at a sample I wrote that uses the same ICookieManager abstraction that ASP.NET Core uses to chunk large cookies successfully.

Why You Would and Wouldn’t Use Cookies

As the introduction mentions, cookies are a straightforward mechanism for maintaining the state between HTTP requests as users interact with your application. Cookies can significantly simplify your backend implementation, as you can expect requests to contain most of the information required to process user-intended actions. Cookies may include user information such as an ID, a name, an email address, and more. The request/response lifecycle of cookies also makes it easy to debug issues when they inevitably occur, as you can view an HTTP request and its headers in most logging mechanisms. These are only a few advantages, but let’s discuss some disadvantages.

While cookies are configurable, you can assume that, generally, the client will pass them along with each request to the server. The additional payload on each request can add unnecessary overhead to requests that don’t take advantage of the cookies. For example, any request for a file might still receive all set cookies even though the goal is to serve static content. That adds unnecessary ingress and resource utilization to your applications. Imagine a request with 10 cookies with a maxed-out cookie size on each. That’s an additional 40kb per request! And speaking of resource utilization, if cookies are chunked or encrypted, they first need to be reassembled and unencrypted before you can use them. Depending on your ASP.NET Core pipeline setup, this can unnecessarily add to your resource utilization, leading to increased memory and CPU usage.

My description does not say you should or shouldn’t ever use cookies, but you should be mindful that they have an associated cost. Now, let’s get to some code to see how to set a simple cookie and then use the ChunkingCookieManager to chunk larger cookies.

Setting Cookies in ASP.NET Core

You can see the entire sample at this GitHub repository

Like most web-related abstractions, you can access cookies from the current HttpContext. Using the current request’s context, let’s set a cookie on an HTTP response.

ctx.Response.Cookies.Append("cookie_monster", "nom nom nom");

In our sample, we’ll be reading and rewriting a value with appended data.

app.MapGet("/nom-nom", async ctx =>
{
    ctx.Response.Cookies.Append("cookie_monster",
        ctx.Request.Cookies.TryGetValue("cookie_monster", out var cookie)
            ? $"{cookie}, {RandomString()}"
            : $"{RandomString()}");
    // more code
}

That was easy! But there’s an issue: our cookie will continue expanding until it reaches our 4kb limit. Oh no! Admittedly, this is an example designed to fail quickly, but it’s easy to find yourself in a situation where cookies slowly creep up to the size limit. Let’s fix this code.

Install the Microsoft.AspNetCore.Authentication.Cookies NuGet package into your existing project to start using cookie chunking. In most cases, you’ll likely already have this dependency due to a transitive inclusion, but it never hurts to include it explicitly.

Next, we’ll need to register the ChunkingCookieManager in our services collection as an implementation of ICookieManager.

builder.Services.AddScoped<ICookieManager>(svc => new ChunkingCookieManager
{
    // characters, not bytes... 🤔
    ChunkSize = 1000, ThrowForPartialCookies = true
});

In my case, I reduced the chunk size for a few reasons.

See the chunking behavior sooner than later. The ChunkSize is based on characters in .NET and not kilobytes, so you’ll need to account for that based on the data you’ll be storing. 1000 is a nice round number, but the default is 4050.

Let’s look at the implementation in another minimal API endpoint.

{
app.MapGet("/chunks", async (HttpContext ctx, ICookieManager cookieManager) =>
{
    var value = cookieManager.GetRequestCookie(ctx, "chunky_monster") is { } cookie
        ? $"{cookie}, {RandomString()}"
        : $"{RandomString()}";

    cookieManager.AppendResponseCookie(ctx, "chunky_monster", value, new CookieOptions());

    // more code...
});

There are a few essential elements to getting cookie chunking working:

You must use the ICookieManager implementation for all interactions of your logical cookie since it will take care of the chunks. Interacting with the cookies directly through the HttpContext will cause you issues. The ICookieManager API requires access to an HttpContext instance. There is no assumption that a cookie manager will have an HTTP context dependency injected. You could easily create an implementation that wraps this into a new API. The CookieOptions argument is required but can be left empty. Options allow you to set cookie options on the resulting cookie chunks, such as Domain, Expires, Secure, and more.

As the concrete type name suggests, we will be chunking cookies, meaning that if a cookie’s contents exceed our configured limits, we’ll produce multiple header values.

You’ll usually see the following behavior in your browser’s dev tools.

Name	Value
chunky_monster	chunks-2
chunky_monsterC1	value chunk up to `ChunkSize`
chunky_monsterC2	rest of value
chunky_monsterCN	more to come if necessary

There you go, you’ve successfully chunked your cookies using the mechanisms provided by ASP.NET Core.

Conclusion

Cookies are a bedrock of web development, but you need to be mindful of their benefits and drawbacks. If you do find yourself exceeding the size limits of cookies, I’d recommend first understanding why it has occurred and if you have room to optimize your data. In a pinch, adopting chunking can help you get over the sizing issue, but can have the drawbacks mentioned in one of the previous sections. If you think you have a better strategy, you can implement the ICookieManager yourself and take a completely different approach. If you do, drop me a message and send me a link to your implementation.

To try this sample out for yourself, head to my GitHub repository. As always, thanks for reading and sharing my posts.

Vogen and Value Objects with C# and .NET

Tue, 04 Feb 2025 00:00:00 GMT

When it comes to programming, correctness is the name of the game. Every developer aims to understand, model, and limit potential outliers when executing code because those unknown variables can lead to exceptions and critical failures. There are many techniques developers use, but I recently discovered a new library (at least to me) in the .NET community that aims to help developers constrain potential inputs using value objects.

In this post, we’ll write a quick sample using Vogen to demonstrate how value objects can make our code clearer and less error-prone.

Vogen is a C# source generator that creates strongly-typed, validated value objects from primitive types, so you get compile-time safety without hand-writing boilerplate wrapper classes.

What is a Value Object?

A value object represents a logical concept but is a .NET primitive value such as int, bool, string, and more. A straightforward example might be a birth date. Most developers would define a birth date using the DateTime type, hoping that the variable name clarifies the value’s intention.

DateTime birthDate = new DateTime(1990, 1, 1);

The drawback to this code is nothing stops a developer from unintentionally using the birthDate variable incorrectly.

DateTime birthDate = new DateTime(1990, 1, 1);
SetMovieReleaseDate(birthDate);
void SetMovieReleaseDate(DateTime date) { }

While the code technically works, it may not be what the developers intended logically. The birth date may or may not be the release date of a movie, and it’s difficult to tell if this code is “correct.” Let’s fix it using value objects.

var birthDate = new BirthDateTime(new (1990, 1, 1));
var movieReleaseDate = new MovieReleaseDateTime(birthDate.Value);
SetMovieReleaseDate(movieReleaseDate);

void SetMovieReleaseDate(MovieReleaseDateTime date) { }
// value objects
public record MovieReleaseDateTime(DateTime Value);
public record BirthDateTime(DateTime Value);

Looking at this code, you can see that the developer intended to set a movie release date to the same value as the birth date. The goal is to minimize the chance of autocompleting your way into logical bugs that may be difficult to track down.

Yes, this can seem overly ceremonious, so consider the benefits and drawbacks before deciding if you want to adopt it.

Now, let’s see what Vogen is about.

What is Vogen?

Vogen is a NuGet library that utilizes source generators to generate value objects, taking much of the ceremony out of model creation. The library creates factory methods, comparisons, validation, and serializers on partial struct and class implementations.

Let’s start by adding Vogen to a .NET console application.

<PackageReference Include="Vogen" Version="7.0.0-beta.1" />

In my example, I’ll create a PacMan class that requires a FavoriteGhost property to have a valid value of Ghost.

public class PacMan
{
    public Ghost FavoriteGhost { get; set; }

    public override string ToString()
    {
        return $"Pac Man's favorite ghost is {FavoriteGhost}.";
    }
}

Our value object will be Ghost; everyone knows that the ghosts that haunt Pac-Man include Blinky, Pinky, Inky, and Clyde. Let’s start with the unconstrained approach using Vogen.

[ValueObject<string>]
[Instance("Blinky", "Blinky")]
[Instance("Pinky", "Pinky")]
[Instance("Inky", "Inky")]
[Instance("Clyde", "Clyde")]
public partial struct Ghost;

After the source generators have run, you’ll now have public static readonly instances of each ghost on the Ghost struct, allowing our code to run and set the FavoriteGhost property on our pacMan instance.

You can create any Ghost you like using the From method on the struct.

var aNewGhost = Ghost.From("Khalid");

If your value objects are unconstrained, this might be a good time to stop, but we want to limit our Ghost values. Let’s rework our Ghost struct.

[ValueObject<string>]
public partial struct Ghost
{
    public static readonly Ghost Blinky = new("Blinky");
    public static readonly Ghost Pinky = new("Pinky");
    public static readonly Ghost Inky = new("Inky");
    public static readonly Ghost Clyde = new("Clyde");

    public static IReadOnlyCollection<Ghost> All { get; }
        = new[] { Blinky, Pinky, Inky, Clyde }.AsReadOnly();

    private static Validation Validate(string input) =>
        All.Any(g => g.Equals(input))
            ? Validation.Ok
            : Validation.Invalid($"Ghost must be {string.Join(", ", All)}");
}

With some extra code, we can now validate that all values used to create a Ghost fit within a defined set of values.

// will throw an exception
var aNewGhost = Ghost.From("Khalid");
// will pass
var aKnownGhost = Ghost.From("Blinky");

Let’s see the use of Vogen in a complete C# sample.

using Vogen;

var pacMan = new PacMan
{
    FavoriteGhost = Ghost.Blinky
};

foreach (var ghost in Ghost.All)
{
    Console.WriteLine(ghost);
}

Console.WriteLine(pacMan);

[ValueObject<string>]
public partial struct Ghost
{
    public static readonly Ghost Blinky = new("Blinky");
    public static readonly Ghost Pinky = new("Pinky");
    public static readonly Ghost Inky = new("Inky");
    public static readonly Ghost Clyde = new("Clyde");

    public static IReadOnlyCollection<Ghost> All { get; }
        = new[] { Blinky, Pinky, Inky, Clyde }.AsReadOnly();

    private static Validation Validate(string input) =>
        All.Any(g => g.Equals(input))
            ? Validation.Ok
            : Validation.Invalid($"Ghost must be {string.Join(", ", All)}");
}

public class PacMan
{
    public Ghost FavoriteGhost { get; set; }

    public override string ToString()
    {
        return $"Pac Man's favorite ghost is {FavoriteGhost}.";
    }
}

Conclusion

Using value objects is an efficient way to constrain inputs and outputs logically. It helps you reflect logical constraints in the codebase and offers readability levels that could be lost using primitive types. With the addition of Vogen, you can remove boilerplate code and get straight to using value objects, with the benefits of quickly accessing the underlying primitive value through explicit and implicit means.

I think the next step for folks is likely to take an existing part of a codebase and see if converting it to use value objects improves readability and correctness.

I hope you enjoyed this post. As always, thanks for reading and sharing my posts.

Initialize ASP.NET Core TagHelpers with Shared Data

Tue, 14 Jan 2025 00:00:00 GMT

ASP.NET Core has a superpower that few other frameworks have, largely thanks to the Razor engine. Razor syntax is a mix of HTML and C#, and most Razor syntax implementations will skew heavily towards HTML over C#. However, C# syntax offers the most value in control flow mechanics using if, for, and switch statements. Razor’s power is that even HTML syntax is processed by C# and converted into compiled artifacts. This gives Razor a unique opportunity to do some amazing tricks.

In this post, we’ll see how to use the TagHelpers infrastructure to initialize all tag helper usage across your application and inject necessary shared data.

The TagHelper In Question

Let’s start by writing a simple tag helper that will replace the contents of a span tag when a text attribute is set.

using Microsoft.AspNetCore.Mvc.Razor;
using Microsoft.AspNetCore.Mvc.Rendering;
using Microsoft.AspNetCore.Razor.TagHelpers;

namespace WebApplication2.Models;

[HtmlTargetElement("span")]
public class MyTagHelper: TagHelper
{
    [HtmlAttributeName("text")]
    public string Text { get; set; } = "";

    [HtmlAttributeNotBound]
    public string Version { get; set; } = "";

    public override Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
    {
        output.Content.SetHtmlContent(Text);
        output.Attributes.Add("data-version", Version);
        return Task.CompletedTask;
    }
}

Usage of this tag helper is straightforward. In a Razor view, add the following tag.

<span class="fs-1 d-block" text="Hello, World!">...</span>
<span class="fs-1 d-block"></span>

As you may have noticed in the MyTagHelper implementation, there is another property of Version, which I decorated with the HtmlAttributeNotBound attribute. This value will be initialized with the tag helper initialization infrastructure.

TagHelper Initializers

We’ll implement the ITagHelperInitializer generic interface, which has an Initialize method that takes an instance of a tag helper and a ViewContext.

public class MyTagHelperInitializer(string defaultText, string version)
    : ITagHelperInitializer<MyTagHelper>
{
    public void Initialize(MyTagHelper helper, ViewContext context)
    {
        helper.Text = defaultText;
        helper.Version = version;
    }
}

Here, the data passed into our implementation can be used to hydrate all tag helpers of MyTagHelper. This is awesome for multiple reasons.

Expensive data can be calculated once and set globally, reducing resource utilization and speeding up page rendering.
We have access to the ViewContext, so we can modify and enhance all request/response lifecycle elements if necessary.
We have direct access to the tag helper, so the initialization code is as straightforward as possible.
The ViewContext gives us access to HttpContext, so we can also handle request-specific values from cookies, user information, etc.
Also, we can request other services that are already registered in our services collection.

How do we use this initializer? In Program, add the following line to register our initializer with our services collection.

builder.Services.AddSingleton<
    ITagHelperInitializer<MyTagHelper>
>(new MyTagHelperInitializer("Default Text", "1.0.0"));

In our case, we’re passing in the initial values. However, this type could also take in application configuration and read values from the IConfiguration implementation of an ASP.NET Core application. It’s important to note that this type is registered as a **Singleton **, which means any data passed to it in the constructor is the data for the rest of the application’s lifetime.

When we run our application, the tag helper will result in the following HTML.

<span class="fs-1 d-block" data-version="1.0.0">Hello, World!</span>
<span class="fs-1 d-block" data-version="1.0.0">Default Text</span>

Wow, so easy!

Conclusion

Part of building web experiences is handling requests efficiently and returning responses as quickly as possible. With tag helpers, you can help create more buffer space in your performance budgets by reducing and isolating the work needed to process data for HTML tags. Additionally, this technique of global initialization might also be helpful for test-driven UI tests, as attributes and their data can be added or removed depending on build flags. This approach is exciting, and I hope you try it in your applications.

As always, thanks for reading and sharing my blog posts. Cheers.

Writing a String Numeric Comparer with .NET 9

Tue, 07 Jan 2025 00:00:00 GMT

I recently saw that .NET 10 adds a numeric comparer, allowing you to sort string elements that may contain numeric values at the end of a string. Think movie sequels or number versions of an operating system. To my surprise, I could not believe it wasn’t already included in .NET, but then I sat down to try to write my own, and I now “get it”. The edge cases alone can drive you mad. Numeric ordering is subjective. Should the numbers come before Roman numerals? Should Roman numerals be parsed as numbers? What about decimals?

Anyway, I’ve added my numeric comparer implementation in this post, which uses some of the latest .NET features. Enjoy!

A List of Numbered Things

A number at the end of a text is typical for movies, books, video games, and products. These numbers denote a newer and better iteration of an item. For example, I have a combination of movies, Windows versions, and some decimal values.

var numberedThings = new List<string>
{
    "Godfather", "Godfather 3", "Scream",
    "Scream 2", "Scream 3", "Scream 1",
    "Windows 10", "Windows 7",
    "Windows 11", "Rocky 5",
    "Rocky 2", "Rocky 4", "Rocky 3", "Rock",
    "1.2", "1.3", "1.1", "Rocky", "Windows XP",
    "Godfather 2", "1.11", "1.10", "10.0", "1.0"
};

var numericOrderer = new NumericOrderer();
var sorted = numberedThings
    .OrderBy(x => x, numericOrderer)
    .ToList();

foreach (var item in sorted)
{
    Console.WriteLine(item);
}

The goal is to have the output result in alphanumeric ordering. For example, Godfather should come before Godfather 2. Also, when it comes to strings made of numbers, I want each part of a value to be treated as a whole number. For example, 1.1, 1.10, and 1.11 would follow that order.

We expect the following output from the previous code based on the input.

1.0
1.1
1.2
1.3
1.10
1.11
10.0
Godfather
Godfather 2
Godfather 3
Rock
Rocky
Rocky 2
Rocky 3
Rocky 4
Rocky 5
Scream
Scream 1
Scream 2
Scream 3
Windows 7
Windows 10
Windows 11
Windows XP

Let’s look at my implementation.

Writing a NumericOrderer with Spans

Here is my NumericOrderer based on the collection of data previously mentioned.

public sealed class NumericOrderer : IComparer<string>
{
    public int Compare(string? x, string? y)
    {
        if (x == null && y == null) return 0;
        if (x == null) return -1;
        if (y == null) return 1;

        var xSpan = x.AsSpan();
        var ySpan = y.AsSpan();

        var commonPrefixLength = xSpan.CommonPrefixLength(ySpan);

        while (commonPrefixLength > 0)
        {
            xSpan = xSpan[commonPrefixLength..];
            ySpan = ySpan[commonPrefixLength..];
            commonPrefixLength = xSpan.CommonPrefixLength(ySpan);
        }

        if (int.TryParse(xSpan, out var xNumber) &&
            int.TryParse(ySpan, out var yNumber))
        {
            return xNumber.CompareTo(yNumber);
        }

        return xSpan.CompareTo(ySpan, StringComparison.Ordinal);
    }
}

There are three configuration points you should consider in this implementation.

CommonPrefixLength can also take a Comparer argument, which might help ignore casing.
The CompareTo method currently takes a StringComparison.Ordinal value, which is case sensitive. I suggest changing this based on your needs.
The use of int.TryParse compares whole numbers. If your values contain decimals, then you may want to try double.TryParse.

Are there edge cases here? Very likely, but when ordering anything with “opinions”, you’ll likely have to tweak it to your liking. As I mentioned previously, Roman numerals are commonly used in place of Arabic numerals, so you may want to tweak this to support those, or you may want Windows XP to appear before Windows 11 in a list. You’re the sorting wizard in your magical journey.

Conclusion

This exercise made me realize that building a general-purpose numeric orderer is likely a herculean task. Instead, I’d probably implement a sorter based on your needs for that specific use case. Also, I learned that the Span APIs are very good and capable of breaking apart strings without creating new instances in memory. Finally, while this comparison works well for a single-point dataset, you’re likely dealing with more complex data models with other sortable fields that can be more accurately sorted (think numbers and dates). I’d likely lean more on predictably sortable values in a production setting than leaving it all to a general-purpose numeric comparer.

At the very least, I hope this implementation gives you a starting point for writing and tweaking your implementation. As always, thanks for reading, and cheers.

Great .NET Documentation with Astro, Starlight, and MarkdownSnippets

Tue, 31 Dec 2024 00:00:00 GMT

The hallmark of every great project is equally great documentation, but it can be increasingly difficult for developers to keep both in sync. Luckily, I’ve been experimenting again with a combination of Starlight and MarkdownSnippets to make maintaining code samples and documentation much more convenient.

In this post, we’ll see how to set up your repository so that MarkdownSnippets pulls samples from your codebase and updates your Starlight documentation.

Directory Structure and Tools

To get started, let’s set up our repository for success. Let’s begin with folders. We’ll want to create the following folders at the root of a newly created directory.

- docs
- src

The docs directory will hold our documentation powered by Starlight, and the src directory will have all our .NET code.

We’ll want to run the following dotnet commands within the same directory.

dotnet new tool-manifest

Next, let’s install the MarkdownSnippets tool.

dotnet tool install MarkdownSnippets.Tool

Finally, let’s create the MarkdownSnippets configuration file of mdsnippets.json, which will tune our snippet generation to work with Starlight.

{
  "$schema": "https://raw.githubusercontent.com/SimonCropp/MarkdownSnippets/refs/heads/main/schema.json",
  "Convention": "InPlaceOverwrite",
  "WriteHeader": false,
  "ReadOnly": false,
  "LinkFormat": "None",
  "OmitSnippetLinks": true
}

Following the steps correctly, you’ll have the following files and folders.

- docs
- src
- .config
- mdsnippets.json

Great! Let’s write some .NET code in our src directory now.

Our .NET Code Samples

Change to the src directory and create a new Console application. Any will do. What’s important is using the MarkdownSnippets convention to develop a block of code to be extracted. Here’s the one I’m using in Program.cs.

// begin-snippet: App:HelloWorld
Console.WriteLine("Hello, Again!");
// end-snippet

That’s it! Write and decorate as many code samples as you’ll use in the next section.

Our Starlight Documentation

Now, let’s move into the docs directory and run the following command. Note you’ll need both Node and Yarn installed.

yarn create astro --template starlight

From here, follow the Astro wizard to create a new documentation site. From the root, your directory structure should look similar to the following.

- docs
  - .astro
  - .vscode
  - .yarn
  - src
  - public
  - astro.config.mjs
  - package.json
  - ...
- src
  - App
    - bin
    - obj
    - App.csproj
    - Program.cs
- mdsnippets.json

Now, let’s update our package.json to scan our C# project, find snippets, and update our documentation.

{
  "type": "module",
  "version": "0.0.1",
  "scripts": {
    "mdsnippets": "cd .. && dotnet mdsnippets",
    "dev": "npm run mdsnippets && astro dev",
    "start": "npm run dev",
    "build": "npm run mdsnippets && astro build"
  },
  "dependencies": {
    "@astrojs/starlight": "^0.29.3",
    "astro": "^4.16.10",
    "sharp": "^0.32.5"
  }
}

Feel free to add or remove any additional scripts or dependencies for your particular use case. This is the bare minimum for this post.

Now, let’s write some documentation. Find the example.md file under docs/src/content/docs/guides/ and write the following markdown.

---
title: Hello, World!
description: Creating your first .NET Console Application
---

## Getting Started

Your first .NET application will be a console application, or what the cool folks like to call it, an app. Create a new project using the
`dotnet` CLI command `new`.

```bash title="Terminal"
dotnet new console -o HelloWorld && cd ./HelloWorld
```

Then, add the following code in the `Program.cs` file.

snippet: App:HelloWorld

Then run the app by using the following command.

```bash title="Terminal"
dotnet run
```

Congratulations!

Now, run the dev command from the root directory. MarkdownSnippets will transform the snippet: App:HelloWorld in your Markdown to the following.

---
title: Hello, World!
description: Creating your first .NET Console Application
---

## Getting Started

Your first .NET application will be a console application, or what the cool folks like to call it, an app. Create a new project using the
`dotnet` CLI command `new`.

```bash title="Terminal"
dotnet new console -o HelloWorld && cd ./HelloWorld
```

Then, add the following code in the `Program.cs` file.

<!-- snippet: App:HelloWorld -->

```cs
// Program.cs
Console.WriteLine("Hello, Again!");
```

<!-- endSnippet -->

Then run the app by using the following command.

```bash title="Terminal"
dotnet run
```

Congratulations!

You can change the code in Program.cs and rerun the command to see the documentation update.

Conclusion

If you’re working on code-heavy documentation where samples speak louder than words, then combining MarkdownSnippets with Starlight is a great pairing. You’ll want to develop a good naming convention to make finding and altering samples easier, after which you’ll be sure that any code samples are valid, compiled, and run. After all, as developers, we all want to get it right the first time.

As always, thanks for reading, and cheers.

Alpine.Js Polling ASP.NET Core APIs For Updates

Tue, 24 Dec 2024 00:00:00 GMT

Building dynamic JavaScript experiences has come a long in the 20 years since I first started software development, but updating the document object model (DOM) can still be a real pain in the butt. That’s why we’ve seen single-page application frameworks explode in use. While JavaScript provides a very capable API when interacting with the DOM, it can be verbose.

In this post, we’ll see how to use the Alpine.Js library’s declarative attribute approach to create a real-time updating UI with minimal JavaScript and no direct use of the DOM APIs.

The Strength of Alpine.js

Alpine.js is a lightweight JavaScript framework that allows you to compose behavior directly in your HTML markup. The library consists of 15 attributes, six properties, and two methods. While its surface API is small, what it offers is, as the site says, “powerful as hell.”

The strength of Alpine.js comes from its data model, which uses reactivity to detect changes to data and update the UI elements accordingly. Reactivity means you can update values naturally without keeping track of a dependency graph. Let’s take a look at a quick example.

<div x-data="{ count: 0 }">
    <button x-on:click="count++">Increment</button>

    <span x-text="count"></span>
</div>

In this example, the count value is reactive. When you click the button, the value increments. Since the count value is also used in the span element, it is updated at the time of the change. So easy!

Values can also be accessed from JavaScript. With a few modifications, we can use the data method to create a shared context for our counter.

<div x-data="count">
    <button x-on:click="increment()">Increment</button>
    <span x-text="value"></span>
</div>

<script>
    document.addEventListener('alpine:init', () => {

        Alpine.data('count', () => ({
            increment() {
                this.value++;
            },
            value: 0
        }));

    });
</script>

Note that we’ve encapsulated the counter logic in increment and changed the value field on each click. There’s no need to do any special syntax to access the value field. We can use it as we would a plain-old JavaScript object.

Now that we understand more about reactivity related to Alpine.js, let’s write a more complex sample that polls our ASP.NET Core application for updated data.

ASP.NET Core and Alpine.Js

Let’s start by creating an API endpoint that will return weather data. First, let’s look at our data model.

public class Weather
{
    public string Location { get; set; } = "";
    public string Description { get; set; } = "";
    public string Temperature { get; set; } = "";

    public static ReadOnlySpan<string> Descriptions =>
        new(["Sunny", "Cloudy", "Rainy", "Snowy"]);

    public static ReadOnlySpan<string> Locations =>
        new(["Mountain", "Valley", "Desert", "Forest"]);
}

Next, let’s add a new API endpoint to our application in Program.

using MountainWeather.Models;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/weather", () =>
{
    return Results.Json(
        Enumerable
            .Range(1, 10)
            .Select(i => new Weather
            {
                Location = $"{Random.Shared.GetItems(Weather.Locations, 1)[0]} #{i}",
                Description = $"{Random.Shared.GetItems(Weather.Descriptions, 1)[0]}",
                Temperature = $"{Random.Shared.Next(32, 100)}℉"
            })
            .ToList()
    );
});

app.UseDefaultFiles();
app.UseStaticFiles();

app.Run();

Next, let’s write our HTML and JavaScript. This is an index.html file placed in the wwwroot folder.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Weather</title>
    <link rel="stylesheet" href="https://unpkg.com/@picocss/pico@latest/css/pico.min.css">
    <script src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js" defer></script>
</head>
<body>
<main class="container-fluid">
    <table class="table table-striped" x-data="weather">
        <thead>
        <tr>
            <th>Location</th>
            <th>Description</th>
            <th>Temperature</th>
        </tr>
        </thead>
        <tbody>
        <tr x-show="locations.length === 0">
            <td colspan="3">
                0 Locations Found.
            </td>
        </tr>
        <template x-for="l in locations">
            <tr>
                <td x-text="l.location"></td>
                <td x-text="l.description"></td>
                <td x-text="l.temperature"></td>
            </tr>
        </template>
        </tbody>
        <tfoot>
        <tr>
            <td colspan="3" x-text="updated"></td>
        </tr>
        </tfoot>
    </table>
</main>
<script>
    async function getWeather() {
        let result = {};
        const response = await fetch('/weather');
        result.locations = await response.json();
        result.updated = new Date();
        return result;
    }

    document.addEventListener('alpine:init', () => {
        Alpine.data('weather', () => ({
            async init() {
                this.timer = setInterval(async () => {
                    const result = await getWeather();
                    this.locations = result.locations;
                    this.updated = result.updated;
                }, 3000);

                const result = await getWeather();
                this.locations = result.locations;
                this.updated = result.updated;
            },
            destroy: () => {
                clearInterval(this.timer);
            },
            locations: [],
            updated: "n/a",
            timer: null
        }));
    });
</script>
</body>
</html>

Let me explain what’s happening in this HTML, starting with our weather data model. We use the Alpine.data method to create a data context that our HTML can use with the x-data attribute. This data model has fields for locations, updated, and timer. The timer fetches data from our API every three seconds and changes the values. When the values change, the UI changes as well.

Let’s look at HTML binding because Alpine.js allows developers to employ a neat trick: the template HTML tag. By default, the template tag takes the user-defined contents and appends the hydrated version into the DOM as the following elements. In this sample, we get rows matching the values from the ASP.NET Core API. Now, running the sample, we get a table that updates its values every three seconds.

Note that JavaScript developers using intervals should call clearInterval if the DOM element can be removed before the user navigates away from the page. This ensures there will be no memory leaks. You can do this using the destroy method in your data definition.

Conclusion

There you go—a simple, updating UI with minimal JavaScript and an easy-to-understand and maintainable codebase. I like Alpine.js and what it offers. In most cases, a little bit of a user interface can go a long way. I hope you enjoyed this post, and thank you for reading. Cheers.

Building a Persistent Counter with Alpine.Js

Tue, 17 Dec 2024 00:00:00 GMT

If you read this blog, you likely know I predominantly work with .NET technologies and use web technologies such as HTML, CSS, and JavaScript. The web is an excellent space for new and exciting ways to solve age-old problems. I recently thought about the Blazor “Counter” example that ships with the Blazor Wasm template and how I’ve solved the same problem using Htmx. The issue with Htmx is that it still requires a backend to manage the state; in the case of a counter, this state is the current count. What if you wanted to build a self-contained client-side experience?

Alpine.js is a declarative library aimed at helping developers build client-side interactivity using HTML attributes on DOM elements. This post will show you how to create the same Blazor Counter example with very little JavaScript and network payloads.

Installing Alpine.js

Since Alpine.js is a JavaScript library, you only need to reference the necessary files in your HTML pages. In an ASP.NET Core application, that’s typically in your layout files.

Add the following script tag to the head portion of your page.

<!-- Alpine Core -->
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>

That’s it. You can also use NPM to bundle the dependency into an existing build process, but we’ll leave that out of this post for now.

Building an inline Counter with Alpine

Alpine uses attributes, and one of the most important attributes is the x-data attribute. The x-data attribute sets up the context for our current scope. In most cases, that scope is the DOM element you decorate with the attribute.

<main class="container" x-data="{ count : 0 }">
    <article class="card">
        <header>
            <h3>Counter Value</h3>
        </header>
        <section>
            <p x-text="count"></p>
        </section>
    </article>

    <button type="button" x-on:click="count++">
        Increment
    </button>
    <button type="button" x-on:click="count = 0">
        Reset
    </button>
</main>

Wow, that’s easy, right? So, how do we persist this information on reloads? Local storage of course!

Making the inline counter persistent

Alpine.js has a persistence plugin, which we’ll need to install. While you can write the local storage code, this plugin makes it much nicer to use stored values and update them as users make changes.

Modify the reference to Alpine.js on the page to include these two script tags.

<!-- Alpine Plugins -->
<script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/persist@3.x.x/dist/cdn.min.js"></script>
<!-- Alpine Core -->
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>

Cool, we’re ready to update the HTML to persist the value across page refreshes.

<main class="container" x-data="{ count : $persist(0) }">
    <article class="card">
        <header>
            <h3>Counter Value</h3>
        </header>
        <section>
            <p x-text="count"></p>
        </section>
    </article>

    <button type="button" x-on:click="count++">
        Increment
    </button>
    <button type="button" x-on:click="count = 0">
        Reset
    </button>
</main>

Refreshing the page now maintains the previous count. What if we want to use that value in other page parts? In other words, what if we want to keep a globally accessible value? That’s where Alpine.js stores come in.

Persisting state in an Alpine Store

Alpine.js allows you to create a global state using a store. Stores are created when Alpine.js initializes the page, allowing you to write more complex logic using JavaScript. Let’s modify our page to use a counter store with persistent values and methods.

<body>
    <main class="container" x-data>
        <article class="card">
            <header>
                <h3>Counter Value</h3>
            </header>
            <section>
                <p x-text="$store.counter.value"></p>
            </section>
        </article>

        <button type="button" x-on:click="$store.counter.increment()">
            Increment
        </button>
        <button type="button" x-on:click="$store.counter.reset()">
            Reset
        </button>
    </main>
    <script>
        document.addEventListener('alpine:initializing', () => {
            Alpine.store('counter', {
                value: Alpine.$persist(0),
                increment() {
                    this.value++
                },
                reset() {
                    this.value = 0;
                }
            })
        })
    </script>
</body>

It’s a bit more JavaScript code, but now other page elements can access the counter store, and the concepts of increment and reset are incapsulated into the store, allowing us to change behavior in a single location. That’s pretty cool!

Here’s the full HTML file so you can try it out for yourself.

<!DOCTYPE html>
<html lang="en" xmlns:x-on="http://www.w3.org/1999/xhtml">
<head>
    <meta charset="UTF-8">
    <title>PicoCSS Boilerplate</title>
    <link
            rel="stylesheet"
            href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css"
    />
    <link rel="stylesheet" href="/css/site.css"/>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="color-scheme" content="light dark"/>
    <title>Hello World!</title>
    <!-- Alpine Plugins -->
    <script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/persist@3.x.x/dist/cdn.min.js"></script>
    <!-- Alpine Core -->
    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
</head>
<body>
<main class="container" x-data>
    <article class="card">
        <header>
            <h3>Counter Value</h3>
        </header>
        <section>
            <p x-text="$store.counter.value"></p>
        </section>
    </article>

    <button type="button" x-on:click="$store.counter.increment()">
        Increment
    </button>
    <button type="button" x-on:click="$store.counter.reset()">
        Reset
    </button>
</main>
<script>
    document.addEventListener('alpine:initializing', () => {
        Alpine.store('counter', {
            value: Alpine.$persist(0),
            increment() {
                this.value++
            },
            reset() {
                this.value = 0;
            }
        })
    })
</script>
</body>
</html>

Conclusion

Alpine.js is an excellent library for building client-side experiences, and mixing it with Htmx or plain old JavaScript is a winning combination. I hope you try this and experiment with changing the behavior of increment and reset.

As always, thanks for reading and sharing my posts with others. Cheers.

Dynamic Htmx Islands with ASP.NET Core

Tue, 19 Nov 2024 00:00:00 GMT

I’m a big fan of static site renderers, and they are still one of the missing elements that would make ASP.NET Core more compelling for users across the vast ecosystem divide. In the meantime, developers must rely on tools like Astro, Jekyll, and 11ty to build static site experiences. Recently, I read about Astro 5.0 and its server island implementation. Server islands allow for mostly static pages to carve out portions of the page that will be rendered on-demand by, you guessed it, the server. This allows site authors to deliver fast, statically rendered pages that benefit the user while allowing for dynamic user-specific content.

In this post, we’ll see how to implement a similar island approach in ASP.NET Core applications that utilize response and output caching for performance increases while still carving out small page sections for dynamic content. We’ll use Htmx to trigger requests for dynamic content based on three exclusive page events.

What is an Island?

As described in the introduction, an island is part of the document object model (DOM) that is loaded after the initial page load. This allows the shared DOM across users to be cached while dynamic content specific to a user session is loaded afterward. While a post-load event is commonly used to retrieve dynamic content, islands can also be lazily loaded and take advantage of the revealed or intersect events. These will only trigger requests if the user sees this DOM element on the page. Optimizing pages by selecting island events can reduce unnecessary service processing. In general, islands are a powerful technique when building web applications.

Examples of islands may include a profile name in a page’s navigation, customized recommendations on a storefront, user-based statistics for a dashboard, and more. These islands typically comprise a small yet critical part of the user experience.

Now, let’s implement an island component for ASP.NET Core web applications.

The Island Plan

An island has three parts: the initial content, the triggering event, and the endpoint that returns the dynamic content.

Let’s start by seeing what our island implementation will look like on a Razor page.

<island url="/profile/avatar">
    <div class="alert alert-info d-flex justify-content-center vertical-align-center">
        <div class="spinner-border" role="status">
            <span class="visually-hidden">Loading...</span>
        </div>
    </div>
</island>

The island element has a URL attribute and some inner content that will be used as a placeholder while dynamic content is loaded. The handler for our dynamic content is a straightforward endpoint, but it could be any backend you choose. What you don’t see in this initial example is a configurable event. We’ll see that in action later in the post.

app.MapGet("/profile/avatar", () => Results.Content(
    //lang=html
    $"""
     <div class="alert alert-info">
        <p class="fs-1 fw-bold">🌴 Welcome to the island Khalid!</p>
        <p class="fs-3">You arrived on ({DateTime.Now.ToLongTimeString()})</p>
     </div>
     """)
);

OK, let’s build it!

Creating an Island TagHelper

While I initially attempted to do this with a ViewComponent I found it needing more in what it could accomplish. Tag Helpers are vastly more powerful and capable in this case.

using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Razor.TagHelpers;

public enum IslandEvents
{
    Load,
    Revealed,
    Intersect
}

[HtmlTargetElement("island")]
public class IslandTagHelper : TagHelper
{
    [HtmlAttributeName("url"), Required]
    public string? Url { get; set; }

    [HtmlAttributeName("event")]
    public IslandEvents Event { get; set; } = IslandEvents.Load;

    public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
    {
        // Changing the tag name to "div"
        output.TagName = "div";

        var @event = Event switch
        {
            IslandEvents.Load => "load",
            IslandEvents.Revealed => "revealed",
            IslandEvents.Intersect => "intersect once",
            _ => "load"
        };

        output.Attributes.SetAttribute("hx-get", Url);
        output.Attributes.SetAttribute("hx-trigger", @event);
        output.Attributes.SetAttribute("hx-swap", "outerHTML");

        // Retrieve the inner content
        var childContent = await output.GetChildContentAsync();
        output.Content.SetHtmlContent(childContent);

        // Ensuring the tag is not self-closing
        output.TagMode = TagMode.StartTagAndEndTag;
    }
}

Remember to register the tag helper in _ViewImports.cshtml. Since we’re using Htmx, you must add the script reference to your _Layout.cshtml.

<script src="https://unpkg.com/htmx.org@2.0.3"></script>

You’ll notice we have an enum of IslandEvents. Let’s discuss what each person does and how their behavior differs.

Load: After the initial page load, the page will retrieve the dynamic content.
Revealed: The dynamic content will be retrieved only after the element is visible to the user.
Intersect: If the element is in an overflow, the page will only retrieve the dynamic content after it intersects with the visible part of the page.

Let’s look at how to change the default loading behavior.

<div style="margin-top: 2000px">
    <island url="/profile/avatar" event="Revealed">
        <div class="alert alert-info d-flex justify-content-center vertical-align-center">
            <div class="spinner-border" role="status">
                <span class="visually-hidden">Loading...</span>
            </div>
        </div>
    </island>
</div>

In the example, the margin-top is 2000px. This forces us to scroll down to reveal the element, and only then will we call for dynamic content.

Response and Output Caching

While not the main focus of this post, response and output caching will be essential to using islands. As mentioned, you want to share as much as possible across user sessions to reap the benefits of these techniques.

You must update your Program file to include the following components to add output and response caching—first, the service registrations.

builder.Services.AddOutputCache();
builder.Services.AddResponseCaching();

Then, as part of your ASP.NET Core pipeline, you’ll need to add the following middleware calls.

app.UseResponseCaching();
app.UseOutputCache();

Once registered, you can apply output caching to the endpoint, which displays most of the content. Here is an example of its use on a Razor page.

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.AspNetCore.OutputCaching;

[OutputCache(Duration = 100),
 ResponseCache(
     Duration = 100,
     Location = ResponseCacheLocation.Any,
     NoStore = false)]
public class IndexModel(ILogger<IndexModel> logger) : PageModel
{
    private readonly ILogger<IndexModel> logger = logger;

    public void OnGet()
    {
    }
}

Feel free to apply caching to the dynamic endpoints, being mindful of cache-busting based on a user’s session variables.

app.MapGet("/profile/avatar", () => Results.Content(
    //lang=html
    $"""
     <div class="alert alert-info">
        <p class="fs-1 fw-bold">🌴 Welcome to the island Khalid!</p>
        <p class="fs-3">You arrived on ({DateTime.Now.ToLongTimeString()})</p>
     </div>
     """))
    .CacheOutput(policy => { /* apply caching policy here */ });

If you are unfamiliar with caching in ASP.NET Core, I recommend that you read the official documentation on the topic.

There you have it. ASP.NET Core Islands using Htmx.

Conclusion

Some folks may wonder why they should not just do all the caching and reuse on the server, including techniques like donut caching and _donut hole caching_. The advantage of this approach is that dynamic content can come from anywhere and isn’t explicitly tied to your ASP.NET Core server backend. You can deliver dynamic content from CDNs, function as service endpoints, use other static sites, and more. It’s a technique that benefits from ASP.NET Core but isn’t tied to it.

If I spent more time on this implementation, I’d likely integrate islands more closely to ASP.NET Core’s routing mechanisms, allowing users to specify pages, handlers, MVC actions, and more. That said, a simple url attribute works just fine.

Finally, TagHelpers are an underrated feature of the ASP.NET Core stack, and I think people should revisit them.

If you’d like to see a running sample of this project, visit my GitHub repository and try it out for yourself. Cheers.

Update HTML Elements with Htmx Triggers and ASP.NET Core

Tue, 22 Oct 2024 00:00:00 GMT

Let me start by saying that I love the combination of Htmx and ASP.NET Core, and it is a pairing that any .NET developer should consider, whether maintaining an existing application or building a new one. It’s very cool. I was recently talking about revisiting the hx-trigger and HX-Trigger header technique with ASP.NET Core on Mastodon with Illya Busigin, and they mentioned they use the same method to update the avatar image when a user updates their profile. So, I thought I’d try and see how to implement it myself.

In this post, we’ll see how to use the HX-Trigger facility in Htmx to update existing UI elements on a rendered HTML page.

The Moving Parts

When building any new feature in an application, you need to arrange multiple components to work together. Let’s address all the parts you’ll need to make this experience.

A User Profile store
Profile Settings endpoints for display and updating
An endpoint to refresh the avatar element on the page

We’ll be using the capabilities of ASP.NET Core Razor Pages and Razor Views to handle the HTML snippets that Htmx needs for swapping elements. Before we get into HTML and Htmx, let’s deal with our user profile storage service.

Note that you’ll need the NuGet packages of Htmx and, optionally, Htmx.TagHelpers.

The User Service

I created a straightforward class for the demo that will hold the user name and the avatar URL. In a “real application”, you’d likely store this information in a database or third-party auth service. Let’s see what I wrote.

public class UserService
{
    public static readonly string[] AvatarUrls =
    [
        "~/img/avatar_one.png",
        "~/img/avatar_two.png",
        "~/img/avatar_three.png",
    ];

    public string Name { get; set; } = "Khalid Abuhakmeh";
    public string AvatarUrl { get; set; } = AvatarUrls[0];
}

The user can choose from three existing avatars, which are stored in the wwwroot/img folder. Fewer options mean less code for the demo and more focus on the Htmx bits that come later.

Next, we’ll register the UserService as a Singleton in our ASP.NET Core setup class to maintain the state between requests. Note: This is only for the demo and is not recommended in any other scenario.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddSingleton<UserService>();

var app = builder.Build();

Cool! Now, we can inject this service where we need it to grab the current state of the user profile, which includes the name and avatar URL.

I inject this service into my Layout.cshtml and then render the avatar partial.

@inject UserService UserService
<!-- some HTML -->
@await Html.PartialAsync("_Avatar", UserService)

We’ll examine the partial later in the article, but first, let’s discuss our account endpoints.

Profile Endpoints

In a new Razor page titled Index, we’ll have three endpoints:

Show the profile settings form.
Accept user updates
Render the _Avatar profile image as partial content.

I’ll paste the full class here, and we’ll break it down into one endpoint at a time.

using System.Diagnostics.CodeAnalysis;
using Htmx;
using HtmxAvatarChange.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.AspNetCore.Mvc.Rendering;

namespace HtmxAvatarChange.Pages;

public class IndexModel(UserService userService, ILogger<IndexModel> logger) : PageModel
{
    [BindProperty] public string? Name { get; set; }

    [BindProperty] public string? AvatarUrl { get; set; }

    [TempData] public string? Message { get; set; }
    [TempData] public string? MessageCssClass { get; set; }

    [MemberNotNullWhen(true, nameof(Message))]
    public bool HasMessage => Message != null;

    public List<SelectListItem> Avatars => UserService
        .AvatarUrls
        .Select((x, i) => new SelectListItem($"avatar-{i:00}", x))
        .ToList();

    public void OnGet()
    {
        Name = userService.Name;
        AvatarUrl = userService.AvatarUrl;
    }

    public IActionResult OnPost()
    {
        if (ModelState.IsValid)
        {
            Message = "Successfully saved account settings";
            MessageCssClass = "alert-success";

            // change values
            userService.Name = Name!;
            userService.AvatarUrl = AvatarUrl!;

            Response.Htmx(h =>
                h.WithTrigger("avatar"));
        }
        else
        {
            Message = "Failed to save account settings";
            MessageCssClass = "alert-danger";
        }

        if (Request.IsHtmx())
        {
            return Partial("_Form", this);
        }

        return RedirectToPage("Index");
    }

    public IActionResult OnGetAvatar()
    {
        return Partial("_Avatar", userService);
    }

    public string? IsCurrentAvatar(string avatarValue)
    {
        return avatarValue == AvatarUrl ? "checked" : null;
    }
}

The first method we’ll look at is OnGet. This method takes the information from the UserService and hydrates our property. These properties will be used to bind information to our form.

public void OnGet()
{
  Name = userService.Name;
  AvatarUrl = userService.AvatarUrl;
}

Next, closer to the bottom of the class, let’s look at a similar method, OnGetAvatar.

public IActionResult OnGetAvatar()
{
  return Partial("_Avatar", userService);
}

This method returns the partial view of _Avatar, simply displaying our user information. Now, let’s look at the OnPost method, which is the juiciest of the implementations.

public IActionResult OnPost()
{
  if (ModelState.IsValid)
  {
    Message = "Successfully saved account settings";
    MessageCssClass = "alert-success";

    // change values
    userService.Name = Name!;
    userService.AvatarUrl = AvatarUrl!;

    Response.Htmx(h =>
      h.WithTrigger("avatar"));
  }
  else
  {
    Message = "Failed to save account settings";
    MessageCssClass = "alert-danger";
  }

  if (Request.IsHtmx())
  {
    return Partial("_Form", this);
  }

  return RedirectToPage("Index");
}

Here, we determine if the user input is valid and then update the page. The two most important lines include the Htmx references.

Response.Htmx(h =>
  h.WithTrigger("avatar"));

If the incoming request was initiated with Htmx, we add a response header to tell Htmx to fire a client-side event of avatar. Any element subscribing to this event will then trigger another request. In our case, we’ll be calling the OnGetAvatar endpoint. You can add as many events as you need here, but we only want one in our case.

The following reference to Htmx checks if Htmx initiated the request. If it was, we need to send back a partial Html snippet.

if (Request.IsHtmx())
{
  return Partial("_Form", this);
}

That’s it! But what do the Razor views look like?

Htmx and Partial Views

Let’s start with the form since it is the focal point of our user experience. It’s straightforward Razor code with one exception: the Htmx attributes on the form tag.

@model IndexModel

<fieldset id="account-settings">
    <legend>Account Settings</legend>

    @if (Model.HasMessage)
    {
        <div class="alert @(Model.MessageCssClass ?? "alert-info")" role="alert">
            @Model.Message
        </div>
    }

    <form method="post" hx-post hx-target="#account-settings" hx-swap="outerHTML">
        <div class="form-group row">
            <label asp-for="Name" class="col-sm-2 col-form-label">Name</label>
            <div class="col-sm-10">
                <input class="form-control" asp-for="Name">
            </div>
        </div>
        <fieldset class="form-group mt-3">
            <div class="row">
                <legend class="col-form-label col-sm-2 pt-0">Avatar</legend>
                <div class="col-sm-10">
                    @foreach (var avatar in Model.Avatars)
                    {
                        <div class="form-check">
                            <input
                                id="@avatar.Text"
                                asp-for="AvatarUrl"
                                class="form-check-inline" type="radio"
                                value="@avatar.Value"
                                checked="@Model.IsCurrentAvatar(avatar.Value)">
                            <label class="form-check-label" for="@avatar.Text">
                                <img src="@Url.Content(avatar.Value)" class="profile-pic" alt="@avatar.Text"/>
                            </label>
                        </div>
                    }
                </div>
            </div>
        </fieldset>
        <div class="form-group row mt-3">
            <button type="submit" class="btn btn-primary">Save Profile</button>
        </div>
    </form>
</fieldset>

These Htmx attributes allow us to hijack the form submission and route it through an Htmx request, allowing the library to process the header request. Once processed, it fires the event on the _Avatar partial. Let’s take a look at that view now.

@model HtmxAvatarChange.Models.UserService

<div id="profile-avatar"
     class="mx-2 smooth"
     hx-get="@Url.Page("Index", "Avatar")"
     hx-trigger="avatar from:body">
    <div class="profile-pic">
        <img src="@Url.Content(Model.AvatarUrl)" alt="Profile Picture">
    </div>
    <span class="navbar-text"> @Model.Name</span>
</div>

The essential attribute on this view is the hx-trigger attribute. Note the exact value.

hx-trigger="avatar from:body"

The from:body is essential, as the body element is what Htmx uses to broadcast the event. That’s it. Let’s see it in action!

Wow! That’s cool!

Conclusion

HX-Trigger headers can help you decouple UI elements from each other and create a system of elements that can act independently. This can be very powerful, but it should be used in moderation, like all things. Remember, each triggered event results in a request back to the server, which could come at a cost. That said, many existing SPA UI approaches already make expensive calls to the server, so this might not be any worse than a GraphQL call or JSON over an HTTP request.

I’ve uploaded the code for this sample to my GitHub repository so you can try it out.

As always, thanks for reading and hope you give this one a try.

Add EF Core Migrations to .NET Aspire Solutions

Tue, 08 Oct 2024 00:00:00 GMT

Folks working with EF Core are likely very fond of the library’s migration features, one of the most vital selling points for adopting an ORM. If you’re building a .NET solution, your database schema will evolve, and adding, removing, and updating are everyday actions you must perform.

.NET Aspire can ease the development of distributed solutions, but you still need to bridge the gap between development time actions and runtime execution. With EF Core, a development time action is managing migrations, while at runtime, you’ll need to execute those migrations against a database. The original tutorial by the Microsoft documentation explains how to run a .NET Aspire application with migrations but leaves out how to do development time tasks.

In this post, we’ll explore how to manage migrations during the development process so you can get the most out of your .NET Aspire and Entity Framework Core adoption.

The Solution Structure

We’ll first need to understand the solution structure of our Aspire distributed application. This is what my solution looks like, but you can change the approach depending on your preferences.

AspireSandbox
|- AspireSandbox.AppHost
|- AspireSandbox.Data
|- AspireSandbox.ServiceDefaults
|- AspireSandbox.Web

The AspireSanbox.Data project contains my DbContext implementation, which is nothing remarkable.

using Microsoft.EntityFrameworkCore;

namespace AspireSandbox.Data;

public class Database(DbContextOptions<Database> options)
    : DbContext(options)
{
    public DbSet<Count> Counts => Set<Count>();
}

public class Count
{
    public int Id { get; set; }
    public DateTimeOffset CountedAt { get; set; } = DateTimeOffset.UtcNow;
}

The dependencies for this project include the following Entity Framework Core packages.

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
        <ImplicitUsings>enable</ImplicitUsings>
        <Nullable>enable</Nullable>
    </PropertyGroup>

    <ItemGroup>
      <PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.8" />
      <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="8.0.8">
        <PrivateAssets>all</PrivateAssets>
        <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      </PackageReference>
      <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="8.0.8" />
    </ItemGroup>

</Project>

Next, we must add this project as a reference to our AspireSandbox.AppHost project, paying attention to adding the attribute of IsAspireProjectResource and setting its value to false. This opts this project out of the Aspire source generators.

I have a few other package references, but pay attention to the Entity Framework Core dependencies.

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net8.0</TargetFramework>
        <ImplicitUsings>enable</ImplicitUsings>
        <Nullable>enable</Nullable>
        <IsAspireHost>true</IsAspireHost>
        <UserSecretsId>ba2648f9-6953-4e8b-9918-c241b1d99b09</UserSecretsId>
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="Aspire.Hosting.AppHost" Version="8.2.1"/>
        <PackageReference Include="Aspire.Hosting.PostgreSQL" Version="8.2.1" />
        <PackageReference Include="Aspire.Hosting.Redis" Version="8.2.1" />
        <PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.8" />
        <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="8.0.8">
          <PrivateAssets>all</PrivateAssets>
          <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
        </PackageReference>
    </ItemGroup>

    <ItemGroup>
      <ProjectReference Include="..\AspireSandbox.Data\AspireSandbox.Data.csproj"
                        IsAspireProjectResource="false" />
      <ProjectReference Include="..\AspireSandbox.Web\AspireSandbox.Web.csproj" />
    </ItemGroup>

</Project>

OK, we’re ready to write some code.

Entity Framework Core Design Time Factory

Entity Framework Core provides a mechanism for the tooling to connect and work with a database. Since our database is in the scope of our distributed application, we need to run our tooling when Aspire has built our dependency. Don’t worry; it will make sense in a second.

In the AspireSandbox.AppHost, create a new DataContextDesignTimeFactory class.

using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Design;

namespace AspireSandbox.AppHost;

public sealed class DataContextDesignTimeFactory :
  IDesignTimeDbContextFactory<Data.Database>
{
    public Data.Database CreateDbContext(string[] args)
    {
        var builder = DistributedApplication.CreateBuilder(args);

        var postgres = builder
            .AddPostgres("postgres")
            .AddDatabase("migrations", databaseName: "migrations");

        var optionsBuilder = new DbContextOptionsBuilder<Data.Database>();
        optionsBuilder.UseNpgsql("migrations");
        return new Data.Database(optionsBuilder.Options);
    }
}

This implementation will spin up our database dependency and allow us to create an instance of our DbContext implementation. At least long enough to create and add our migrations to our project. Remember that EF Core creates a model snapshot as a C# file, so there is no need to persist the database across migration runs.

EF Core CLI Command

Now, we can run the following command to spin up Aspire long enough to create a migration.

dotnet ef migrations --project ./AspireSandbox.Data --startup-project ./AspireSandbox.AppHost add Initial

Change the --project and --startup-project to match your solution structure.

If all goes well, you should now have a new database migration.

Conclusion

There you have it; you can now work seamlessly between your development environment and Aspire solution with just a new IDesignTimeDbContextFactory implementation and tweaking your CLI command.

Thanks to James Hancock for leaving this comment on the Aspire GitHub issues and inspiring this blog post. His solution is pretty +$%! good.

Htmx and Playwright Tests in C#

Tue, 24 Sep 2024 00:00:00 GMT

Community member Jonathan Channon recently approached me about an appropriate way to test your Htmx-powered applications using the Playwright testing framework. It can be annoying to get the timing right between sending an HTMX request, processing it on the server, and applying it to the page.

In this post, we’ll see a surefire way to wait for Htmx to finish before testing the state of your pages, thus leading to more reliable tests and faster test execution. Let’s go.

The Htmx Counter Application

Let’s first see what application we’ll be testing. It’s a simple **Counter ** component that increases in value when the user presses a button.

@model HtmxPlaywrightIntegration.ViewModels.CounterViewModel

<div id="counter" class="card">
    <div id="value" class="card-body">
        @Model.Count
    </div>
    <div class="card-footer">
        <form asp-page="Index" method="post"
              hx-post
              hx-target="#counter"
              hx-swap="outerHTML">
            <button class="btn btn-primary">Increment</button>
        </form>
    </div>
</div>

The ASP.NET Core endpoint is straightforward.

using HtmxPlaywrightIntegration.ViewModels;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;

namespace HtmxPlaywrightIntegration.Pages;

public class IndexModel(ILogger<IndexModel> logger) : PageModel
{
    public static CounterViewModel Value { get; set; }
        = new();

    public void OnGet()
    {
    }

    public IActionResult OnPost()
    {
        Value.Count += 1;
        return Partial("_Counter", Value);
    }
}

Clicking the button will make a request to the server, increment the value, and return the HTML snippet to be processed into the page.

Now, let’s move on to the next part of the process, the Htmx lifecycle.

Htmx Request Lifecycle Events

Htmx contains multiple lifecycle events that we can utilize during a request. These events allow us to modify outgoing requests and understand what stages Htmx is at during the processing phase.

The lifecycle event we are most interested in is htmx:afterSettle. Settling is the process after all DOM changes have been applied and the page is now stable. Let’s hook into this page event and write a console message. I’ve added this to the typical site.js file, but it can go anywhere within your application.

document.body.addEventListener('htmx:afterSettle', function(evt) {
    console.log('playwright:continue');
});

Now, whenever we settle the page, a console message will be written with the value of playwright:continue. We’ll see how to register this script into our page in the next section using the Playwright APIs.

Playwright and Htmx Extensions

Now, let’s look at our test.

namespace HtmxPlaywrightIntegration.Tests;

[Parallelizable(ParallelScope.Self)]
[TestFixture]
public class Tests : PageTest
{
    [Test]
    public async Task CanIncrementCountUsingHtmx()
    {
        await Page.GotoAsync("http://localhost:5170");

        await Page.RegisterHtmxLifecycleListener();

        var button = Page.Locator("text=Increment");
        var body = Page.Locator("#value");

        var currentCount = int.Parse(await body.TextContentAsync() ?? "-1");

        await button.ClickAsync();
        await Page.WaitForHtmx();

        await Expect(body).ToHaveTextAsync($"{currentCount+1}");
    }
}

We first call the RegisterHtmxLifecycleListener script. This is the same JavaScript seen above. Then, we call WaitForHtmx, which will wait for the console message in our page’s output. Let’s see how these extension methods work.

using Microsoft.Playwright;

namespace HtmxPlaywrightIntegration.Tests;

public static class HtmxExtensions
{
    private const string Continue = "playwright:continue";

    public static Task WaitForHtmx(this IPage page)
    {
        return page.WaitForConsoleMessageAsync(new() {
            Predicate = message => message.Text == Continue
        });
    }

    public static Task RegisterHtmxLifecycleListener(this IPage page)
    {
        return page.AddScriptTagAsync(new()
        {
            // language=javascript
            Content = $$"""
                      document.body.addEventListener('htmx:afterSettle', function(evt) {
                          console.log('{{Continue}}');
                      });
                      """
        });
    }
}

It’s that easy. Now, your Playwright tests can wait for messages generated by the Htmx lifecycle, so you don’t have to worry about changes to your implementation on the front or back end changing how your tests execute. Additionally, you won’t have to waste time waiting for random delays to progress through your tests.

I hope you found this post helpful. Have fun building Htmx apps tested by Playwright. Cheers.

Intersperse Values for Enumerable Collections

Tue, 10 Sep 2024 00:00:00 GMT

JavaScript, for better or worse, has a much smaller standard library than what .NET developers are used to with the base class library (BCL). The JavaScript community has made many attempts to build a standard library, and I’m sure some of them are great. As I was scanning the options, I came across a fascinating method named intersperse, which “inserts a separator between the elements of its list argument”.

In this post, I’ll implement the same method in C# as an extension method on the IEnumerable interface.

Intersperse implementation in C#

Let’s first look at a few examples and the expected output before we look at the implementation of the method.

var hello = new string("Hello".Intersperse('-').ToArray());
var one = new string("1".Intersperse('x').ToArray());
var @null = ((IEnumerable<object>)null!).Intersperse(',').ToArray();
var array = new[] { 1, 2, 3 }.Intersperse(42).ToArray();
var menu = new [] {"Home", "About", "Privacy" }
    .Intersperse(" > ")
    .Aggregate((a, b) => $"{a}{b}");

Console.WriteLine($"'{hello}' interspersed with '-' is {hello}");
Console.WriteLine($"1 interspersed is {one}");
Console.WriteLine($"null interspersed is {@null}");
Console.WriteLine($"array interspersed is {string.Join(", ", array)}");
Console.WriteLine($"The menu is {menu}");

Running this application, we will see the following output.

'H-e-l-l-o' interspersed with '-' is H-e-l-l-o
1 interspersed is 1
null interspersed is System.Object[]
array interspersed is 1, 42, 2, 42, 3
The menu is Home > About > Privacy

Let’s get to the implementation!

public static class EnumerableExtensions
{
    public static IEnumerable<T> Intersperse<T>(
        this IEnumerable<T>? source,
        T delimiter)
    {
        if (source is null) yield break;

        using var enumerator = source.GetEnumerator();
        var hasFirstElement = enumerator.MoveNext();

        if (hasFirstElement == false) yield break;

        yield return enumerator.Current;

        while (enumerator.MoveNext())
        {
            yield return delimiter;
            yield return enumerator.Current;
        }
    }
}

I used yield to reduce the number of iterations on the collection being passed, as it would add unnecessary overhead. Additionally, I could have used a method like Zip, but that would have required more gymnastics than the current implementation.

I hope you enjoyed reading this quick blog post, and as always, thanks for reading. Cheers.