Khalid Abuhakmeh

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

Tue, 22 Apr 2025 00:00:00 +0000

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 +0000

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 +0000

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.

The Curious Case of .NET ConcurrentDictionary and Closures

Tue, 18 Feb 2025 00:00:00 +0000

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 +0000

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 +0000

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.

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 +0000

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 +0000

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 +0000

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
// Program.cs
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 +0000

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 +0000

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 +0000

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](https://www.computerworld.com/article/1604649/what-exactly-is-donut-caching.html). 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 +0000

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 +0000

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 +0000

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 +0000

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.

Checked and Unchecked Arithmetic Operations in .NET

Tue, 27 Aug 2024 00:00:00 +0000

The other day, I played around with the Fibonacci sequence and overflowed my int variables in surprisingly low iterations. Did you know you’ll overflow an integer in **48 ** iterations? Don’t believe me? Let’s take a look at the result of the code you’ll see later in this post.

Enter an integer: 48
Fibonacci sequence for 48:
0,1,1,2,3,5,8,13,21,34,55,89,144,233,377,610,987,1597,2584,4181,6765,10946,17711,28657,46368,75025,121393,196418,
317811,514229,832040,1346269,2178309,3524578,5702887,9227465,14930352,24157817,39088169,63245986,102334155,165580
141,267914296,433494437,701408733,1134903170,1836311903,-1323752223

You’ll notice that the last value has looped back to a negative value. Oh no! This is a tell-tale sign that an overflow has occurred.

This post will explore how to keep your applications safe from these overflow issues.

The code causing the overflow

First, let’s look at my implementation of the Fibonacci sequence generator. I’m using Spectre.Console to make the output more appealing, but it’s optional. I’m also using the System.Numerics namespace, which will allow you to experiment with different number types in .NET.

using System.Numerics;
using Spectre.Console;

while (true)
{
    try
    {
        var integer = AnsiConsole.Ask<int>("Enter an integer: ");

        if (integer <= -1)
        {
            AnsiConsole.MarkupLine("Goodbye!");
            break;
        }

        var numbers = GenerateFibonacci<int>((uint)integer);
        AnsiConsole.MarkupLine($"[bold green]Fibonacci sequence for {integer}:[/]");
        AnsiConsole.MarkupLine($"[bold yellow]{string.Join(",", numbers)}[/]");
        AnsiConsole.MarkupLine("");
    }
    catch (ArgumentOutOfRangeException)
    {
        AnsiConsole.MarkupLine("[red]Error: pick a value greater than 2[/]");
    }
}

static T[] GenerateFibonacci<T>(uint iterations)
    where T : INumber<T>
{
    ArgumentOutOfRangeException
        .ThrowIfLessThan<uint>(iterations, 2, "iterations must be greater than or equal to 2");

    T[] fib = new T[iterations];
    fib[0] = T.Zero;
    fib[1] = T.One;
    for (int i = 2; i < iterations; i++)
    {
        fib[i] = fib[i - 1] + fib[i - 2];
    }

    return fib;
}

Neat! Now, why does the issue occur in the first place?

Unchecked Arithmetic

By default, .NET performs unchecked arithmetic operations. That means the runtime assumes you know what you’re doing when adding one variable to another. This is true in most day-to-day cases, as the scale of numbers most developers deal with is on the lower side of the maximum int and long values.

For integers, the max value is 2147483647, and it is doubled to 4294967295 if you drop the sign —/+ from the value. For a long, the max value is 9223372036854775807, which is quite a lot bigger but not infinite. If your application increments values indefinitely, you will run into overflow issues, and no known type will save you. It’s just math!

As you’ve seen previously, the issue is that the numbers will loop around from positive to negative values and back. Your application will continue to “work” but likely will be nonsensical and wrong.

How do we fix this issue? Well, there are two ways.

The `checked` keyword

The first and most precise way to fix this issue is to use the checked keyword. Using this keyword creates a scope where arithmetic overflows will trigger an OverflowException.

static T[] GenerateFibonacci<T>(uint iterations)
    where T : INumber<T>
{
    ArgumentOutOfRangeException
        .ThrowIfLessThan<uint>(iterations, 2, "iterations must be greater than or equal to 2");

    T[] fib = new T[iterations];
    fib[0] = T.Zero;
    fib[1] = T.One;
    for (int i = 2; i < iterations; i++)
    {
        checked
        {
            fib[i] = fib[i - 1] + fib[i - 2];
        }
    }

    return fib;
}

Rerunning the same code results in the following exception.

Enter an integer: 49
Unhandled exception. System.OverflowException: Arithmetic operation resulted in an overflow.
   at System.Int32.System.Numerics.IAdditionOperators<System.Int32,System.Int32,System.Int32>.op_CheckedAddition(Int32 left, Int32 right)
   at Program.<<Main>$>g__GenerateFibonacci|0_0[T](UInt32 iterations) in /Users/khalidabuhakmeh/RiderProjects/zed-sample/Program.cs:line 40
   at Program.<Main>$(String[] args) in /Users/khalidabuhakmeh/RiderProjects/zed-sample/Program.cs:line 16

Nice. This technique is very selective and changes the intermediate language to call the op_CheckedAddition method instead.

      // [40 13 - 40 46]
      IL_003f: ldloc.0      // fib
      IL_0040: ldloc.1      // i
      IL_0041: ldloc.0      // fib
      IL_0042: ldloc.1      // i
      IL_0043: ldc.i4.1
      IL_0044: sub.ovf
      IL_0045: ldelem       !!0/*T*/
      IL_004a: ldloc.0      // fib
      IL_004b: ldloc.1      // i
      IL_004c: ldc.i4.2
      IL_004d: sub.ovf
      IL_004e: ldelem       !!0/*T*/
      IL_0053: constrained. !!0/*T*/
      IL_0059: call         !2/*T*/ class [System.Runtime]System.Numerics.IAdditionOperators`3<!!0/*T*/, !!0/*T*/, !!0/*T*/>::op_CheckedAddition(!0/*T*/, !1/*T*/)
      IL_005e: stelem       !!0/*T*/

Cool! Problem solved, but what if we want all our arithmetic checked?

Project Setting for Checked Arithmetic

You can add the CheckForOverflowUnderflow property in your project settings, and it will change all supported arithmetic operations to use checked operations.

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Spectre.Console" Version="0.49.1" />
  </ItemGroup>

</Project>

Easy peasy. Running the original code results in the same System.OverflowException.

To opt out of checking, you can use the converse unchecked keyword.

static T[] GenerateFibonacci<T>(uint iterations)
    where T : INumber<T>
{
    ArgumentOutOfRangeException
        .ThrowIfLessThan<uint>(iterations, 2, "iterations must be greater than or equal to 2");

    T[] fib = new T[iterations];
    fib[0] = T.Zero;
    fib[1] = T.One;
    for (int i = 2; i < iterations; i++)
    {
        unchecked
        {
            fib[i] = fib[i - 1] + fib[i - 2];
        }
    }

    return fib;
}

Conclusion

We can sometimes take for granted arithmetic operations and assume they will work. In most cases, they will, but if you’re building mission-critical applications that could run into underflow and overflow situations, it’s better to check these values so as not to cause potential headaches down the line.

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

Confirmation Dialogs with Htmx and SweetAlert

Tue, 20 Aug 2024 00:00:00 +0000

When building web experiences, there are safe operations and destructive ones. In the case of dangerous actions, it’s widespread to ask the user if they’d like to continue with the action before ultimately executing it.

In this post, we’ll explore a valuable feature in the Htmx documentation that allows you to intercept outgoing requests and present a Sweet Alert confirmation dialog. This feature can greatly enhance user experience and control in your web applications. Let’s dive in.

The `htmx:confirm` event

Htmx users are likely familiar with the hx-confirm attribute, which is a declarative way to use the confirm JavaScript function. This uses your browser’s native functionality to display a confirmation dialog that allows the user one last chance to cancel their action.

<button class="btn btn-danger" 
        hx-post=""
        name="input"
        value="DELETE"
        hx-confirm="Are you sure?">
    Delete Important Stuff
</button>

But folks likely don’t know that the htmx:confirm event is triggered before **every ** request. This allows you to intercept, stop, or continue any Htmx request on the client. This opens up a lot of UX opportunities.

To register for this event, you will need the following JavaScript referenced in your web application.

document.body.addEventListener('htmx:confirm', function (evt) {
    // do something here
    // you can evt.preventDefault()
    // or...
    // evt.details.issueRequest() to continue.
});

Let’s use the SweetAlert JavaScript library to enhance the dull confirm dialog.

Add SweetAlert to Htmx Confirmations

I’ll intercept an Htmx request using the event above and slot in a new confirmation dialog. This is the example shown in the Htm documentation. To get started, you’ll need to add a reference to SweetAlert in your web application.

<script src="https://unpkg.com/sweetalert/dist/sweetalert.min.js"></script>

You’ll need to modify your target elements with the following attribute.

<button class="btn btn-danger" 
        hx-post=""
        name="input"
        value="DELETE"
        confirm-with-sweet-alert='true'>
    Delete Important Stuff
</button>

Note that this attribute is only necessary if you want to be more selective about when and where this new dialog appears. If you aren’t selective, you don’t need this attribute.

Finally, let’s write some JavaScript code.

// site.js
document.body.addEventListener('htmx:confirm', function (evt) {
    if (evt.target.matches("[confirm-with-sweet-alert='true']")) {
        evt.preventDefault();
        swal({
            title: "Are you sure?",
            text: "Are you sure you are sure?",
            icon: "warning",
            buttons: true,
            dangerMode: true,
        }).then((confirmed) => {
            if (confirmed) {
                evt.detail.issueRequest();
            }
        });
    }
});

The event will only be handled when the target element has our confirm-with-sweet-alert attribute. Otherwise, it falls back to Htmx’s default behavior.

Cool! Now, you’ll see the SweetAlert dialog defined in our JavaScript whenever you click the button.

Conclusion

Htmx continues to surprise me with its flexibility and extension points. I recommend reading through more of the documentation to discover more features you can use in your applications. In this case, we can enhance the user experience of dangerous operations to give users more detailed information about the action they are about to take.

I hope you try this in your applications, and as always, thanks for reading.

How To Pick The Right Constructor When Using ActivatorUtilities In .NET

Tue, 13 Aug 2024 00:00:00 +0000

If you’ve ever worked with reflection in .NET, you’re likely familiar with Activator. In .NET 6, ActivatorUtilities was introduced to make it easier to create classes with dependencies. Constructor dependency injection is common in the .NET space, and you’re likely to run into several types that require constructor parameters before being created. The Activator class is a relic of a simpler time, whereas ActivatorUtilities meets developers where .NET is today.

In this post, we’ll look at a code example of how to guide ActivatorUtilities toward the constructor you want to use when building instances of types that may have multiple constructors.

Registering a Type and the Dependencies

Let’s start by looking at a Person class that has a total of three constructors. Wowza!

public class Person(string name, int age = 0)
{
    public Person(string name)
        : this(name, 0)
    {
        Console.WriteLine("Person(string)");
    }
    
    public Person(object name)
        : this(name.ToString()!, 41)
    {
        Console.WriteLine("Person(object)");
    }

    public string Name { get; } = name;
    public int Age { get; } = age;
}

We have the following constructors.

A primary constructor that takes a name and an optional age
A constructor that takes a string dependency
A constructor that takes an object dependency

Let’s set up our new ServiceCollection and add dependencies to the dependency collection. Note that you’ll need to install the NuGet package Microsoft.Extensions.DependencyInjection if you haven’t already.

using Microsoft.Extensions.DependencyInjection;

var collection = new ServiceCollection();

var value = "Khalid";

collection.AddTransient<Person>();
// an instance of object
collection.AddSingleton<object>(value);
// an instance of string
collection.AddSingleton<string>(value);

var serviceProvider = collection.BuildServiceProvider();

var person = ActivatorUtilities.CreateInstance<Person>(serviceProvider);

Console.WriteLine($"{person.Name} is {person.Age} years old.");

Take a second and guess what constructor implementation is called. We’ve satisfied all the dependencies, but just by looking at the code, you can feel a sense of uncertainty creeping in. Let’s run it.

Khalid is 0 years old.

Ah, the primary constructor got called. It makes sense; that’s what “primary” means, right?

What if we want a different constructor to get called?

Using the ActivatorUtilitiesConstructor Attribute

In the Microsoft.Extensions.DependencyInjection package, you’ll find the ActivatorUtilitiesConstructorAttribute. This attribute gives the ServiceProvider hints at which constructor to call first. Let’s modify our Person class definition to call the constructor with the object dependency.

public class Person(string name, int age = 0)
{
    public Person(string name)
        : this(name, 0)
    {
        Console.WriteLine("Person(string)");
    }
    
    [ActivatorUtilitiesConstructor]
    public Person(object name)
        : this(name.ToString()!, 41)
    {
        Console.WriteLine("Person(object)");
    }

    public string Name { get; } = name;
    public int Age { get; } = age;
}

After rerunning our code, we’ll get the following output:

Person(object)
Khalid is 41 years old.

Note that we did not change the executing code; we only added a single attribute. With this knowledge, you can now have all the constructors you want on your types but still make it clear which constructor you’d like ActivatorUtilities to use.

There you have it. I hope you enjoyed this post. As always, thanks for reading and sharing with friends and colleagues. Cheers.

Add a Property to the Top-level Statements Program class

Tue, 06 Aug 2024 00:00:00 +0000

The evolution of the C# language has introduced us to many new features and probably made a lot of folks re-evaluate how they write their apps. In the latest versions of .NET, nothing has been marked such a stylistic shift as the introduction of top-level statements.

In this short post, we’ll examine how to add properties to your Program instance to improve the readability of utility console applications.

Top-level statement files

When starting a new console application, you can create a Program.cs file and opt into the top-level statements style. The single line below is a valid .NET application.

Console.WriteLine("Hello, World");

At compile-time, the compiler generates the typical ceremony associated with traditional applications. Looking at our app’s low-level C# version, we’ll see the symbols we typically expect to see in a .NET app.

using System;
using System.Runtime.CompilerServices;

[CompilerGenerated]
internal class Program
{
  private static void <Main>$(string[] args)
  {
    Console.WriteLine("Hello, World");
  }

  public Program()
  {
    base..ctor();
  }
}

You’ll see that there is always a Program class and the expected entry point of static void Main.

Let’s get more complex.

Console.WriteLine($"Hello, {GetName()}");  
  
string GetName()  
{  
    return Environment.GetCommandLineArgs()[1];  
}

What does this look like now?

using System;
using System.Runtime.CompilerServices;

[CompilerGenerated]
internal class Program
{
  private static void <Main>$(string[] args)
  {
    Console.WriteLine(string.Concat("Hello, ", Program.<<Main>$>g__GetName|0_0()));
  }

  public Program()
  {
    base..ctor();
  }

  [NullableContext(1)]
  [CompilerGenerated]
  internal static string <<Main>$>g__GetName|0_0()
  {
    return Environment.GetCommandLineArgs()[1];
  }
}

The method attached to the end of the file becomes an internal static method on the Program. Can we add a property? In this case, a property would be much more readable than a method.

// not valid c#
Console.WriteLine($"Hello, {Name}");  
  
string Name => Environment.GetCommandLineArgs()[1];

This syntax does not work. Still, we can add a Name property to our Program file.

Adding the property with a partial class

How do we get top-level properties into our top-level statements file? Well, it’s pretty straightforward. The Program class can be extended using the partial keyword. Let’s do that.

Console.WriteLine($"Hello, {Name}");

partial class Program
{
    static string Name => Environment.GetCommandLineArgs()[1];    
}

Now, we can add scoped properties to our top-level statement files. Returning to our low-level C#, we can see what the compiler is doing.

using System;
using System.Runtime.CompilerServices;

internal class Program
{
  private static void <Main>$(string[] args)
  {
    Console.WriteLine(string.Concat("Hello, ", Program.Name));
  }

  [Nullable(1)]
  private static string Name
  {
    [NullableContext(1)] get
    {
      return Environment.GetCommandLineArgs()[1];
    }
  }

  public Program()
  {
    base..ctor();
  }
}

You can also move your partial Program class to another file if you are going for that minimal aesthetic entry point look. One thing to note is that all properties must be static, as the properties are referenced in the static void Main method.

I hope this post helps, and as always, thanks for reading. Cheers.

Fix .NET MAUI MissingEntitlement and Provisioning Profiles Issues

Tue, 30 Jul 2024 00:00:00 +0000

There are times on this blog when I write posts for the reader’s benefit and times when I need to memorialize my own pain and suffering to find a solution to a seemingly simple issue. This post is the latter.

In this post, we’ll see what it takes to fix the MissingEntitlement and “Could not find any available provisioning profiles” errors.

Also, be warned: You might not like what you see.

Ok, let’s go!

iOS, Security, and Entitlements

I recently purchased the “.NET MAUI in Action” book and was working through the sample application in Chapter 3. The author’s perspective differs from mine in that their app targets Windows, and I am targeting iOS. As one might expect, the details between the two target platforms differ.

This difference led to my first issue running the sample application targeting iOS; I got this exception and crashed the application.

System.Exception: Error adding record: MissingEntitlement
   at Microsoft.Maui.Storage.KeyChain.SetValueForKey(String value, String key, String service)
   at Microsoft.Maui.Storage.SecureStorageImplementation.SetAsync(String key, String value, SecAccessible accessible)
   at Microsoft.Maui.Storage.SecureStorageImplementation.PlatformSetAsync(String key, String data)
   at Microsoft.Maui.Storage.SecureStorageImplementation.SetAsync(String key, String value)
   at Microsoft.Maui.Storage.SecureStorage.SetAsync(String key, String value)

This leads users to the first issue, a missing Entitlements.plist file. What are Entitlements?

Side Note: The MissingEntitlment exception could really use a more helpful error message. WHICH ONE MAUI? WHICH ONE?!

All iOS applications are sandboxed, allowing the app only to execute iOS functions it has requested and explicitly been granted by the user. Entitlements ensure apps behave as intended and don’t expose users to unnecessary risks. For your application to use iOS features like Maps, KeyChain, or Siri, you must first add values to the Entitlements.plist file to request access. Only then can you use these features.

You can read more about Entitlements on the Microsoft documentation site.

Side Note: I would think the .NET MAUI template would have an empty entitlements file already in the Platforms/iOS folder, but it doesn’t.

So, in the Platforms/iOS folder, you’ll need to create an Entitlements.plistfile with the following XML.

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
    </dict>
</plist>

For enabling the Maps feature, your Entitlements.plist file might look like the following.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>com.apple.developer.maps</key>
        <true/>
    </dict>
</plist>

You can also use JetBrains Rider’s plist editor to create and manage these files with schema validation and an excellent UI experience.

You should be good to go, right? Not so fast. Running your application now presents you with the following error.

1>Xamarin.Shared.targets(1820,3): Error  : Could not find any available provisioning profiles for MauiTodo on iOS.

Wait…. what?! What’s going on? I’m only trying to deploy to the iOS simulator!

Provisioning Profiles, Apple Developer Account, and Physical Devices

Adding the Entitlements.plist file has cascaded into a secondary issue in the build process. (Note that I’m currently using .NET 8.0 and 9.0 workloads).

1>Xamarin.Shared.targets(1820,3): Error  : Could not find any available provisioning profiles for MauiTodo on iOS.

MAUI is looking for a provisioning profile. What is a provisioning profile?

A development provisioning profile allows your app to launch on devices and use certain app services during development. For an individual, a development provisioning profile allows apps signed by you to run on your registered devices. For an organization, a development provisioning profile allows apps developed by a team to be signed by any member of the team and installed on their devices. –Apple

Huh. How do you fix this issue? I just want to deploy my app to my local simulator.

Here are the steps you’ll need to fix this, and I’ll start with the two most significant hurdles.

A physical iOS device. Yes, you will need a physical device.
An Apple Developer Account at $99/year. Sign up here or give up now.
macOS and XCode

First, Be sure to enable Developer Mode on your device. You’ll need the identifier for this physical device. To get your device’s UUID, connect your iOS device to your macOS machine and launch XCode. Open “Window | Devices and Simulators.” Here, you’ll see your device’s ID. You’ll need this to register the device.

Log in to your new Apple Developer account and add your physical device. You can visit the “Register a New Device” page. Here, you’ll register the physical device, at which point you’ll get a provisioning profile.

Now, open your MAUI project in XCode (which you can do from JetBrains Rider). Under the Project settings’ “Signing & Capabilities” tab, select a Team and check the Automatically manage signing checkbox. If you don’t see a Team, be sure to add your Apple Developer account to Xcode under “Settings | Accounts” and try again.

If all goes well, you should see values for the Provisioning Profiles and Signing Certificate fields in the bottom iOS section.

Now, you can go back to building and deploying your application with Entitlements to the iOS simulator without any issues. Xcode will handle signing your apps from here on out.

Conclusion

The steps outlined here fixed my issue, but honestly, it took way longer and a significant amount of money 💰 to solve this issue, given the price of a physical iOS device and an Apple Developer subscription. I am still not sure if this is an Xcode and iOS issue or a MAUI issue. All I know is that it’s a MAUI developer stumbling block that I ran into, and it’s now “solved.”

I hope this post helps you on your MAUI development journey. Cheers.

Health Checks for ASP.NET Core and Entity Framework Core

Tue, 23 Jul 2024 00:00:00 +0000

I’ve recently been reading up on .NET Aspire and have found a lot of cool .NET tech underpinning the offering. One of the tools that has gotten a glow-up since I last looked at it has been Microsoft.Extensions.Diagnostics.HealthChecks package provides you with the infrastructure to perform various types of system health monitoring.

In this post, we’ll look at installing the health checks package into existing ASP.NET Core applications and using an additional package to perform health checks on your databases using Entity Framework Core.

Install and Set Up Health Checks

In an existing ASP.NET Core application, you’ll need to install the following package.

dotnet add package Microsoft.Extensions.Diagnostics.HealthChecks

Once the package has been installed, you must do several setup tasks in your Program file.

The first step is to register the HealthChecks middleware and services in the services collection.

builder.Services.AddHealthChecks();

Next, in your ASP.NET Core request pipeline, you’ll need to register the middleware. You can choose whether to place the middleware before or after the authorization middleware, but as you’ll see, there might not be much reason to have this behind an auth check.

You’ll need to choose a URL path to access your health check. I used the /health path for this case, but feel free to choose whatever suits you.

app.UseRouting();

app.UseHealthChecks("/health");

app.UseAuthorization();

Navigating to the /health endpoint will get you the following response.

Healthy

The response will always be a string of Healthy, Unhealthy, or Degraded. This makes it simple for third-party health check systems to determine your application’s general health quickly. Your logging system will handle the details of the issues.

Let’s write a new health check! You’ll need to implement the IHealthCheck interface and implement the CheckHealthAsync method.

using Microsoft.Extensions.Diagnostics.HealthChecks;

namespace Healthnut.Services;

public class KhalidHealthCheck: IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, CancellationToken cancellationToken = new CancellationToken())
    {
        return Task.FromResult(
            HealthCheckResult.Degraded("Khalid ate some ice cream")
        );
    }
}

These classes are added to your services collection, so they can opt-in to any dependency injection mechanisms you might want to use. Let’s add it to our health checks. Modify the registration in the Program file.

builder.Services
    .AddHealthChecks()
    .AddCheck<KhalidHealthCheck>("Khalid");

Note that health checks require a unique name. You’ll see a Degraded string after rerunning the app and hitting the /health endpoint. What’s more interesting is that you’ll see a new log message on your terminal.

warn: Microsoft.Extensions.Diagnostics.HealthChecks.DefaultHealthCheckService[103]
      Health check Khalid with status Degraded completed after 2.5366ms with message 'Khalid ate some ice cream'

Health checks are async, so you can write any logic you need to determine the health of your system, but be sure it’s snappy and non-resource-intensive checks; otherwise, ironically, the health checks could lead to unhealthy results.

If you hate the formalities of classes and interfaces, you can also choose to implement health checks directly at the point of registration. This can be helpful for microservices or smaller utility applications.

builder.Services
    .AddHealthChecks()
    .AddCheck<KhalidHealthCheck>("Khalid")
    .AddAsyncCheck("Butter", async () =>
    {
        await Task.Delay(1000);
        return new HealthCheckResult(HealthStatus.Healthy, "Butter is good");
    });

So far, it’s been good, but let’s now use health checks for our database.

Health checks for Entity Framework Core

You’ll need to install a new package to get a new extension method for EF Core health checks. You should already have an Entity Framework Core application with a DbContext implementation. If you don’t, create one. Now, the package.

dotnet add package Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore

Once installed, we can update our health check registration using the following line.

builder.Services
    .AddHealthChecks()
    .AddCheck<KhalidHealthCheck>("Khalid")
    .AddAsyncCheck("Butter", async () =>
    {
        await Task.Delay(1000);
        return new HealthCheckResult(HealthStatus.Healthy, "Butter is good");
    })
    .AddDbContextCheck<Database>(
        "people check",
        customTestQuery: (db, token) => db.People.AnyAsync(token)
    );

The AddDbContextCheck takes a generic argument of a DbContext implementation, and the customTestQuery argument is a query you can execute to verify the health of your database. The provided query must return a single bool value. Use logical LINQ operators such as Any and All, or write queries that evaluate entirely on the server with limited results returned. Oh, and keep these queries snappy and to the point. Doing expensive database checks may impact the health of your application.

Rerunning the application, we’ll see the log message we expect.

info: Microsoft.EntityFrameworkCore.Database.Command[20101]
      Executed DbCommand (14ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
      SELECT EXISTS (
          SELECT 1
          FROM "People" AS "p")
fail: Microsoft.Extensions.Diagnostics.HealthChecks.DefaultHealthCheckService[103]
      Health check people check with status Unhealthy completed after 1545.2538ms with message '(null)'

Neat!

Conclusion

We barely scratched the surface of what’s possible with the health checks feature of ASP.NET Core, and there’s so much more you can do to provide real-time health updates of your applications. There’s also a wide variety of health check extensions on NuGet, so you’ll rarely have to write your own, but it’s nice knowing you could with such a straightforward interface.

Finally, It’s important to remember that you’ll need a monitoring tool to watch these endpoints to get the most out of them, but I’ll leave that decision up to you.

As always, thanks for reading and cheers.

How To Fix .NET Nullability Warnings For Guarded Members

Tue, 16 Jul 2024 00:00:00 +0000

Nullability provides developers with development-time warnings that can help reduce dereferencing issues. These errors can be costly, but with the power of a few additional checks in code, developers can easily avoid them, putting them in control of their code’s quality.

In this post, we’ll see a code sample that should be “safe” yet continues to give IDE and build-time warnings about dereferencing of a possibly null reference. We’ll also see how to adjust your code to remove unnecessary warnings in current and future projects.

Dereference of a possibly null reference

Let’s look at some basic C# code, which you likely have something similar to in your projects.

var database = new Database();

// Name cannot be null when Initialize is true
if (database.Initialized)
{
    // This has a warning about Name being null
    var length = database.Name.Length;
    
    Console.WriteLine($"{database.Name} and length is {length}");
}

Console.WriteLine("Hello, World!");

public class Database
{
    public string? Name { get; set; }
    public bool Initialized => Name is not null;
}

Here, we have a Database class, and we know the Name property will never be null if the boolean property of Initialized returns true. Yet, you likely see a yellow line warning you with the message “Dereference of a possibly null reference” in your editor. Additionally, this warning shows up in your build logs.

Program.cs(9,18): Warning CS8602 : Dereference of a possibly null reference.

We can ignore this, right? Well, not if your team uses the MSBuild element of TreatWarningsAsErrors.

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

    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net9.0</TargetFramework>
        <ImplicitUsings>enable</ImplicitUsings>
        <Nullable>enable</Nullable>
        <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    </PropertyGroup>

</Project>

Oh no! Our build is broken!

0>Program.cs(9,18): Error CS8602 : Dereference of a possibly null reference.
0>------- Finished building project: ConsoleApp2. Succeeded: False. Errors: 1. Warnings: 0

How do we fix this?

Using MemberNotNullWhen On Boolean Properties

There are several attributes under the System.Diagnostics.CodeAnalysis namespace that we can use to give the compiler hints about the safety of the written code. The attribute we’ll use is MemberNotNullWhen, which allows us to decorate a property or method that returns a bool result and tie the safety check to one or more other properties.

using System.Diagnostics.CodeAnalysis;

var database = new Database();

// Name cannot be null when Initialize is true
if (database.Initialized)
{
    // The warning/error is now gone
    var length = database.Name.Length;
    
    Console.WriteLine($"{database.Name} and length is {length}");
}

Console.WriteLine("Hello, World!");

public class Database
{
    public string? Name { get; set; }
    // this attribute fixes the issue
    [MemberNotNullWhen(true, nameof(Name))]
    public bool Initialized => Name is not null;
}

The steps in the code are as follows:

Decorate a boolean property or method that returns bool with MemberNotNullWhen.
Choose the value state that signals safety to the compiler.
Choose one or more nullable members covered by the bool member.

There should be no editor warnings or build errors, and you can live the good life. I hope you found this post helpful. As always, thank you for reading. Cheers.

HTML Datalist for ASP.NET Core Inputs

Tue, 09 Jul 2024 00:00:00 +0000

In my last blog post, I discussed range inputs. This time, we’ll examine a tag helper that adds support for the HTML element of datalist.

In this short post, I’ll explain what a datalist is and why you may want to consider using it in your ASP.NET Core applications. Finally, we’ll implement a set of tag helpers to make using the datalist element more straightforward with your ASP.NET Core MVC and Razor Page applications.

What is `datalist`?

True to its name, the datalist element allows web developers to create a list of options that are permissible or recommended for form input elements. This allows users to choose from a predefined list the application developer has curated.

Let’s look at a quick HTML example pulled from the MDN web docs.

<label for="ice-cream-choice">Choose a flavor:</label>
<input list="ice-cream-flavors" id="ice-cream-choice" name="ice-cream-choice"/>

<datalist id="ice-cream-flavors">
    <option value="Chocolate"></option>
    <option value="Coconut"></option>
    <option value="Mint"></option>
    <option value="Strawberry"></option>
    <option value="Vanilla"></option>
</datalist>

The ice-cream-choice field will use the datalist options and provide users with a dropdown of potential options but still allow users to type their choices using freeform text.

The list attribute supports multiple input types, including text, date, range, and color. While the datalist is supported in most browsers, Firefox partially supports the input field and does not work with the types date, time, range, and color.

Providing a datalist can guide your users to common answers for otherwise fuzzy fields. The element might be helpful in surveys or support forms.

How do we use it in ASP.NET Core MVC and Razor Pages?

Datalist TagHelper for MVC and Razor Pages

Let’s start with our end goal of using a datalist in our Razor views. We’ll look at a Razor Pages example where we’ll see the HTML and C# Page Model.

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.AspNetCore.Mvc.Rendering;

namespace OutputValues.Pages;

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

    public string? Message { get; set; }

    public List<SelectListItem> Fruits { get; } =
    [
        new("The finest from Tokyo", "Apple"),
        new("The curviest fruit", "Banana"),
        new("The citrus is amazing", "Orange")
    ];

    public void OnGet()
    {
    }

    public void OnPost()
    {
        Message = $"You selected {Value}!";
    }
}

We’ll reuse the SelectListItem class commonly used by the select element. There’s no reason to reinvent the wheel here. Next, let’s update our view.

<form method="post" asp-page="Index">
    <div>
        <label class="form-label" asp-for="Value"></label>
        <input class="form-control" asp-for="Value" asp-list="Fruits" />
    </div>

    <button type="submit" class="mt-3 btn btn-primary">
        Add
    </button>
    
    <datalist asp-items="Fruits"></datalist>
</form>

That’s it! We now have an input field backed by our new datalist. Let’s see what the output HTML looks like.


<form method="post" action="/">
    <div>
        <label class="form-label" for="Value">Value</label>
        <input class="form-control" type="text" id="Value" name="Value" value="" list="Fruits">
    </div>

    <button type="submit" class="mt-3 btn btn-primary">
        Add
    </button>

    <datalist id="Fruits">
        <option label="The finest from Tokyo" value="Apple"></option>
        <option label="The curviest fruit" value="Banana"></option>
        <option label="The citrus is amazing" value="Orange"></option>
    </datalist>
    <input name="__RequestVerificationToken" type="hidden" value="">
</form>

The tag helpers are designed to look for asp-items on a datalist element and an asp-list attribute on any input field. Let’s see how these two tag helpers are implemented.

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

namespace OutputValues;

[HtmlTargetElement("datalist", Attributes = ItemsAttributeName)]
public class DataListHelper : TagHelper
{
    private const string ItemsAttributeName = "asp-items";

    /// <summary>
    /// A collection of <see cref="SelectListItem"/> objects used to populate the &lt;datalist&gt; element with
    /// &lt;option&gt; elements.
    /// </summary>
    [HtmlAttributeName(ItemsAttributeName)]
    public ModelExpression For { get; set; } = default!;

    public override void Process(TagHelperContext context, TagHelperOutput output)
    {
        ArgumentNullException.ThrowIfNull(context);
        ArgumentNullException.ThrowIfNull(output);

        var items = (IEnumerable<SelectListItem>)For.Model ?? [];
        foreach (var item in items)
        {
            var tagBuilder = new TagBuilder("option")
            {
                Attributes =
                {
                    ["value"] = item.Value
                }
            };

            if (!string.IsNullOrWhiteSpace(item.Text))
            {
                tagBuilder.Attributes["label"] = item.Text;
            }

            output.PostContent.AppendHtml(tagBuilder);
        }

        // the developer may choose their own id if they choose to
        // otherwise we use the property name to generate an id
        if (!output.Attributes.ContainsName("id"))
        {
            var id = GetDatalistId(For);
            output.Attributes.SetAttribute("id", id);
        }
    }

    public static string GetDatalistId(ModelExpression @for)
    {
        // perhaps we want different ids
        return TagBuilder.CreateSanitizedId(@for.Name, "");
    }
}

[HtmlTargetElement("input", Attributes = ItemsAttributeName)]
public class DataListInputHelper : TagHelper
{
    private const string ItemsAttributeName = "asp-list";

    /// <summary>
    /// A collection of <see cref="SelectListItem"/> objects used to populate the &lt;datalist&gt; element with
    /// &lt;option&gt; elements.
    /// </summary>
    [HtmlAttributeName(ItemsAttributeName)]
    public ModelExpression For { get; set; } = default!;

    public override void Process(TagHelperContext context, TagHelperOutput output)
    {
        ArgumentNullException.ThrowIfNull(context);
        ArgumentNullException.ThrowIfNull(output);

        // if it already has a list attribute then don't override it
        // not sure why it's there, but sure why not 🤷‍♂️
        if (!output.Attributes.ContainsName("list"))
        {
            var listId = DataListHelper.GetDatalistId(For);
            output.Attributes.SetAttribute("list", listId);
        }
    }
}

This straightforward implementation could easily be modified to accommodate your needs.

The most crucial implementation detail is the ModelExpression, which allows us to get both the metadata of our property and the value of the property. It’s an awesome part of the tag helper API.

Conclusion

The datalist element is an HTML-native feature that provides completion on several input types. With a few simple tag helpers, we can derive the datalist options we need to power any input, thus reducing the work required to keep the UI and application data models in sync. Please try this and let me know if you found it helpful.

As always, thanks for reading, and cheers.

HTML Range Inputs with ASP.NET Core TagHelpers

Tue, 02 Jul 2024 00:00:00 +0000

I’ve recently been rediscovering all the input fields that HTML offers and how they can help developers build more straightforward user experiences. The library of native HTML controls is impressive, with 22 HTML input types as of this post.

Looking through ASP.NET Core’s InputTagHelper, I counted 14 supported input types based on the .NET common language runtime types you may use in your models. That’s over 8 controls missing from ASP.NET Core. The missing range input is one of the most valuable controls.

In this post, we’ll write an ASP.NET Core tag helper that piggybacks on the InputTagHelper and turns a number property into a range input.

What is the `range` Input?

The range input is as it sounds. Developers commonly refer to these elements as a “slider” since users typically slide an indicator to set a value. The input allows users to choose a value constrained by a minimum and maximum value. The limitation ensures that users can only choose valid values. When defining a range input, you may specify the max, min, and step attributes. You may also provide markers along the slider path in the form of a datalist. It is a very powerful control.

I highly recommend reading the MDN on the topic to learn more details.

TagHelper Piggyback to Slider

When working with ASP.NET Core MVC or Razor Pages, you’ll typically have a model and a razor view. Let’s examine both. First, the page model.

public class IndexModel(ILogger<IndexModel> logger) : PageModel
{
    [BindProperty]
    public int Value { get; set; }
    
    public string? Message { get; set; }
    
    public void OnGet()
    {
    }

    public void OnPost()
    {
        Message = $"You selected {Value}!";
    }
}

Next, the Razor view.

@page
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

@if (Model.Message is not null)
{
    <div class="alert alert-info">
        @Model.Message
    </div>
}

<form method="post" asp-page="Index">
    <div>
        <label class="form-label" asp-for="Value"></label>
        <input class="form-range" asp-for="Value" />
    </div>
    <button type="submit" class="btn btn-primary">
        Add
    </button>
</form>

So far, so good, but when you run this application, you’ll notice that the input type for our Value field is set to text. It’s not what we want, let’s fix that.

The first step is using the RangeAttribute and creating a derived RangeWithStepAttribute for additional metadata. You could also create separate attributes for additional metadata. The choice is yours.

public class RangeWithStepAttribute(int minimum, int maximum)
    : RangeAttribute(minimum, maximum)
{
    public double Step { get; set; } = 1;
}

Next, let’s decorate our property with the new attribute.

[BindProperty, RangeWithStep(1, 5, Step = 1)]
public int Value { get; set; }

So far, so good; now let’s create a tag helper that recognizes the RangeAttribute on our models.

using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Mvc.ViewFeatures;
using Microsoft.AspNetCore.Razor.TagHelpers;
using OutputValues.Pages;

namespace OutputValues;

[HtmlTargetElement("input", 
    Attributes = ForAttributeName, 
    TagStructure = TagStructure.WithoutEndTag)]
public class RangeInputTagHelper : TagHelper
{
    private const string ForAttributeName = "asp-for";
    private const string TypeAttributeValue = "range";

    public override int Order { get; } = -999;

    [HtmlAttributeName(ForAttributeName)] public ModelExpression For { get; set; }

    public override void Process(TagHelperContext context, TagHelperOutput output)
    {
        var metadata = For.Metadata;

        if (metadata is { ContainerType: not null, PropertyName: not null })
        {
            var attribute =
                metadata.ContainerType.GetProperty(metadata.PropertyName)
                ?.GetCustomAttributes(typeof(RangeAttribute), true)
                .FirstOrDefault();
            
            if (attribute is RangeAttribute range)
            {
                output.Attributes.SetAttribute("type", TypeAttributeValue);
                output.Attributes.SetAttribute("min", range.Minimum);
                output.Attributes.SetAttribute("max", range.Maximum);

                if (range is RangeWithStepAttribute rws)
                {
                    output.Attributes.SetAttribute("step", rws.Step);
                }
            }
        }
    }
}

All we need to do is register our custom tag helper in the _ViewImports.cshtml. Change the assembly name to match your assembly name.

@addTagHelper *, OutputValues

A note about the Order property on the RangeInputTagHelper and why it’s set to -999. The default InputTagHelper has a value of -1000, meaning it will likely run before all tag helpers you create. Typically, the order doesn’t matter too much, but in this case, we want our tag helper to do as little work as possible, letting the original tag helper do much of the work it typically does. Since HTML inputs share a lot of attributes and behaviors, this is ideal for this scenario. We set our tag helper to -999 to ensure it runs sometime right after the original tag helper.

After rerunning the application, you’ll see a slider with the values for min, max, and step set ready for your users. Awesome!

Conclusion

This technique can work with any HTML5 input you’d like to support that isn’t in ASP.NET Core. It also ensures that all HTML id and name values derive from your C# models and that the HTML and server-side handlers are in sync.

I hope you found this post helpful, and as always, thanks for reading. Cheers.

HTML5 Validation for ASP.NET Core Models and Razor Views

Tue, 25 Jun 2024 00:00:00 +0000

I was recently working on an HTMX and ASP.NET Core demo and wanted to limit client-to-server requests to valid requests. This is a built-in feature for HTMX, as long as you utilize HTML5 validators on your forms and inputs. As many ASP.NET Core practitioners know, the default client-side validation in ASP.NET Core is not HTML5 but a mix of custom data-val attributes and JQuery. The current approach is acceptable, but it makes adopting new frameworks, supporting native HTML capabilities, and dropping extraneous dependencies more difficult.

Could we drop the JQuery validation dependency in favor of HTML5 validation? Luckily, we can thank OSS author Andrew White for his latest NuGet package, FinBuckle.Html5Validation. This package allows us to disable the default behavior of ASP.NET Core MVC and Razor Pages for a more modern approach.

What is HTML5 Validation?

Before HTML5, developers wrote all client-side validation using JavaScript code. While JavaScript code allowed for complex scenarios, many folks realized two things: Client-side validation has many recurring patterns, and, ultimately, it’s not a bullet-proof validation approach. Server-side validation is essential.

This realization helped HTML narrow down the scope of client-side validation, which limits requests sent to the server to client-validated ones. This validation focused on a few user input characteristics:

Required: This field must have some value.
Type: This field conforms to the expected integer, date, phone number, etc.
Constraints: This field has a minimum, maximum, or fits within a specified range.
Pattern: This field conforms to a regular expression pattern

These agreed-upon validations reduced the required JavaScript code while allowing clients to create native experiences based on the input types.

Let’s take a look at an example of an HTML5-validated form. The following code can be seen on the MDN site.

<form>
  <fieldset>
    <legend>
      Do you have a driver's license?<span aria-label="required">*</span>
    </legend>
    <input type="radio" required name="driver" id="r1" value="yes" /><label
      for="r1"
      >Yes</label
    >
    <input type="radio" required name="driver" id="r2" value="no" /><label
      for="r2"
      >No</label
    >
  </fieldset>
  <p>
    <label for="n1">How old are you?</label>    
    <input
      type="number"
      min="12"
      max="120"
      step="1"
      id="n1"
      name="age"
      pattern="\d+" />
  </p>
  <p>
    <label for="t1"
      >What's your favorite fruit?<span aria-label="required">*</span></label
    >
    <input
      type="text"
      id="t1"
      name="fruit"
      list="l1"
      required
      pattern="[Bb]anana|[Cc]herry|[Aa]pple|[Ss]trawberry|[Ll]emon|[Oo]range" />
    <datalist id="l1">
      <option>Banana</option>
      <option>Cherry</option>
      <option>Apple</option>
      <option>Strawberry</option>
      <option>Lemon</option>
      <option>Orange</option>
    </datalist>
  </p>
  <p>
    <label for="t2">What's your email address?</label>
    <input type="email" id="t2" name="email" />
  </p>
  <p>
    <label for="t3">Leave a short message</label>
    <textarea id="t3" name="msg" maxlength="140" rows="5"></textarea>
  </p>
  <p>
    <button>Submit</button>
  </p>
</form>

As you’ll notice, the attributes required, pattern, min, max, and type are all used to create a validation experience with no lines of JavaScript. When attempting to submit the form, you’ll notice the client displays a message. You can also highlight inputs based on their validation status.

Awesome, right?! With a bit of CSS, we can get some UI indicators. Depending on the client, any input with an appropriate type will have automatic access to the native type value picker, whether it’s a date, a phone number, or a number.

OK, now that we understand what HTML5 validation gets us, how do we get that in ASP.NET Core?

Disable Client-side Validation in ASP.NET Core

This section is for folks who’d prefer to keep their models and views completely separate and write the HTML mostly by hand.

To disable the default client-side validation in ASP.NET Core MVC and Razor Pages, you can use the following lines in your Program file.

builder.Services.AddRazorPages()
    .AddViewOptions(options => {
        options.HtmlHelperOptions.ClientValidationEnabled = false;
    });

This will prevent Razor Pages and MVC from generating the data-val attributes commonly found on inputs in the HTML output.

This approach is fine, but I think the next section is a better option for most folks as it still relies on the model metadata that ASP.NET Core provides.

FinBuckle.HTML5Validation NuGet Package

To move towards HTML5 validation, you must first install the FinBuckle.HTML5Validation NuGet package into your ASP.NET Core application.

Important Note: this package only works with MVC and Razor Pages.

<PackageReference Include="Finbuckle.Html5Validation" Version="1.0.1" />

Once added to your dependencies, you must register the package with your application’s services collection.

using Finbuckle.Html5Validation;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHtml5Validation();

Internally, this method provides the ASP.NET Core pipeline with an IValidationAttributeAdapterProvider.

namespace Microsoft.AspNetCore.Mvc.DataAnnotations
{
  public interface IValidationAttributeAdapterProvider
  {
    IAttributeAdapter? GetAttributeAdapter(
      ValidationAttribute attribute,
      IStringLocalizer? stringLocalizer);
  }
}

This adapter gets passed an attribute and a localizer, at which point you can decide what attributes should be added to the HTML input. Let’s see an implementation for the pattern attribute.

// Copyright Finbuckle LLC, Andrew White, and Contributors.
// Refer to the solution LICENSE file for more information.

// Portions of this file are derived from ASP.NET Core and are subject to the following:
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Mvc.DataAnnotations;
using Microsoft.AspNetCore.Mvc.ModelBinding.Validation;
using Microsoft.Extensions.Localization;

namespace Finbuckle.Html5Validation.Internal;

public class RegularExpressionAttributeAdapter : AttributeAdapterBase<RegularExpressionAttribute>
{
    public RegularExpressionAttributeAdapter(RegularExpressionAttribute attribute, IStringLocalizer? stringLocalizer)
        : base(attribute, stringLocalizer)
    {
    }

    public override void AddValidation(ClientModelValidationContext context)
    {
        if (context == null)
        {
            throw new ArgumentNullException(nameof(context));
        }
        
        MergeAttribute(context.Attributes, "pattern", Attribute.Pattern);
    }

    /// <inheritdoc />
    public override string GetErrorMessage(ModelValidationContextBase validationContext)
    {
        if (validationContext == null)
        {
            throw new ArgumentNullException(nameof(validationContext));
        }

        return GetErrorMessage(
            validationContext.ModelMetadata,
            validationContext.ModelMetadata.GetDisplayName(),
            Attribute.Pattern);
    }
}

This is a neat part of the ASP.NET Core MVC and Razor Pages pipeline. It’s extensible to the point where folks can replace validation without changing Razor views. Speaking of Razor views, let’s see how we can use this in one.

First, let’s create a Razor PageModel.

using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;

namespace HtmxFormValidation.Pages;

public class IndexModel(ILogger<IndexModel> logger) : PageModel
{
    [BindProperty, Required]
    public string? Name { get; set; }
    
    [BindProperty, Required]
    public string? Media { get; set; }
    
    [BindProperty, Required]
    public DateTime? Date { get; set; }
    
    public void OnGet()
    {
    }

    public IActionResult OnPost()
    {
        if (ModelState.IsValid)
        {
            logger.LogInformation("{Name} picked {Media}", Name, Media);
        }

        return Partial("_Form", this);
    }
}

I’m using DataAnnotations here; now, what does the view look like? (I’m using HTMX, hence the hx- attributes).

@model IndexModel
@{ string[] options = ["Television", "Radio", "Social Media"]; }

<form method="post" asp-page="Index"
      hx-post="@Url.Page("Index")"
      hx-swap="outerHtml">

    @* alert box *@
    @if (Model.Name is not null)
    {
        <div class="alert alert-info mb-3">
            @Model.Name picked @Model.Media!
        </div>
    }

    <div class="form-group mb-2">
        <label asp-for="Name"></label>
        <input asp-for="Name" type="text"
               class="form-control" 
               title="Must be Khalid or RoboCop">
    </div>

    <div class="form-group mb-2">
        <label asp-for="Date"></label>
        <input asp-for="Date" class="form-control">
    </div>
    
    <!-- radio button list -->
    <div class="mb-3">
        <label>Media Types</label>
        @foreach (var option in options)
        {
            <div class="form-check">
                <input class="form-check-input" type="radio" asp-for="Media" value="@option">
                <label class="form-check-label" asp-for="Media">
                    @option
                </label>
            </div>
        }
    </div>
    <button type="submit" class="btn btn-primary ">
        Submit
    </button>
</form>

Cool! Now we need some CSS to highlight invalid fields with some styling.

input:user-invalid {
  border-color: red;
  background-color: pink;
  box-shadow: 0 0 5px 1px red;
}

You can target several states, such as :valid, :invalid, and :user-invalid. The :user-invalid state only triggers after a user has interacted with an element, whereas you can use the :invalid state to signify a field is invalid immediately.

Let’s run our application and submit the form.

Sweet! All looks like it’s working as expected.

Conclusion

While validation libraries can offer a lot in terms of user experience, the native validation is really good. In fact, it’s good enough to handle most client-side validation and then additionally lean on server-side validation to handle the rest.

I recommend trying this approach and seeing how far you get. You’ll likely be surprised how many dependencies you can drop in favor of native controls and validation.

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

What is HSTS and why is it in my ASP.NET Core app?

Tue, 18 Jun 2024 00:00:00 +0000

When creating a new ASP.NET Core application, you get a set of middleware that performs typical web application duties. Some include serving static assets, routing, HTTPS redirection, and exception handling. Folks looking will also notice a middleware registration of the app.UseHsts() found in every ASP.NET Core app.

What is HSTS, why would you want it, and how do you configure the HSTS options in ASP.NET Core? Let’s find out.

What is HSTS?

HSTS (HTTP Strict Transport Security) is a method by which your application server can tell clients to use a secure connection when sending requests. As you may know, HTTP is unsecured communication, while HTTPS uses encryption to improve users’ privacy and security. Applications can transition user sessions from HTTP and HTTPS, and historically, it was very common to move from an unsecured part of a website to a secured section. For example, shopping sites used to display store items over HTTP and then only use HTTPS for the checkout process.

This still happens in ASP.NET Core today, but typically only on the first request to the application. You may notice this line somewhere in your ASP.NET Core pipeline definition.

app.UseHttpsRedirection();

If a user visits your application using http://, the ASP.NET Core middleware will attempt to rewrite the request to target https://. This is all good and secure, well, except for that first request, and that’s the crucial part. There’s still some unsecured communication occurring, which can be an issue depending on what is included in that initial request.

With HSTS, we want to communicate several aspects to any client accessing our application:

Always communicate using HTTPS, no matter what.
If includeSubdomains is present we also mean all subdomains.
If preload is set, the browser will always make HTTPS requests, even on the first request.
The max-age of the policy, which can be measured in seconds to years.

The preload value is the most interesting, as this is used by browser vendors to create a known list of sites serving only experiences over HTTPS. This allows the browser to switch to HTTPS before the first request. A browser will never communicate with your application over HTTP, even if your server supports it.

While you may be tempted to turn on HSTS and the preload functionality immediately, you must be mindful of what’s expected of your application before deploying this feature.

Serve and maintain a valid certificate
Redirect from HTTP to HTTPS on the same host
Serve all subdomains over HTTPS
Serve an HSTS header with a max-age of 1 year, includeSubdomains, and include the preload key.
Redirect responses must also contain the HSTS header.

`Strict-Transport-Security:` `max-age=63072000; includeSubDomains; preload`

And finally, you can verify that you’ve satisfied all the requirements by going to https://hstspreload.org.

In summary, HSTS allows you to tell browser vendors that you want an added level of security by having all communication occur over encrypted communication and that requests or responses should never be unsecured. In short, enforce HTTPS.

HSTS in ASP.NET Core

Let’s get back to ASP.NET Core. You’ve likely seen this line in your applications but never clicked through the link in the comment.

// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();

Why is the default value 30 days, and why should you consider changing it for production scenarios?

30 days is a nice round number, just long enough to be helpful but not so long that if you make a mistake, it will take forever for browser vendors to resolve. That said, you should change the value for production. The HSTS preload guidance is a gradual smoke test and will likely take a few application deployments to work through.

Start with a low max-age of 5 minutes, test your site, then graduate to 1 week and to 1 month.

max-age=2592000; includeSubDomains

Along the way, test your site for errors or issues related to HTTPS traffic. Standard HTTP to HTTPS issues include static assets and CDN dependencies. When you feel confident you’ve squashed all your issues, you can add the preload value and increase the max-age to 2 years.

You’ll need to configure the HstsOptions object registered in your ASP.NET Core services collection to work up to this.

builder.Services.Configure<HstsOptions>(o =>
{
    o.Preload = true;
    o.MaxAge = new TimeSpan(730 /* 2 years */);
    o.IncludeSubDomains = true;
});

The next time your site is crawled by the major browser providers (Google, Mozilla, or Microsoft), you’ll be added to the preload list hard-coded into browsers.

If you’re running a multi-tenant site and need to exclude different tenants from a particular policy, you can also set the ExcludeHosts property.

builder.Services.Configure<HstsOptions>(o =>
{
    o.Preload = true;
    o.MaxAge = new TimeSpan(730 /* 2 years */);
    o.IncludeSubDomains = true;
    o.ExcludedHosts.Add("example.com");
    o.ExcludedHosts.Add("www.example.com");
});

Just note that if you exclude a subdomain from a top-level domain that opts into HSTS, you can’t get the preload capability since you’ve not satisfied the requirements.

Should I turn on HSTS?

HSTS is an added layer of security that can prevent man-in-the-middle attacks from protocol downgrades and cookie hijacking. That said, ASP.NET Core has mechanisms to secure cookies, such as Data Protection encryption and browser-handling hints such as Secure, HttpOnly, and SameSite. As long as you don’t change those values, you’ll be following best practices. That said, always consult an actual security professional and perform security audits periodically.

HSTS can be annoying if you accidentally enable it in a development environment that may not have a certificate, but in most production environments, you should have a certificate.

In general, yes, you should enable it, but be mindful when and where you enable it, as it can be challenging to get browsers to refresh the policy.

Conclusion

You now know a little bit more about HSTS, why it’s included in your ASP.NET Core application, and how and when to configure it. HSTS is an additional layer of security specifically designed to keep all communication over HTTPS, including those initial requests. That said, you’ll need to put in the work to get that preload functionality and plan for weeks of deployments, testing, and audits to make sure everything is working smoothly.

As always, thanks for reading, and cheers.

References

How To Encrypt ASP.NET Core Route Parameters

Tue, 11 Jun 2024 00:00:00 +0000

I recently read a classic blog post from the RavenDB community recommending developers think twice about exposing primary identifiers in their URLs. There are several reasons for this, which I’ll summarize in this post, but I wanted to revisit the problem and see what the current ASP.NET Core development stack has to offer when it comes to solving this problem.

In this post, we’ll see some code that can both encrypt and decrypt sensitive identifiers in the URL path.

Why Obscure Identifiers?

Many people first think, “Why obscure identifiers in the first place?” I mean, it’s just an ID, right?

There are several arguments as to why it may be a “bad” practice.

1. URL Tampering

While we all do our best to secure our applications, there are times when we may forget to properly verify that a user has permission to access a particular resource.

https://example.com/?id=1

Over the years, we’ve become acutely aware that changing the value of the id in a URL might return a different resource. This may be intended behavior, or it could give “hackers” another avenue to exfiltrate data from your system.

Making identifiers more opaque can eliminate a user experience you never intended to offer.

2. Leaking System Information

Most identifiers can be tied back to their supporting system. For example, integers are widely used in relational databases, while document databases use string identifiers. This extra information may give users more information about your internal system and architectural choices than you intended.

3. Leaking Business Information

This is likely the most important for your business stakeholders. Since most identifiers are incremental, they could accidentally leak your business’s critical metrics to outside parties. You could track the current volume and growth velocity over time of a system type. Some hypothetical entities may include orders, issues, and products.

The reasons given here clearly rely on your context and your application security. So, while you may or may not ultimately decide to obscure identifiers, it’s still important to consider why you’re making that decision.

ASP.NET Core Route Constraints

In this code, we’ll use ASP.NET Core’s route constraints to provide an implicit way of encrypting identifiers in route templates. We’ll also use the DataProtection APIs, so we don’t have to worry about encryption keys and storage for this example. However, you could adapt this code to use any methodology you have in mind.

The first step is to create a new class called EncryptedParameter, and we’ll need to implement the IOutboundParameterTransformer interface.

using Microsoft.AspNetCore.DataProtection;

public class EncryptedParameter(IDataProtectionProvider dpp) : 
    IOutboundParameterTransformer
{
    private readonly IDataProtector protector 
        = dpp.CreateProtector("EncryptedParameter");
    
    public string? TransformOutbound(object? value)
    {
        var result = value?.ToString();
        return string.IsNullOrEmpty(result) 
            ? null 
            : protector.Protect(result);
    }
}

We need to register this code as a route constraint. Add the following code to the Program class of your ASP.NET Core application.

builder.Services.AddDataProtection();
builder.Services.Configure<RouteOptions>(opt =>  {
    opt.ConstraintMap.Add("encrypt", typeof(EncryptedParameter));
});

We have to register the constraint, and since our constraint is using the DataProtection API, we also need to remember to add the data protection services.

We can now use the constraint in our route templates on our target actions. Here’s an example being used in a Razor Page route template.

@page "{id:encrypt}"
@model RavenDbTodoApp.Pages.Agenda

<h1>@Model.Id</h1>

When we use ASP.NET Core’s LinkGenerator, it will use our constraint to process parameters.

<a href="@Url.Page("Agenda", new { id = "agenda/1" })">
    Link To Agenda
</a>

The previous code generates the following HTML link.

<a href="/Agenda/CfDJ8LTlmMRHw3JNmUOvTfhPRjsGI3dXCSP-7yuu-Hu05yjURdIZkalKYJc7-rbJbOXrJCkeLdywxW7m6A7XT3ylMY6ilrNC5DYdssyWTA1-QCHpqFFvRi6LokwktvGkcGs5BA">
    Link To Agenda
</a>

Neat, but as you may have noticed, this is only one part of the equation. Dealing with these identifiers may become cumbersome if we don’t use the ASP.NET Core machinery. Let’s implement the second part.

ASP.NET Core Model Binders

We’ll be using ASP.NET Core’s model binding machinery to transform the incoming parameter into something more usable. Let’s modify our EncryptedParameter class with a new interface, IModelBinder.

using Microsoft.AspNetCore.DataProtection;
using Microsoft.AspNetCore.Mvc.ModelBinding;

public class EncryptedParameter(IDataProtectionProvider dpp) : 
    IModelBinder,
    IOutboundParameterTransformer
{
    private readonly IDataProtector protector 
        = dpp.CreateProtector("EncryptedParameter");
    
    public string? TransformOutbound(object? value)
    {
        var result = value?.ToString();
        return string.IsNullOrEmpty(result) 
            ? null 
            : protector.Protect(result);
    }

    public Task BindModelAsync(ModelBindingContext bindingContext)
    {
        var key = bindingContext.FieldName;
        var valueProviderResult = bindingContext.ValueProvider.GetValue(key);
        
        if (valueProviderResult.FirstValue is { } value)
        {
            var result = protector.Unprotect(value);
            bindingContext.Result = ModelBindingResult.Success(result);
        }

        return Task.CompletedTask;
    }
}

Now, let’s apply this model binder to a parameter on the receiving page.

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

public class Agenda: PageModel
{
    [BindProperty(SupportsGet = true, BinderType = typeof(EncryptedParameter))]
    public string Id { get; set; }
    
    public void OnGet()
    {
        
    }
}

Now, you can access the parameter with its original value, which should make it easier to use against your existing data storage engine of choice.

Some thoughts on this approach

You may want to evaluate a few things when taking this approach and whether it’s worth the tradeoffs.

Encryption and Decryption can be expensive, adding to the overhead of each link generation and request.
Encryption creates some really long strings. I’m not an encryption expert, but there are likely encryption algorithms that produce more compact strings.
A little more noise in code with constraints and attributes.
Easy to miss a constraint or attribute as the system grows.

Conclusion

If you’ve been worried about URL tampering or exposing critical system information, the approach outlined in this post might be useful to you. That said, before slapping this onto your applications, please consider the trade-offs and costs of applying encryption to parameters.

As always, thanks for reading and I hope this article has helped. Cheers

State Machines, Light Switches, and Space Travel with Stateless and .NET 8

Tue, 04 Jun 2024 00:00:00 +0000

State machines are so integral to software development that they often seem invisible to developers. They are used so frequently yet abstracted away through APIs and syntax that many developers don’t directly deal with them. However, we’d like to.

At their core, state machines are systems with finite inputs and deterministic pathways. While they can be complex, the basic structure of nodes and vertices makes them more approachable than they may initially seem.

In this post, I’ll guide you through the process of building two state machines using the .NET library Stateless. We’ll also discuss effective strategies for incorporating state machines into your code.

Getting Started with Stateless

To start using Stateless, you’ll need to install the latest version of the package using NuGet.

dotnet add package Stateless

From here, you will use the StateMachine class to define the state object and the triggers that mutate the machine’s state.

The example used in the Stateless documentation is that of a phone.

var phoneCall = new StateMachine<State, Trigger>(State.OffHook);

phoneCall.Configure(State.OffHook)
    .Permit(Trigger.CallDialled, State.Ringing);

phoneCall.Configure(State.Connected)
    .OnEntry(t => StartCallTimer())
    .OnExit(t => StopCallTimer())
    .InternalTransition(Trigger.MuteMicrophone, t => OnMute())
    .InternalTransition(Trigger.UnmuteMicrophone, t => OnUnmute())
    .InternalTransition<int>(_setVolumeTrigger, (volume, t) => OnSetVolume(volume))
    .Permit(Trigger.LeftMessage, State.OffHook)
    .Permit(Trigger.PlacedOnHold, State.OnHold);

// ...

phoneCall.Fire(Trigger.CallDialled);

You’ll notice that the StateMachine has two generic arguments: one for the state and the other for the trigger. These types can be any .NET type, but they’re enum types in this sample.

Let’s build something closer to how I recommend using Stateless.

The Light Switch State Machine Example

This example shows a Widget class that always has a deterministic state of being On or Off. The trigger for our Widget is to Press. While we could implement the state machine as we did previously, I recommend encapsulating state machines within a class.

public class Widget
{
    private readonly StateMachine<State, Trigger> workflow = new(State.Off);
    public string Name { get; }

    enum State
    {
        On,
        Off
    }
    enum Trigger
    {
        Press
    }

    public Widget(string name)
    {
        Name = name;
        
        workflow.Configure(State.On)
            .Permit(Trigger.Press, State.Off)
            .OnEntry(() => Console.WriteLine($"🟢 {Name} is {workflow.State}"));
        
        workflow.Configure(State.Off)
            .Permit(Trigger.Press, State.On)
            .OnEntry(() => Console.WriteLine($"🔴 {Name} is {workflow.State}"));
    }

    public void Toggle()
    {
        workflow.Fire(Trigger.Press);
    }
}

Why? It’s much easier to consume these class instances and have the machine’s state exposed through properties and interactions to exist as a method call. In the “real world,” we typically don’t understand the internal behavior of the abstractions we interact with; we only observe the outcome of our interactions.

In the case of this implementation, Stateless is managing the state of our Widget, and we know it will be consistent with the behavior we define in the constructor.

var widget = new Widget("Lightbulb 💡");

Console.WriteLine($"Press any key to toggle {widget.Name}");
while (true) {
    _ = Console.ReadKey();
    widget.Toggle();
}

Let’s see it in action!

Press any key to toggle Lightbulb 💡
🟢 Lightbulb 💡 is On
🔴 Lightbulb 💡 is Off
🟢 Lightbulb 💡 is On
🔴 Lightbulb 💡 is Off
🟢 Lightbulb 💡 is On

This is a neat technique, but admittedly simple. Let’s go to space next.

Space Travel with State Machines

A challenging concept when working with state machines is managing the state. Luckily, with Stateless, extracting, storing, and rehydrating state is straightforward.

Let’s create a state machine to travel through our solar system.

public class SpaceTravel
{
    public record Planet(String Name, int DistanceFromSunInMillionsOfMiles)
    {
        public static readonly Planet Sun = new(nameof(Sun), 0);
        public static readonly Planet Mercury = new(nameof(Mercury), 36);
        public static readonly Planet Venus = new(nameof(Venus), 67);
        public static readonly Planet Earth = new(nameof(Earth), 93);
        public static readonly Planet Mars = new(nameof(Mars), 142);
        public static readonly Planet Jupiter = new(nameof(Jupiter), 484);
        public static readonly Planet Saturn = new(nameof(Saturn), 886);
        public static readonly Planet Uranus = new(nameof(Uranus), 1784);
        public static readonly Planet Neptune = new(nameof(Neptune), 2793);
        public static readonly Planet Pluto = new(nameof(Pluto), 3670);
        
        public static readonly List<Planet> All = [
            Sun, Mercury, Venus,
            Earth, Mars, Jupiter,
            Saturn, Uranus, Neptune,
            Pluto
        ];

        public override string ToString()
        {
            return $"{Name}";
        }
    }

    enum Actions
    {
        In,
        Out
    }

    private readonly StateMachine<Planet, Actions> machine;
    
    public SpaceTravel(Planet? start = null)
    {
        start ??= Planet.Earth;

        if (!Planet.All.Contains(start))
        {
            throw new Exception("Starting planet must be in our solar system");
        }

        machine = new(start);
        
        machine.OnTransitionCompleted((transition =>
        {
            var (source, destination, direction) = transition;
            var distance = Math.Abs(source.DistanceFromSunInMillionsOfMiles - destination.DistanceFromSunInMillionsOfMiles);
            var dir = direction == Actions.In ? "⬇" : "⬆";
            Console.WriteLine($"{dir} 🚀 You traveled {distance} million miles from {source.Name} to {destination.Name}.");
        }));
        
        machine.Configure(Planet.Sun).Ignore(Actions.In).Permit(Actions.Out, Planet.Mercury);
        machine.Configure(Planet.Mercury).Permit(Actions.In, Planet.Sun).Permit(Actions.Out, Planet.Venus);
        machine.Configure(Planet.Venus).Permit(Actions.In, Planet.Mercury).Permit(Actions.Out, Planet.Earth);
        machine.Configure(Planet.Earth).Permit(Actions.In, Planet.Venus).Permit(Actions.Out, Planet.Mars);
        machine.Configure(Planet.Mars).Permit(Actions.In, Planet.Earth).Permit(Actions.Out, Planet.Jupiter);
        machine.Configure(Planet.Jupiter).Permit(Actions.In, Planet.Mars).Permit(Actions.Out, Planet.Saturn);
        machine.Configure(Planet.Saturn).Permit(Actions.In, Planet.Jupiter).Permit(Actions.Out, Planet.Uranus);
        machine.Configure(Planet.Uranus).Permit(Actions.In, Planet.Saturn).Permit(Actions.Out, Planet.Neptune);
        machine.Configure(Planet.Neptune).Permit(Actions.In, Planet.Uranus).Permit(Actions.Out, Planet.Pluto);
        machine.Configure(Planet.Pluto).Ignore(Actions.Out).Permit(Actions.In, Planet.Neptune);
    }

    public Planet Current => machine.State;

    public void In()
    {
        machine.Fire(Actions.In);
    }

    public void Out()
    {
        machine.Fire(Actions.Out);
    }
}

internal static class StateMachineExtensions {
    public static void Deconstruct<TState, TTrigger>(this StateMachine<TState, TTrigger>.Transition transition,
        out TState source, out TState destination, out TTrigger direction)
    {
        source = transition.Source;
        destination = transition.Destination;
        direction = transition.Trigger;
    }
}

We’ve done a few things with this state machine that are more complex than our Widget example.

The initial state of our StateMachine can be set at instantiation time through the constructor.
There are two triggers of In and Out, both of which can be fired through matching methods.
The constructor defines how travel can occur from one planet to another, with the Sun and Pluto being re-entry nodes. (You can’t leave the solar system).
Each transition calculates the distance between two bodies, regardless of the state change.

Let’s do some space travel!

var system = new SpaceTravel(SpaceTravel.Planet.Earth);
Console.WriteLine("🔭 Use O(ut) or ⬆ and I(n) and ⬇ keys to move through our solar system.");

while (true)
{
    var key = Console.ReadKey(true);
    switch (key)
    {
        case { Key: ConsoleKey.O or ConsoleKey.UpArrow }:
            system.Out();
            break;
        case { Key: ConsoleKey.I or ConsoleKey.DownArrow }:
            system.In();
            break;
        default:
            var miles = system.Current.DistanceFromSunInMillionsOfMiles;
            Console.WriteLine($"🛰️ Currently at {system.Current.Name} ({miles} million miles from the ☀️).");
            break;
    }
}

Running the application, we get the sample output.

🔭 Use O(ut) or ⬆ and I(n) and ⬇ keys to move through our solar system.
⬆ 🚀 You traveled 49 million miles from Earth to Mars.
⬆ 🚀 You traveled 342 million miles from Mars to Jupiter.
⬆ 🚀 You traveled 402 million miles from Jupiter to Saturn.
⬆ 🚀 You traveled 898 million miles from Saturn to Uranus.
⬆ 🚀 You traveled 1009 million miles from Uranus to Neptune.
⬆ 🚀 You traveled 877 million miles from Neptune to Pluto.
🛰️ Currently at Pluto (3670 million miles from the ☀️).

Neat! What about seeing our travel path?

Graphing your State Machines

At any point in time, you can use the UmlDotGraph static class in the Stateless library to output the graph to a string value.

var graph = UmlDotGraph.Format(workflow.GetInfo());

Our light switch sample produces the following DotGraph that can be turned into an SVG.

digraph {
compound=true;
node [shape=Mrecord]
rankdir="LR"
"On" [label="On|entry / Function"];
"Off" [label="Off|entry / Function"];

"On" -> "Off" [style="solid", label="Press"];
"Off" -> "On" [style="solid", label="Press"];
 init [label="", shape=point];
 init -> "Off"[style = "solid"]
}

These visualizations can be helpful for documentation or diagnosing issues when exceptions occur in the state machine.

Conclusion

Stateless is a very cool library worth checking out. It can add the necessary structure to otherwise complex workflows. I highly recommend encapsulating the StateMachine class within a container class; otherwise, you’ll be dealing with some unwieldy APIs.

A slew of APIs not covered in this post can help you determine if an action can be executed, what next steps are permitted, and error handling for unhandled triggers. It is a well-thought-out library, and I hope you try it.

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

Blazor HTML Forms, Submitting, and Antiforgery Tokens

Tue, 28 May 2024 00:00:00 +0000

I love the web and HTML. It’s certainly come a long way since its inception and what it provides as a core experience for web developers. While folks can certainly build HTML-exclusive experiences, adding forms on a page inevitably leads to introducing a backend tech stack. Recently, I’ve been experimenting with Blazor Server-side Rendering (SSR) and how developers can use its component-driven approach while still building the web experience they know and love.

In this post, we’ll see how to use the plain-old form tag with a Blazor SSR page, handle form posts, and attach antiforgery tokens.

Why not use EditForm?

Anyone familiar with Blazor would likely immediately think, “Why not use the EditForm component?” Well, for my taste, the EditForm component has so many hooks, fields, and requirements that it begins to feel like a burden compared to the humble HTML form. In my opinion, much of the EditForm functionality is overkill for an SSR scenario.

You’re welcome to use EditForm if you find its features useful.

HTML Form Blazor Basics

Blazor is a component-driven framework, and even top-level pages are considered components. In a way, it’s simpler to think of each component as a tree of other components, and you have to start somewhere. This approach means that a component page must handle all incoming requests and “route” those requests to the appropriate handlers.

In a Blazor application, there are two levels of “routing”. The first is what you’d consider traditional HTTP path routing using the @page directive. The second uses the @formname attribute on a form to inject a handler name into forms, in which you can use that additional information for application logic.

Let’s add a basic form to a page and submit it to a Blazor component. THIS WILL NOT WORK

@page "/"

<PageTitle>Home</PageTitle>

<h1>Hello, world!</h1>

@if (Name is { Length: >0 } name)
{
    <h2>@name</h2>
}
else
{
    <h2>Welcome to your new app.</h2>
}

<div class="my-2">
    <hr>
    <form action="" method="post">
        <div class="input-group mb-3">
            <input type="text" class="form-control" 
                   name="name" placeholder="Say your name...">
            <button
                id="button-addon2"
                class="btn btn-outline-secondary"
                type="submit">
                Say Hello
            </button>
        </div>
    </form>
</div>

@code
{
    [SupplyParameterFromForm] public string? Name { get; set; }
}

As soon as we submit the page, we get the following error.

The POST request does not specify which form is being submitted. To fix this, ensure <form> elements have a @formname attribute with any unique value, or pass a FormName parameter if using <EditForm>.

To fix this, we need to add the @formname SSR attribute and give it a unique name within the page scope.

@page "/"

<PageTitle>Home</PageTitle>

<h1>Hello, world!</h1>

@if (Name is { Length: >0} name)
{
    <h2>Hello, @name!</h2>
}
else
{
    <h2>Welcome to your new app.</h2>
}

<div class="my-2">
    <hr>
    <form action="" method="post" @formname="main">
        <div class="input-group mb-3">
            <input type="text" class="form-control" 
                   name="name" placeholder="Say your name...">
            <button
                id="button-addon2"
                class="btn btn-outline-secondary"
                type="submit">
                Say Hello
            </button>
        </div>
    </form>
</div>

@code
{
    [SupplyParameterFromForm] public string? Name { get; set; }
}

We still have an issue as you may notice when you submit this form.

A valid antiforgery token was not provided with the request. Add an antiforgery token, or disable antiforgery validation for this endpoint.

Blazor has an AntiforgeryToken component we forgot to add to the form.

    <form action="" method="post" @formname="main">
        <div class="input-group mb-3">
            <input type="text" class="form-control" 
                   name="name" placeholder="Say your name...">
            <button
                id="button-addon2"
                class="btn btn-outline-secondary"
                type="submit">
                Say Hello
            </button>
        </div>
        <AntiforgeryToken/>
    </form>

Woot! Now it works. If we look at the HTML rendered to the page, you’ll see what Blazor is doing to transform our form into one compatible with the Blazor request pipeline.

<form action="" method="post">
<input type="hidden" name="_handler" value="main"><div class="input-group mb-3"><input type="text" class="form-control" name="name" placeholder="Say your name...">
            <button id="button-addon2" class="btn btn-outline-secondary" type="submit">
                Say Hello
            </button></div>
        <input type="hidden" name="__RequestVerificationToken" value="CfDJ8LTlmMRHw3JNmUOvTfhPRjst1GbXskBXT7OtvUmsHbD9sMekv4N4xfoGi1hZlx-XqE_xVTjkPJ2U2T_ZN02Z92RfdhmdofvYJYlPn4QwD_Pno-HJ_z6JkjMTtgOcTkO3q72vEYX_Hl9MaHvju50tTz8"></form>

The hidden inputs are notable, as they provide values for _handler and our antiforgery token.

Being Extra with @onsubmit

I hinted at this in the previous section, but Blazor is processing the “HTML” in our components to inject and add input elements that we didn’t specify. We can take advantage of another attribute, @onsubmit, to ensure that all submissions are handled by the appropriate handler on the page.

@page "/"

<PageTitle>Home</PageTitle>

<h1>Hello, world!</h1>

@if (Message is not null)
{
    <h2>@Message</h2>
}
else
{
    <h2>Welcome to your new app.</h2>
}

<div class="my-2">
    <hr>
    <form action="" method="post" @formname="main" @onsubmit="Submit">
        <div class="input-group mb-3">
            <input type="text" class="form-control" 
                   name="name" placeholder="Say your name...">
            <button
                id="button-addon2"
                class="btn btn-outline-secondary"
                type="submit">
                Say Hello
            </button>
        </div>
        <AntiforgeryToken/>
    </form>
</div>

@code
{
    [SupplyParameterFromForm(FormName = "main")] public string? Name { get; set; }
    string? Message { get; set; }

    void Submit()
    {
        if (!string.IsNullOrWhiteSpace(Name))
        {
            Message = $"Hello, {Name} to your Blazor App!";
        }
    }
}

You’ll notice a few new elements in the previous code examples.

Our form now has an @onsubmit attribute. This allows Blazor to execute the method at the time of a request according to the _handler value passed on a submit.
The SupplyParameterFromForm now has a FormName property to match our form name. This is optional and only necessary when dealing with multiple forms on a single page.
We have a Submit method with a bit more complex logic for our component.

Cool! We have a functioning form on a Blazor SSR page and haven’t sacrificed security or HTML readability. We also now understand how to add additional forms and handlers as we expand the page’s functionality.

Conclusion

HTML is great, and using it with ASP.NET Core is pretty great as well. Having Blazor SSR support makes it easy to write performant server-rendered pages while still maintaining a component-driven approach that so many folks like. I hope you found this article helpful. Cheers.

Fix Missing OpenAPI Elements From ASP.NET Core Minimal API Apps

Tue, 21 May 2024 00:00:00 +0000

When working in .NET, there’s a lot of room for reorganizing a codebase, but sometimes we can organize ourselves into a mess of a problem. Recently, when working on an ASP.NET Core Minimal API demo, I seemingly broke an endpoint’s OpenAPI definition, and it was no longer in the list of endpoints.

In this short post, we’ll compare two endpoints and discuss why one is different than the other, why it might break OpenAPI integrations, and how to fix it.

Let’s start with a typical Minimal API endpoint.

app.MapGet("/hello", () =>
    {
        return new Hello("World");
    })
    .WithName("Hello")
    .WithOpenApi();
    
record Hello(string Target);

Our endpoint registration contains enough metadata to determine the parameters, the return type and its structure, and the name of our endpoint. Great! That’s more than enough for ASP.NET Core to generate an OpenAPI definition entry.

Let’s do some refactoring of our handler to a local function.

Task<Hello> Handler()
{
    return Task.FromResult(new Hello("World"));
}

app.MapGet("/hello", Handler)
    .WithName("Hello")
    .WithOpenApi();

record Hello(string Target);

So far, so good! Everything still functions as expected. Now, let’s add a similar endpoint, but we’ll define an HttpContext parameter on our endpoint.

Task<Hello> HandlerWithContext(HttpContext ctx)
{
    return Task.FromResult(new Hello("World"));
}

app.MapGet("/goodbye", HandlerWithContext)
    .WithName("Goodbye")
    .WithOpenApi();

What?! Our OpenAPI endpoint is no longer being generated and is appearing on our definitions page. What happened?!

If we look at the warning generated by code analysis, we’ll see the culprit.

ASP0016: The method used to create a RequestDelegate returns Task<Hello>. RequestDelegate discards this value. If this isn’t intended then change the return type to non-generic Task or, if the delegate is a route handler, cast it to Delegate so the return value is written to the response.

Ah! We accidentally turned a method into RequestDelegate and stripped all the metadata necessary to build our OpenAPI definition. We can fix that by casting our registration to a delegate.

Task<Hello> HandlerWithContext(HttpContext ctx)
{
    return Task.FromResult(new Hello("World"));
}

app.MapGet("/goodbye", (Delegate)HandlerWithContext)
    .WithName("Goodbye")
    .WithOpenApi();

All is good in the world again.

Conclusion

Remember that while code can look very similar syntactically, you may inadvertently strip enough semantics to break ASP.NET Core’s OpenAPI integration when refactoring your Minimal API endpoints.

I hope you found this post helpful. Cheers.

ASP.NET Core, SSR Web Components, and Enhance Wasm

Tue, 14 May 2024 00:00:00 +0000

Web components are some of the most exciting technology I’ve seen in a long time. They promise to revolutionize how we write, maintain, and ship HTML-based applications. With web components, you can extend the set of HTML tags specific to your site while still providing the functionality you intended with less markup.

And then there’s Web Assembly, or Wasm for short, a technology that opens up a world of possibilities. It enables all ecosystems to package functionality in a reusable format that can be deployed across a wide range of platforms.

Could we combine them to provide ASP.NET Core with brand-new server-side rendering functionality while avoiding the client-side costs of web components as they attach to the DOM? Sure we can! With Enhance Wasm.

What is Enhance WASM?

Enhance WASM is an open-source initiative to bring the features of Enhance, a dynamic web apps framework, to the server for all technology stacks through Wasm. As mentioned in the opening, web components are significant but take some time to attach to an active web page. This can be less than ideal. If we can render some of the web component’s HTML in advance, we can provide users with a better and faster experience while the page catches up.

Web components are a standard way of building components for HTML apps without libraries like React, Angular, Vue, or Svelte. They are also very lightweight, typically not needing much, if any, build steps. The Enhance project has guiding tenants that make it appealing for folks suffering from SPA fatigue:

Author and deliver HTML Pages
Use Web Standards
Progressively enhance working HTML

ASP.NET Core and Razor are perfect fits for this philosophy as they are mature and reliable technologies. Let’s see how to get these technologies working together.

Getting Started

You’ll first need to download the latest version of Enhance WASM from its GitHub page. Then, place the enhance-ssr.wasm file as Content in an ASP.NET Core application and set it to always copy to your build output directory.

Next, install the following packages.

<ItemGroup>
  <PackageReference Include="Extism.runtime.all" Version="1.2.0" />
  <PackageReference Include="Extism.Sdk" Version="1.2.0" />
</ItemGroup>

The SDK package is a wrapper for the runtime packages. Both are required to make the following code work.

Now we’re ready to write a wrapper for Enhance Wasm.

Running Enhance WASM in .NET

This part is pretty straightforward. We need to load the enhance-ssr.wasm file into memory, then load it as an Extism plugin.

using System.Text.Encodings.Web;
using System.Text.Json;
using System.Text.Json.Serialization;
using Extism.Sdk;

namespace EnhanceWebComponents.Services;

public class EnhanceServerSideRenderer(Dictionary<string, string> webComponentElements)
{
    private static readonly byte[] Wasm =
        File.ReadAllBytes("enhance-ssr.wasm");

    private readonly Plugin plugin = new(Wasm, [], withWasi: true);

    private static readonly JsonSerializerOptions Options = new()
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
        DictionaryKeyPolicy = JsonNamingPolicy.CamelCase,
        Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
    };

    public EnhanceResult Process(EnhanceInput input)
    {
        var value = new EnhanceInputWithComponents(input.Markup, webComponentElements, input.InitialState);
        var json = JsonSerializer.Serialize(value, Options);
        var result = plugin.Call("ssr", json);
        
        return result is null
            ? throw new Exception("unable to process web component")
            : JsonSerializer.Deserialize<EnhanceResult>(result, Options)!;
    }
}

public record EnhanceInput(
    string Markup,
    object? InitialState = null
);

internal record EnhanceInputWithComponents(
    string Markup,
    Dictionary<string, string> Elements,
    object? InitialState
);

public record EnhanceResult(
    string Document,
    string Body,
    string Styles
);

Now, we can call this code with web component definitions and elements to process.

using EnhanceWebComponents.Services;
using Xunit.Abstractions;

namespace EnhanceWebComponents.Tests;

public class EnhanceServerSideRendererTests(ITestOutputHelper output)
{
    private EnhanceServerSideRenderer sut = new(
        webComponentElements: new()
        {
            {
                "my-header",
                // lang=javascript
                """
                function MyHeader({ html }) 
                {
                    return html`<style>h1{color:red;}</style><h1><slot></slot></h1>` 
                }
                """
            },
            {
                "my-component-state",
                // lang=javascript
                """
                function MyComponentState({ html, state }) {
                  const { store } = state
                  return html`<span>${ store?.name }</span>`
                }
                """
            }
        }
    );

    [Fact]
    public void Can_process_web_component()
    {
        var input = new EnhanceInput(
            "<my-header>Hello World</my-header>"
        );

        var result = sut.Process(input);
        
        output.WriteLine(result.Body);

        Assert.NotNull(result);
        Assert.Equal("""<my-header enhanced="✨"><h1>Hello World</h1></my-header>""", result.Body);
        Assert.Equal("my-header h1 {\n  color: red;\n}", result.Styles);
    }
    
    [Fact]
    public void Can_process_web_component_with_state()
    {
        var input = new EnhanceInput(
            "<my-component-state></my-component-state>",
            // accessed via state.store.name in JavaScript
            new { name = "Khalid" }
        );

        var result = sut.Process(input);
        
        output.WriteLine(result.Body);

        Assert.NotNull(result);
        Assert.Equal("""<my-component-state enhanced="✨"><span>Khalid</span></my-component-state>""", result.Body);
    }
}

Wooooooooah! It works! Well, it’s nice but it could be nicer. Let’s make a tag helper for ASP.NET Core.

ASP.NET Core Enhance Wasm Tag Helper

ASP.NET Core has tag helpers that should make this even more awesome, so let’s do that!

We’ll create two classes: EnhanceTagHelper and EnhanceRequestContext.

using System.Text;
using System.Text.Encodings.Web;
using Microsoft.AspNetCore.Razor.TagHelpers;

namespace EnhanceWebComponents.Services;

[HtmlTargetElement(Attributes = EnhanceSsrAttribute)]
public class EnhanceTagHelper(EnhanceServerSideRenderer enhanceServerSideRenderer, EnhanceRequestContext enhanceCtx) : TagHelper
{
    private const string EnhanceSsrAttribute = "enhance-ssr"; 
    public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
    {
        output.Attributes.Clear();
        foreach (var attribute in context.AllAttributes)
        {
            if (attribute.Name == "enhance-ssr")
                continue;
            
            output.Attributes.Add(attribute);
        }
        output.Content = await output.GetChildContentAsync();

        var sb = new StringBuilder();
        await using var stringWriter = new StringWriter(sb);
        output.WriteTo(stringWriter, HtmlEncoder.Default);

        var input = new EnhanceInput(sb.ToString());
        
        var result = enhanceServerSideRenderer.Process(input);
        // remove outer-wrapper
        output.TagName = "";
        output.Content.SetHtmlContent(result.Body);
        
        // any scoped css goes into the current context
        enhanceCtx.Add(result);
    }
}

You notice the type EnhanceRequestContext; this request-scoped instance allows us to push processed CSS into memory while all the components are being processed.

using System.Collections.Concurrent;
using System.Text;
using Microsoft.AspNetCore.Html;

namespace EnhanceWebComponents.Services;

public class EnhanceRequestContext
{
    private ConcurrentBag<EnhanceResult> Results { get; }
        = new();

    public void Add(EnhanceResult result) =>
        Results.Add(result);
    
    public IHtmlContent Styles()
    {
        return new HtmlString(
            // lang=html
            $"""
             <style enhanced="✨">
                {GetAllStyles()}
             </style>
             """
        );
    }
    
    private string GetAllStyles()
    {
        var sb = new StringBuilder();
        // we only want the unique styles
        foreach (var result in Results.DistinctBy(x => x.Styles)) 
            sb.AppendLine(result.Styles);
        return sb.ToString();
    }
}

Let’s register these types in Program.cs in our services collection.

builder.Services.AddSingleton(new EnhanceServerSideRenderer(
    // Note: pull these definitions from somewhere else.
    // you could probably read these from a folder in `wwwroot/js` 
    // and register them by convention `name of file` and `contents`.
    webComponentElements: new()
    {
        {
            "my-header",
            // lang=javascript
            """
            function MyHeader({ html }) 
            {
                return html`<style>h1{color:purple;}</style><h1><slot></slot></h1>` 
            }
            """
        }
    }
));

// a "per request" entity to store results so you 
// can then spit out the scoped CSS styles where you need them
builder.Services.AddScoped<EnhanceRequestContext>();

We must also inform Razor about our new tag helper in _ViewImports.cshtml.

@using EnhanceWebComponents
@namespace EnhanceWebComponents.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, EnhanceWebComponents

We also update our _Layout.cshtml file to use the EnhanceRequestContext to render the CSS. Since the _Layout.cshtml is processed last, we know all web components will have already been processed in our views.

@using EnhanceWebComponents.Services
@inject EnhanceRequestContext Enhance

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>@ViewData["Title"] - EnhanceWebComponents</title>
    <link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.min.css"/>
    <link rel="stylesheet" href="~/css/site.css" asp-append-version="true"/>
    <link rel="stylesheet" href="~/EnhanceWebComponents.styles.css" asp-append-version="true"/>
    @Enhance.Styles()
</head>

Note: if you want to process web components in the _Layout.cshtml file, they will work, but you need to get any scoped CSS into the collection. This can be done using middleware or some other pre-layout processing. This is an edge case, and I thought it was overkill for a proof of concept.

Finally, we can use the tag helper and our server-side rendered web components in any Razor view.

@page
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

<div class="text-center">
    <my-header class="display-4" enhance-ssr>Hello World</my-header>
    <my-header class="display-3" enhance-ssr>Hello Again</my-header>
    <p>Learn about <a href="https://learn.microsoft.com/aspnet/core">
        building Web apps with ASP.NET Core
    </a>.</p>
</div>

With the resulting HTML being what we expected.

<div class="text-center">
    <my-header class="display-4" enhanced="✨"><h1>Hello World</h1></my-header>
    <my-header class="display-3" enhanced="✨"><h1>Hello Again</h1></my-header>
    <p>Learn about <a href="https://learn.microsoft.com/aspnet/core">
        building Web apps with ASP.NET Core
    </a>.</p>
</div>

along with the aggregated style element.

<style enhanced="✨">
my-header h1 {
  color: purple;
}
</style>

Awesome!

Conclusion

If you’re interested in trying this, I’ve made the * *code available on GitHub**. I haven’t thought out some edge cases, like the _Layout.cshtml processing, and what to do with attributes in Razor vs. the ones on web components. That said, there’s a lot of potential here for providing an experience never before seen for ASP.NET Core developers.

Thanks for reading and sharing this post with friends and colleagues. Cheers.

How to add HTTP headers to Blazor Components with RazorComponentResult

Tue, 07 May 2024 00:00:00 +0000

In a previous post, ]I wrote about using RazorComponentResult to render Blazor components](/how-to-use-blazor-server-rendered-components-with-htmx) from ASP.NET Core Minimal APIs. The ability allows developers to reuse Blazor components in new and exciting scenarios, specifically with JavaScript UI frameworks and libraries such as React, Vue, Angular, and my favorite library, HTMX.

In this concise post, we’ll explore setting HTTP Headers for RazorComponentResult and creating an extension method that simplifies this task, making your development process more efficient.

RazorComponentResult Recap

Blazor is a component-driven development framework inspired by the JavaScript React library. Components aim to encapsulate UI elements into reusable elements to help accelerate development. They can vary in size, from buttons, links, and textboxes to logical components such as detail cards, tables, video elements, and so on.

Component trees also help manage a page’s state, and Blazor provides some DOM diffing capabilities similar to React. The aim is to make pages more responsive and performant to user interactions without unnecessary DOM swaps. This feature expects components to be nested in other components until you reach the parent component, typically a page. But what about using Blazor for HTML fragments?

RazorComponentResult allows ASP.NET Core endpoints to generate HTML server-side from Blazor components. This can help build HTML APIs for other JavaScript frameworks or vanilla JavaScript calls from your client UI. Let’s see what it looks like.

app.MapGet("/vanilla",
    () => new RazorComponentResult<LoveHtmx>(new
    {
        Message = "I ❤️ ASP.NET Core"
    }));

The corresponding component of LoveHtmx is what you’d expect a Blazor component to look like.

<div class="alert alert-info">
    <span class="text-lg-center">
        @Message
    </span>
</div>

@code{
    [Parameter]
    public string? Message { get; set; } = "I ❤️ HTMX";
}

Cool! Now that we’re all caught back up, how do we set these HTTP headers?

HttpContext and Server-Side Blazor Components

RazorComponentResult generates the HTML that would accompany a Blazor component. While it’s essential to recognize this approach’s limitations, those limitations allow us to make some advantageous assumptions.

Blazor Components must be completely rendered on the server, with no interactivity. I’m sorry, but you’re not getting SignalR or Wasm here.
RazorComponentResult manages the entire Response lifecycle.
You need to specify the state of the component at render time.
You get access to all the server goodies, like HttpContext.

OK, let’s first do the wrong thing. This does not work ❌.

app.MapGet("/vanilla",
    (HttpContext ctx) =>
    {
        ctx.Response.Headers.Append("Nope", "Fail");
        
        return new RazorComponentResult<LoveHtmx>(new
        {
            Message = "I ❤️ ASP.NET Core"
        });
    });

This will fail if you try to set HTTP headers from your ASP.NET Core Minimal API endpoint. Remember, the RazorComponentResult manages the entire Response state. How do we get what we want?

First, we must add an IHttpContextAccessor to our services collection in our Program file.

builder.Services.AddHttpContextAccessor();

Now, let’s get to the component. We need to set headers in the component using the HttpContextinstance, which we’ll get from an IHttpContextAccessor. We can inject the instance using the InjectAttribute or the @inject declaration.


<div class="alert alert-info">
    <span class="text-lg-center">
        @Message
    </span>
</div>

@code{
    [Parameter] public string? Message { get; set; } = "I ❤️ HTMX";

    [Parameter]
    public IHeaderDictionary? Headers { get; set; }
        = new HeaderDictionary();

    [Inject] public IHttpContextAccessor? HttpContextAccessor { get; set; }

    protected override Task OnInitializedAsync()
    {
        if (HttpContextAccessor?.HttpContext is { } ctx &&
            Headers is not null)
        {
            foreach (var (key, value) in Headers)
            {
                ctx.Response.Headers.Append(key, value);
            }
        }

        return base.OnInitializedAsync();
    }
}

Or you might prefer this approach.

@inject IHttpContextAccessor HttpContextAccessor

<div class="alert alert-info">
    <span class="text-lg-center">
        @Message
    </span>
</div>

@code{
    [Parameter] public string? Message { get; set; } = "I ❤️ HTMX";

    [Parameter]
    public IHeaderDictionary? Headers { get; set; }
        = new HeaderDictionary();

    protected override Task OnInitializedAsync()
    {
        if (HttpContextAccessor?.HttpContext is { } ctx &&
            Headers is not null)
        {
            foreach (var (key, value) in Headers)
            {
                ctx.Response.Headers.Append(key, value);
            }
        }

        return base.OnInitializedAsync();
    }

}

This component will only work as a server-rendered component since HttpContext is a dependency.

We can now also write an excellent extension method to keep us from making previous mistakes in the future.

public static class RazorComponentResultExtensions
{
    public static RouteHandlerBuilder MapGetRazorComponent<TComponent>(
        this IEndpointRouteBuilder endpoints,
        [StringSyntax("Route")] string pattern,
        object? state = null
    )
        where TComponent : IComponent
    {
        var dictionary = new RouteValueDictionary(state);
        return endpoints.MapGet(pattern, () => new RazorComponentResult<TComponent>(dictionary));
    }
}

And our new registration now looks like this.

app.MapGetRazorComponent<LoveHtmxWithHeader>(
    "/love-htmx",
    new
    {
        Message = "I ❤️ ASP.NET Core",
        Headers = new HeaderDictionary
        {
            { "Hx-Trigger", "blazor-x" }
        }
    });

Conclusion

There you have it. You can now set HTTP headers when using RazorComponentResult. Using the extension method I provided also makes it clear not to add any additional code in your endpoints, helping you avoid the chance of introducing bugs. Give it a shot!

As always, thanks for reading and sharing my posts with friends and colleagues. As always, cheers.

Working with Rust Libraries from C# .NET Applications

Tue, 30 Apr 2024 00:00:00 +0000

I’ve been on a Rust learning journey lately, and it’s had me thinking about how I can consume Rust libraries from existing .NET applications. The .NET team has done much work regarding interoperability during the .NET 6 to .NET 8 era, and .NET 9 seems poised to continue that trend.

In this post, we’ll create a Rust library and consume it from a .NET application. This post assumes you have installed the .NET SDK and Rust SDK (cargo).

A Simple Rust Library

After creating a .NET Solution, I first created a new Rust library using cargo. The command is relatively straightforward.

cargo init --lib calculator

This creates a new calculator library folder with the most critical files: Cargo.toml and lib.rs. Let’s update the Cargo.toml file to produce an artifact that our .NET application can consume, a dynamic library.

[package]
name = "calculator"
version = "0.1.0"
edition = "2021"

[lib]
name="calculator"
crate-type=["dylib"]

[dependencies]
rand = "0.8.5"

I’ve also included the rand dependency for my Rust code later. Running the cargo b command will now produce a library we can copy into our .NET application.

Let’s write some Rust code we’ll consume from our .NET application later.

use rand::prelude::*;
use std::ffi::{c_char, CStr};

#[repr(C)]
#[derive(Debug)]
pub struct Point {
    pub x: u32,
    pub y: u32,
}

#[no_mangle]
pub extern "C" fn add(left: usize, right: usize) -> usize {
    left + right
}

#[no_mangle]
pub extern "C" fn say_hello(name: *const c_char) {
    let c_str = unsafe { CStr::from_ptr(name) };
    println!("Hello, {}", c_str.to_str().unwrap())
}

#[no_mangle]
pub extern "C" fn random_point() -> Point {
    let mut rng = rand::thread_rng();
    Point {
        x: rng.gen::<u32>(),
        y: rng.gen::<u32>(),
    }
}

#[no_mangle]
pub extern "C" fn distance(first: &Point, second: &Point) -> f64 {
    let dx: f64 = (second.x - first.x).into();
    let dy: f64 = (second.y - first.y).into();

    println!("calculating distance...");

    (dx.powf(2.0) + dy.powf(2.0)).sqrt()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }

    #[test]
    fn say_hello_test() {
        let _result = say_hello("Khalid".as_ptr() as *const i8);

        assert!(true)
    }

    #[test]
    fn get_random_point() {
        let point: Point = random_point();
        println!("{:?}", point);
        assert!(true);
    }

    #[test]
    fn can_calculate_distance() {
        let one = Point { x: 1, y: 1 };
        let two = Point { x: 2, y: 2 };

        let result = distance(&one, &two);
        println!("distance between {:?} and {:?} is {}", one, two, result);
        assert!((result - 1.414).abs() < 0.001)
    }
}

Notable elements of this Rust code include the following.

The extern keyword adds to the list of functions and types in the foreign functions interfaces (FFI).
no_mangle tells the Rust compiler not to mangle the function’s name so that it can be referenced externally by a .NET application or similar external consumer.
The "C" value after extern tells the Rust compiler to compile to something C-compatible. There are other options here as well.
The repr attribute on Point states that this structure should be stored in memory in a C-compatible way.
All functions should use references to elements, which allows us to marshal information from one technology stack to another with little to no overhead. You need to be careful not to introduce memory leaks here, hence the use of unsafe.

Now let’s modify our .NET application for some Rust fun.

Building Rust from a .NET Project

I’ve used this trick several times across tools, and it works like a charm here with Rust. You can use the MSBuild task of Exec to execute commands.

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

  <PropertyGroup>
    <LangVersion>preview</LangVersion>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
  </PropertyGroup>

  <Target Name="Rust Build " BeforeTargets="Compile">
    <Exec Command="echo 'Configuration: $(Configuration)'"/>
    <Exec Condition="'$(Configuration)' == 'Release'" Command="cargo b --release" WorkingDirectory="./../calculator"/>
    <Exec Condition="'$(Configuration)' != 'Release'" Command="cargo b" WorkingDirectory="./../calculator"/>
  </Target>

  <ItemGroup>
    <PackageReference Include="Spectre.Console" Version="0.48.1-preview.0.38"/>
    <Content Include="../calculator/target/$(Configuration)/libcalculator.dylib">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </Content>
  </ItemGroup>


</Project>

You’ll also need to set the AllowUnsafeBlocks element to true, or you won’t be able to access any library. Every time we compile, we’ll build our Rust library and copy it to the project root. From there, we’ll copy the library to our output directory for each build. Depending on your project, feel free to change when the Rust build occurs.

Let’s write some C# code.

Calling Rust from C#

Now, it’s just a matter of giving our C# code something to call. We can do this using .NET’s LibraryImportAttribute.

public partial class Rust
{
    [LibraryImport("libcalculator", EntryPoint = "add")]
    public static partial int Add(int left, int right);

    [LibraryImport("libcalculator", EntryPoint = "say_hello"
        , StringMarshalling = StringMarshalling.Utf8)]
    public static partial void SayHello(string name);

    [LibraryImport("libcalculator", EntryPoint = "random_point")]
    public static partial Point GetRandomPoint();

    [LibraryImport("libcalculator", EntryPoint = "distance")]
    public static partial double Distance(ref Point one, ref Point two);
}

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
[DebuggerDisplay("({X}, {Y})")]
public struct Point
{
    public UInt32 X;
    public UInt32 Y;
    public override string ToString()
        => $"(x: {X}, y: {Y})";
}

Your interface must match the expectations set by the Rust library. Things like structures, types, and references must match, or you’ll likely get an error code of 139, and the executing application will halt.

using System.Diagnostics;
using System.Runtime.InteropServices;
using Spectre.Console;

var one = new Point { X = 1, Y = 1 };
var two = new Point { X = 2, Y = 2 };

var distance = Rust.Distance(ref one, ref two);
AnsiConsole.MarkupLine($"Distance between [yellow]{one}[/] and [red]{two}[/] is [green]{distance}[/]");

var (left, right) = (2, 2);
var result = Rust.Add(left, right);

AnsiConsole.MarkupLine($"[yellow]{left} + {right}[/] = [green]{result}![/]");
Rust.SayHello("Khalid");
AnsiConsole.MarkupInterpolated($"[red]{Rust.GetRandomPoint()}[/]");

public partial class Rust
{
    [LibraryImport("libcalculator", EntryPoint = "add")]
    public static partial int Add(int left, int right);

    [LibraryImport("libcalculator", EntryPoint = "say_hello"
        , StringMarshalling = StringMarshalling.Utf8)]
    public static partial void SayHello(string name);

    [LibraryImport("libcalculator", EntryPoint = "random_point")]
    public static partial Point GetRandomPoint();

    [LibraryImport("libcalculator", EntryPoint = "distance")]
    public static partial double Distance(ref Point one, ref Point two);
}

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
[DebuggerDisplay("({X}, {Y})")]
public struct Point
{
    public UInt32 X;
    public UInt32 Y;
    public override string ToString()
        => $"(x: {X}, y: {Y})";
}

LibraryImport works with the DllImportAttribute and is a source generator that correctly handles common memory management issues with marshaling types like string or reference types. You should use LibraryImport instead of writing the DllImport code yourself.

The results are as you’d expect.

calculating distance...
Distance between (x: 1, y: 1) and (x: 2, y: 2) is 1.4142135623730951
2 + 2 = 4!
Hello, Khalid
(x: 2497287370, y: 698299366)

There you have it. We could call Rust code from a .NET Application with different levels of complexity. That’s pretty cool!

Conclusion

I want to thank Jeremy Mill, who wrote a blog post 2017 that helped me learn and experiment with this sample. I hope you found this post helpful, and be sure to share it with friends and colleagues. As always, thanks and cheers.

Fix Unable To Resolve DbContextOptions For EF Core

Tue, 23 Apr 2024 00:00:00 +0000

I recently hosted a live stream with badass-as-a-service Chris Klug, titled “Stop using Entity Framework Core as a DTO Provider!”. It’s worth a watch, and it gave me, a long-time Entity Framework user, a lot to think about and reevaluate in my workflows. That said, regardless of whether you agree with Chris’ style, he showed a masterclass of tool usage and an understanding that’s easy to admire. In our live stream, one new trick (to me, at least) stood out as something every Entity Framework Core user should know about.

In this post, we’ll explore one strategy to appease the dotnet ef CLI tools regarding design-time configuration and how it opens up a world of possibilities when dealing with database migrations.

Dependencies and ceremony

Entity Framework Core is heavily built around conventions and flexibility. It’s a multi-provider object-relational mapper (ORM), so it needs to operate under many unknown factors, with you, the developer, filling in the gaps. What database are you using? How many databases are you targeting? What migration strategies are you applying? The flexibility is excellent for solving complex problems but also leads developers into the woods of opaque exceptions.

One such problem you’ve likely encountered is the following error output when using the dotnet ef migrations add command.

Unable to create a 'DbContext' of type ''. The exception 
'Unable to resolve service for type 
'Microsoft.EntityFrameworkCore.DbContextOptions`1[MigrationLibrary.Database]'
while attempting to activate 'MigrationLibrary.Database'.

The DbContextOptions class is used to configure a DbContext.

using Microsoft.EntityFrameworkCore;

namespace MigrationLibrary;

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

public class Person
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public int Age { get; set; }
}

Everything looks good, but we need to see the OnConfiguring implementation here, which adds the necessary answers to which database we hope to use. Let’s tweak the code to solve this issue.

using Microsoft.EntityFrameworkCore;

namespace MigrationLibrary;

public class Database() : DbContext 
{
    public DbSet<Person> People => Set<Person>();

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.UseSqlite();
    }
}

public class Person
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public int Age { get; set; }
}

The error is gone now, but we’ve locked into options we can no longer configure outside the Database class. We want something else.

We still want to be able to pass in a DbContextOptions instance. This allows us to configure the DbContext to point to different database implementations and connection strings and alter logging options. We want all that, trust me.

Let’s use a little-known feature to fix this: IDesignTimeDbContextFactory.

IDesignTimeDbContextFactory to the rescue

The IDesignTimeDbContextFactory is a tool that can change how you write migrations, and I don’t say this lightly. Let’s look at the documentation.

A factory for creating derived DbContext instances. 
Implement this interface to enable design-time services 
for context types that do not have a public default constructor.
At design-time, derived DbContext instances can be created 
in order to enable specific design-time experiences such 
as Migrations.
 
Design-time services will automatically discover 
implementations of this interface that are in the 
startup assembly or the same assembly as the derived context.

Hmmm, nice. So what does that look like in C#?

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

namespace MigrationLibrary.Configuration;

// ReSharper disable once UnusedType.Global
public class DatabaseDesignTimeDbContextFactory 
    : IDesignTimeDbContextFactory<Database>
{
    public Database CreateDbContext(string[] args)
    {
        var builder = new DbContextOptionsBuilder<Database>();
        builder.UseSqlite();
        return new Database(builder.Options);
    }
}

Adding this class definition to your project lets Entity Framework’s design-time services answer some of the questions needed to generate migrations and other configuration options.

Running the dotnet ef migrations add command now results in the following output.

(base) ~/RiderProjects/MigrationLibrary
dotnet ef migrations add --project MigrationLibrary AddPerson
Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'

Now, you can define all your migrations and the database configuration in one project while still allowing consuming projects to modify and change options within reason (i.e., you can’t apply SQLite migrations to a SQL Server database).

Conclusion

I love doing live streams because I get to learn from some of the best .NET professionals in the industry, and Chris Klug didn’t disappoint. Again, I highly recommend you watch the stream. This tip, amongst others, is sprinkled throughout the presentation. As always, thanks for reading and sharing these posts with friends and colleagues. Cheers.

Event Queues and Buffering Functions with JavaScript

Tue, 16 Apr 2024 00:00:00 +0000

I was testing JetBrains’ latest Full Line Code Completion plugin in WebStorm by writing a quick JavaScript demo, and by the end, I was pretty happy with what I had built. The JavaScript uses a queue that pushes events to change classes on buttons in 250ms intervals to create a smooth color transition from one style to another.

Is it practical? I don’t know, but it sure is fun. I’ve included all the demo’s contents in a single file so you can test it locally. By the end of this post, you’ll have seen an event queue and how to use it in your JavaScript.

Write a JavaScript Event Queue

The premise of my event queue is straightforward. Push events into a queue and have them execute on a set universal interval. I also wanted the ability to clear the queue of any remaining events.

class EventQueue {
    constructor(interval) {
        this.queue = [];
        this.interval = interval;
        this.startProcessing();
    }

    enqueue(eventFunction) {
        this.queue.push(eventFunction);
    }

    clear() {
        this.queue = [];
    }

    startProcessing() {
        setInterval(() => {
            if (this.queue.length > 0) {
                const eventFunction = this.queue.shift();
                eventFunction();
            }
        }, this.interval);
    }
}

We use the setInterval function to check the queue at our designated interval to process any remaining events. Let’s start using it.

Transitioning Button Colors on Mouse Move

Before we write some more JavaScript, let’s look at the HTML elements we’ll change. Note that I’m using the Bulma CSS library and its button styling classes.

<div class="columns">
    <div class="column">
        <button class="m-1 button is-info">🐁 Move</button>
        <button class="m-1 button is-success">🐁 Move</button>
        <button class="m-1 button is-warning">🐁 Move</button>
        <button class="m-1 button is-danger">🐁 Move</button>
        <button class="m-1 button is-primary">🐁 Move</button>
        <button class="m-1 button is-link">🐁 Move</button>
        <button class="m-1 button is-info">🐁 Move</button>
        <button class="m-1 button is-success">🐁 Move</button>
        <button class="m-1 button is-warning">🐁 Move</button>
        <button class="m-1 button is-danger">🐁 Move</button>
        <button class="m-1 button is-primary">🐁 Move</button>
        <button class="m-1 button is-link">🐁 Move</button>
    </div>
</div>

Also, to smooth the transition between styles, I wrote an additional CSS style to ease the background-color to limit the strobing effect that might happen if colors change too quickly.

<style>
    .button {
        transition: background-color 0.2s ease-in-out;
    }
</style>

Let’s write some JavaScript. We want to change the CSS class on each .button as the user moves the mouse. If the user stops moving the mouse or leaves the bounds of the page, we want to clear all remaining events from our queue.

window.addEventListener('DOMContentLoaded', () => {

    const colors = [
        "is-info", "is-success",
        "is-warning", "is-danger",
        "is-primary", "is-link"
    ];

    const queue = new EventQueue(250 /* ms */);
    const changeButtonColors = () => {
        const buttons = document.querySelectorAll(".button");
        buttons.forEach(button => {
            button.classList.forEach((c) => {
                if (c.startsWith("is-")) {
                    const currentIndex = colors.indexOf(c);
                    const newIndex = currentIndex < colors.length - 1
                        ? currentIndex + 1 : 0;
                    button.classList.remove(c);
                    button.classList.add(colors[newIndex]);
                }
            });
        });
    };

    document.addEventListener('mousemove', (e) => {
        if (e.movementX === 0 && e.movementY === 0) {
            queue.clear();
        } else {
            queue.enqueue(changeButtonColors);
        }
    });

    document.addEventListener('mouseleave', () => {
        queue.clear();
    })
});

That’s pretty straightforward. As a personal side note, JavaScript and the web stack have come a long way. This was genuinely a joy to write.

Let’s see what it’s like in action.

Pretty cool!

Here’s the full HTML/JavaScript/CSS combination in one file.

<!DOCTYPE html>
<meta name="viewport" content="width=device-width, initial-scale=1">
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <!-- bulma.io -->
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bulma/0.9.4/css/bulma.min.css">
    <style>
        .button {
            transition: background-color 0.2s ease-in-out;
        }
    </style>
</head>
<body>
<section class="section">
    <div class="container">
        <h1 class="title">
            Hello World
        </h1>
        <p class="subtitle">
            My first website with <strong>Bulma</strong>!
        </p>
        <div class="columns">
            <div class="column">
                <button class="m-1 button is-info">🐁 Move</button>
                <button class="m-1 button is-success">🐁 Move</button>
                <button class="m-1 button is-warning">🐁 Move</button>
                <button class="m-1 button is-danger">🐁 Move</button>
                <button class="m-1 button is-primary">🐁 Move</button>
                <button class="m-1 button is-link">🐁 Move</button>
                <button class="m-1 button is-info">🐁 Move</button>
                <button class="m-1 button is-success">🐁 Move</button>
                <button class="m-1 button is-warning">🐁 Move</button>
                <button class="m-1 button is-danger">🐁 Move</button>
                <button class="m-1 button is-primary">🐁 Move</button>
                <button class="m-1 button is-link">🐁 Move</button>
            </div>
        </div>
    </div>
</section>
<script type="application/javascript">
window.addEventListener('DOMContentLoaded', () => {

    const colors = [
        "is-info", "is-success",
        "is-warning", "is-danger",
        "is-primary", "is-link"
    ];

    const queue = new EventQueue(250 /* ms */);
    const changeButtonColors = () => {
        const buttons = document.querySelectorAll(".button");
        buttons.forEach(button => {
            button.classList.forEach((c) => {
                if (c.startsWith("is-")) {
                    const currentIndex = colors.indexOf(c);
                    const newIndex = currentIndex < colors.length - 1
                        ? currentIndex + 1 : 0;
                    button.classList.remove(c);
                    button.classList.add(colors[newIndex]);
                }
            });
        });
    };

    document.addEventListener('mousemove', (e) => {
        if (e.movementX === 0 && e.movementY === 0) {
            queue.clear();
        } else {
            queue.enqueue(changeButtonColors);
        }
    });

    document.addEventListener('mouseleave', () => {
        queue.clear();
    })
});

    class EventQueue {
        constructor(interval) {
            this.queue = [];
            this.interval = interval;
            this.startProcessing();
        }

        enqueue(eventFunction) {
            this.queue.push(eventFunction);
        }

        clear() {
            this.queue = [];
        }

        startProcessing() {
            setInterval(() => {
                if (this.queue.length > 0) {
                    const eventFunction = this.queue.shift();
                    eventFunction();
                }
            }, this.interval);
        }
    }

</script>
</body>
</html>

Conclusion

You can create interactive experiences with some JavaScript and some CSS. The EventQueue I wrote is surprisingly simple yet powerful for my use case, but you can adapt it to your needs. The definition of transition is also an excellent tool for keeping visual transitions from being jarring or obnoxious.

Thanks for reading, and I hope you have a great day. Oh, if you thought this post was cool or helpful, please remember to share it with friends and colleagues. Cheers :)

Output CSV Results to Console Table in Rust

Tue, 09 Apr 2024 00:00:00 +0000

‘ve recently been working with Rust and learning about the language and ecosystem by implementing small, typical task applications. There’s no better way to learn than to jump into it.

In this post, I’ll cover how I could read data from a CSV file, deserialize the contents into an array of struct, and then output that collection into a pretty console table.

To follow along, I assume you have a working Rust environment. If not, I suggest RustRover, which works excellently and provides excellent tooling around the Rust ecosystem. Let’s get into it.

Crate Dependencies

I had to research to find the appropriate dependencies required to read a CSV from disk and then deserialize the rows into a Rust struct. These are the dependencies I found: csv, serde, and lazy_static.

The csv crate provides helper methods to read CSV files using a readers pattern. We’ll see how this works when we get to the code sample.

The serde crate allows me to serialize and deserialize directly into Rust data structures, which I’ll be doing from the on disk CSV.

While lazy_static is optional, it will allow us to read and deserialize our rows once for the application’s lifetime.

There will also be a set of other dependencies that you’ll need to import to get the app working. I also need to import ratatui and it’s dependency of crossterm to work with the terminal.

[dependencies]
crossterm = "0.27.0"
ratatui = "0.26.1"
csv = "1.3.0"
serde = { version = "1.0.197", features = ["derive"] }
lazy_static = "1.4.0"

Here is the complete list of use statements from the final sample.

use crossterm::{event:: {self, KeyCode}, ExecutableCommand};
use crossterm::terminal::{enable_raw_mode, EnterAlternateScreen};
use lazy_static::lazy_static;
use ratatui::{prelude::*, widgets::*};
use std::io::{stdout, Result};
use std::process::exit;
use crossterm::event::{Event, KeyEventKind};

Ok, we have everything we need to get started writing some code. Let’s start by processing our CSV file. Here is some sample data.

name,region,toppings
Margherita,Italy,"Tomatoes, Mozzarella, Basil, Salt, Olive oil"
Hawaiian,Canada,"Tomatoes, Ham, Pineapple, Cheese"
Pepperoni,USA,"Tomatoes, Pepperoni, Cheese"
BBQ Chicken,USA,"BBQ Sauce, Chicken, Onions, Cheese"

Processing a CSV Row into a Struct

While it’s possible to work with CSVs dealing with primitive types, it’s not generally a fun way to work with data. Instead, we want to deal with logical structures. In the case of this tutorial, we are dealing with Pizza.

#[derive(Debug, serde::Deserialize)]
pub struct Pizza {
    name: String,
    region: String,
    toppings: String,
}

The attribute of serde::Deserialize lets our serialization dependency know that this is something we’d like to fill with data.

Now, for the fun part, let’s read the data from disk.

fn read_pizzas() -> Vec<Pizza> {
    let mut reader = csv::Reader::from_path("pizzas.csv")
        .unwrap_or_else(|err| {
            eprintln!("Error reading CSV file: {}", err);
            exit(1);
        });

    reader.deserialize().map(|r| {
        match r {
            Ok(pizza) => pizza,
            Err(err) => {
                eprintln!("Error deserializing pizza: {}", err);
                exit(1);
            }
        }
    }).collect()
}

Rust expects us to handle the Result type and all its potential results. In the case of this sample, if the CSV is mangled, we want to exit the application. As you can see, it’s only two lines of code. The Pizza type is inferred from the Vec<Pizza> return value of our read_pizzas function.

We’ll need to put this information where we can access it once it’s initialized. Here, we’ll use the lazy_static! macro to define a global static type.

lazy_static! {
    static ref PIZZAS: Vec<Pizza> = read_pizzas();
}

Now, we can access this value using &*PIZZAS in our code.

let pizzas = &*PIZZAS;
let count = pizzas.len();
println!("{} total pizzas", count)

Output a Pretty Console Table

The next step uses the ratatui library, but be aware that this library is about building Terminal UIs referred to at TUIs. The nature of the this library is it relies on a UI loop and every iteration renders the contents. This is a helpful model, allowing for real-time updates and fascinating use cases.

To take advantage of ratatui, we must first update our main function to have a UI loop.

fn main() -> Result<()> {
    stdout().execute(EnterAlternateScreen)?;
    enable_raw_mode()?;
    let mut terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
    terminal.clear()?;

    loop {
        terminal.draw(ui)?;
        std::thread::sleep(std::time::Duration::from_millis(10));
        // wait for keys
        if let Event::Key(key) = event::read()? {
            if key.kind == KeyEventKind::Press {
                use KeyCode::*;
                match key.code {
                    Char('q') | Esc => return Ok(()),
                    _ => {}
                }
            }
        }
    }
}

I’ve also allowed folks to exit the app by hitting q or Esc. To reduce the load on the CPU, I’ve also made it so the thread sleeps every 10 milliseconds, just enough to be responsive but not burn up my cores.

The only thing left to do is implement the ui function, but before we do that, we need a helper method to convert our Pizza struct, into a Row. Here we’ll use Rust’s impl keyword to fill in that functionality.

impl From<&Pizza> for Row<'_> {
    fn from(p: &Pizza) -> Self {
        Row::new(vec![
            p.name.clone(),
            p.region.clone(),
            p.toppings.clone(),
        ])
            .bottom_margin(1)
            .style(Style::default().fg(Color::White))
    }
}

Now, let’s look at the ui method.

fn ui(frame: &mut Frame) {
    let pizzas = &*PIZZAS;
    let widths = [
        Constraint::Max(20),
        Constraint::Max(10),
        Constraint::Max(50)
    ];
    let header = Row::new(vec![
        "Name".to_string(),
        "Region".to_string(),
        "Toppings".to_string(),
    ])
        .style(Style::default().fg(Color::White).bg(Color::Blue))
        .bold()
        .bottom_margin(1);

    let table = Table::new(pizzas, widths)
        .header(header)
        .footer(Row::new(vec![format!("{} Pizzas ", pizzas.len())]))
        .block(Block::new().borders(Borders::ALL).title("Pizzas"))
        .style(Style::new().blue())
        .widths(widths);

    frame.render_widget(table, frame.size());
}

Pretty straightforward. Running the application, we’ll see the table rendered in our terminal.

Here’s the final codebase in its complete form.

use crossterm::{event::{self, KeyCode}, ExecutableCommand};
use crossterm::terminal::{enable_raw_mode, EnterAlternateScreen};
use lazy_static::lazy_static;
use ratatui::{prelude::*, widgets::*};
use std::io::{stdout, Result};
use std::process::exit;
use crossterm::event::{Event, KeyEventKind, read};

#[derive(Debug, serde::Deserialize)]
pub struct Pizza {
    name: String,
    region: String,
    toppings: String,
}

lazy_static! {
    static ref PIZZAS: Vec<Pizza> = read_pizzas();
}

impl From<&Pizza> for Row<'_> {
    fn from(p: &Pizza) -> Self {
        Row::new(vec![
            p.name.clone(),
            p.region.clone(),
            p.toppings.clone(),
        ])
            .bottom_margin(1)
            .style(Style::default().fg(Color::White))
    }
}

fn main() -> Result<()> {
    stdout().execute(EnterAlternateScreen)?;
    enable_raw_mode()?;
    let mut terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
    terminal.clear()?;

    loop {
        terminal.draw(ui)?;
        std::thread::sleep(std::time::Duration::from_millis(10));
        // wait for keys
        if let Event::Key(key) = event::read()? {
            if key.kind == KeyEventKind::Press {
                use KeyCode::*;
                match key.code {
                    Char('q') | Esc => return Ok(()),
                    _ => {}
                }
            }
        }
    }
}

fn ui(frame: &mut Frame) {
    let pizzas = &*PIZZAS;
    let widths = [
        Constraint::Max(20),
        Constraint::Max(10),
        Constraint::Max(50)
    ];
    let header = Row::new(vec![
        "Name".to_string(),
        "Region".to_string(),
        "Toppings".to_string(),
    ])
        .style(Style::default().fg(Color::White).bg(Color::Blue))
        .bold()
        .bottom_margin(1);

    let table = Table::new(pizzas, widths)
        .header(header)
        .footer(Row::new(vec![format!("{} Pizzas ", pizzas.len())]))
        .block(Block::new().borders(Borders::ALL).title("Pizzas"))
        .style(Style::new().blue())
        .widths(widths);

    frame.render_widget(table, frame.size());
}

fn read_pizzas() -> Vec<Pizza> {
    let mut reader = csv::Reader::from_path("pizzas.csv")
        .unwrap_or_else(|err| {
            eprintln!("Error reading CSV file: {}", err);
            exit(1);
        });

    reader.deserialize().map(|r| {
        match r {
            Ok(pizza) => pizza,
            Err(err) => {
                eprintln!("Error deserializing pizza: {}", err);
                exit(1);
            }
        }
    }).collect()
}

Update: Once_cell instead of Lazy_static

I typically share my learnings in real-time on Mastodon, and someone mentioned that lazy_static has been usurped by once_cell, so I decided to port the code over to use the newer approach. The following lines are converted into the following.

// 👎 old lazy_static way
lazy_static! {
    static ref PIZZAS: Vec<Pizza> = read_pizzas();
}

// 👍 once_cell Lazy
static PIZZAS: once_cell::sync::Lazy<Vec<Pizza>> =
    once_cell::sync::Lazy::new(|| {
        read_pizzas()
    });

This is a much nicer approach in my opinion, and much easier to follow in code. Try out both ways to see which you prefer.

Conclusion

This was a fun little side project, but I learned much from it. For one, I learned more about Rust’s borrow checker and how to use lazy_static to create a shared resource in memory. Secondly, I learned how to read CSV files from disk and deserialize them into a custom struct. Finally, I learned about ratatui and building TUIs in Rust.

Thanks for reading and sharing my posts with friends and colleagues. Cheers.

Responsive Images Crash Course for ASP.NET Core Developers

Tue, 02 Apr 2024 00:00:00 +0000

Yes, I’m guilty! I’m guilty of ignoring the web platform and all the extraordinary riches waiting for discovery. For all the lip service the .NET community loves to give towards being performance-minded, it’s a shame we stop at the response leaving the server. No more fellow reader; it’s time we think beyond the server and think about HTML and, in the case of this post, images.

In this post, I’ll show you how to optimize your image delivery using newer HTML features and the differences between the two approaches. We’ll see how and why you may want to use each approach by weighing the pros and cons. Finally, we’ll look at cute puppies because who doesn’t love puppies?! Nobody.

The Humble Image Tag

If you’ve ever written HTML, you’ll almost certainly have used the img tag. Images are an essential element of most web pages, yet they can also be the downfall of many. Suboptimal images can drag down your Core Web Vitals, the metrics used to determine how a user may perceive your site’s performance. Let’s look at a plain old image tag you may typically see in an HTML response.

<img alt="good boy corgi" src="/img/good-boy@3x.webp">

Nothing outrageous, right? Well, this particular image is sub-optimal for many reasons.

This image is 3.1 MB and has dimensions of 2000px x 2952px
The image tag lacks width and height attributes, so loading the image will cause layout shifts and page redraws
We serve one image for all devices, regardless of pixel density or medium. It’s wasteful.

Let’s see if we can do better.

Descriptive Responsive Image

The img tag has a few new attributes that can help developers address the above-mentioned issues. Those attributes are srcset and sizes.

The srcset attribute allows you to define a set of source images the browser should consider when rendering the HTML to the user. The critical word here is “should”, as the browser determines the selected image. We’ll see how to steer the browser in a particular direction, but it will always be up to the browser. First, let’s see an example of an image with a srcset.

<img
    srcset="/img/good-boy@3x.webp 2000w, /img/good-boy@2x.webp 1000w, /img/good-boy@1x.webp 500w"
    src="/img/good-boy@1x.webp"
    alt="a good boy - corgi puppy"
    decoding="async"
    >

Three images are defined with their width descriptor specified in <number>w format. The width descriptor tells the browser what the image’s intrinsic width is in a unit-agnostic way. This is important as some displays have pixel densities of 1x, 2x, or 3x. We also set the src tag as a fallback for clients that do not support srcset, although those clients are almost non-existent.

Let’s give the browser hints on what to choose when displaying one of our three options. That’s where the sizes attribute comes into play.

<img  
    srcset="/img/good-boy@3x.webp 2000w, /img/good-boy@2x.webp 1000w, /img/good-boy@1x.webp 500w"  
    sizes="(max-width:500px) 500px, (max-width:1000px) 1000px, (max-width:2000px) 2000px"  
    src="/img/good-boy@1x.webp"  
    alt="a good boy - corgi puppy"  
    decoding="async"  
    >

Let’s see what the sizes mean:

When the maximum width of the viewport is 500px, the image will take up 500px in layout.
When the maximum width of the viewport is 1000px, the image will take up 1000px in layout.
When the maximum width of the viewport is 2000px, the image will take up 2000px in layout.

We use CSS to define matches in the form of (max-width:500px). Additionally, we could use the use case and assume all images will always be displayed at 100vw.

<img
    srcset="/img/good-boy@3x.webp 2000w, /img/good-boy@2x.webp 1000w, /img/good-boy@1x.webp 500w"
    sizes="100vw"
    src="/img/good-boy@1x.webp"
    alt="a good boy - corgi puppy"
    decoding="async"
    >

Again, it’s important to note that the client ultimately decides which option is best given the current state of the viewport.

What are the advantages of this approach?

The client knows best, so let it choose for you.
Once the largest-size asset is loaded, it will always be used from the cache. Upgrades never any downgrades in quality.
Less HTML than the other option.

What are the disadvantages?

Lack of control and “art direction”
Black box of when and why things might be chosen.

Let’s look at the next option, the picture tag, and see how we may overcome some disadvantages.

The Descriptive Approach to Responsive Images

The picture tag allows us to describe what image to serve and when to serve it. This allows us a level of control not available to folks using the img tag with srcset and sizes. Let’s take a look at an example.

<picture>
    <source media="(max-width: 500px)" width="500" height="738" srcset="/img/sad-boy@1x.webp">
    <source media="(max-width: 1000px)" width="1000" height="1476" srcset="/img/sad-boy@2x.webp">
    <source media="(min-width: 2000px)" width="2000" height="2952" srcset="/img/sad-boy@3x.webp">
    <img src="/img/sad-boy@3x.webp" alt="a sad boy - French bulldog in a hoodie" loading="lazy">
</picture>

As you may notice, it’s more verbose, but we now can choose precisely what image gets displayed and when it gets displayed.

This can give us a sense of art direction not available with the previous method. We could display images optimized for mobile devices or desktops based on media queries. This can help us optimize the size and dimensions of an image like we couldn’t before.

Advantages of this approach?

Art Direction - Images change as the viewport changes
Flexibility
Still delivering the optimal experience.

Disadvantages to this approach?

Verbose - lots and lots of HTML
Resizes may cause additional network requests for new assets

Let’s see both of these examples in a demo.

Responsive Images Demo Time

This video is hosted on Mastodon, so you can head to my Mastodon page to see it in action. You can also head to my GitHub repository to download the sample ASP.NET Core project.

Your browser does not support the video tag.

As you notice, when I resize the window, the pictures of puppies change (look at the 1x, 2x, and 3x in the corners).

The Corgi’s 1x image is never displayed, but the French Bulldog’s image behaves more predictably. Very cool, right? Give it a try by downloading the demo from GitHub.

Conclusion

Responsive images are an excellent feature of HTML, but they require a bit of thought upfront and an understanding of what you’re attempting to accomplish. The img tag has srcset and sizes and might be an easier path for ASP.NET Core devs as a starting point, but the picture tag offers more control and “art direction”. Regardless of your choice, you’ll deliver an optimized experience to your users.

Thanks for reading and sharing these posts with friends and colleagues. Cheers.

How To SSR Web Components In ASP.NET Core using TagHelpers

Tue, 26 Mar 2024 00:00:00 +0000

Web Components are gaining momentum in the web platform space, and frankly, it’s bittersweet for us ASP.NET Core developers. On the one hand, you can use Web Components in your current ASP.NET Core applications, as I demonstrated in a previous post, but it isn’t the best experience it could be. You’ll have flashes of unstyled content, layout shifts, JavaScript code that blocks the critical rendering path, and you’ll not get the server-side rendering (SSR) goodness developed exclusively for the JavaScript ecosystem.

In his post “THE GOOD, THE BAD, THE WEB COMPONENTS”, Zach Leatherman wrote about the ideal way to deliver web components to avoid some of the issues I described. In this blog post, we’ll see how we can use ASP.NET Core’s Tag Helpers to deliver the best experience to users when using Web Components.

The ideal Web Component delivery method

Web Components are a mix of JavaScript and HTML. Nesting your HTML within a custom element tag is best for delivering a progressively enhanced and seamless experience. Let’s take a look at building a Counter component. First, let’s see what the custom element would look like on your page.

<my-counter>
	<button class="btn btn-primary">1</button>
</my-counter>

and the corresponding JavaScript would be as follows.

class Counter extends HTMLElement {
    connectedCallback() {
        const button = this.querySelector("button");
        button.addEventListener("click", () => {
            button.innerText = (parseInt(button.innerText) + 1).toString();
        });
    }
}

customElements.define("my-counter", Counter);

This allows the client to render the button element and its CSS styles in place before the JavaScript attaches the event listener. That’s awesome, but this technique breaks down quickly once you want to use the counter multiple times.

<my-counter>
	<button class="btn btn-primary">1</button>
</my-counter>
<my-counter>
	<button class="btn btn-primary">2</button>
</my-counter>
<my-counter>
	<button class="btn btn-primary">3</button>
</my-counter>

This is especially painful if the internal HTML is complex with multiple nodes.

Shadow Dom and Templates

With Web Components, you can avoid repeating yourself by utilizing the template element. This template can be used in JavaScript to clone repeated elements within an instance of a component. Let’s look at the HTML.

<template id="my-counter-template">
    <style>
        button {
            background-color: orange;
            color: black;
            padding: .375rem .75rem;
            border-radius: 0.25rem;
            border:  1px solid transparent;
            line-height: 1.5rem;
            cursor: pointer;
            &:hover {
                /* make color darker */
                filter: brightness(75%);
            }
        }
    </style>
    <button>
        <slot></slot>
    </button>
</template>
<my-counter>1</my-counter>
<my-counter>1</my-counter>
<my-counter>2</my-counter>
<my-counter>3</my-counter>

This is great for reducing repetition but comes at the expense of additional front-end processing. Let’s look at the updated JavaScript that now uses the ShadowDom.

class Counter extends HTMLElement {
    connectedCallback() {
        if (this.dataset.template) {
            const template = document.getElementById("my-counter-template");
            const shadowRoot = this.attachShadow({mode: "open"});
            shadowRoot.appendChild(template.content.cloneNode(true));
            const button = shadowRoot.querySelector("button");
            button.addEventListener("click", () => {
                console.log(button);
                this.innerText = (parseInt(this.innerText) + 1).toString();
            });
		}
    }
}

customElements.define("my-counter", Counter);

You can probably tell a few things changed in the JavaScript as well. This is a bit more complex, and we lost the ability to target the elements in our components with external styles from a CSS framework like Bootstrap.

What if we could get the benefits of the first implementation with the style of the second? Well, luckily, with ASP.NET Core, we can!

ASP.NET Core TagHelpers to the rescue!

TagHelpers can do almost anything to the elements within its content, and I mean anything. Let’s look at how we might implement a WebComponentOptimizer tag helper in our ASP.NET Core Razor pages.

<web-component-optimizer>
    <template name="my-counter">
        <button class="btn btn-danger">
            <slot></slot>
        </button>
    </template>

    <my-counter>1</my-counter>
    <my-counter>2</my-counter>
    <my-counter>3</my-counter>
</web-component-optimizer>

When we render the page, we will get the following HTML.

<my-counter>
	<button class="btn btn-danger">
		1
	</button>
</my-counter>
<my-counter>
	<button class="btn btn-danger">
		2
	</button>
</my-counter>
<my-counter>
	<button class="btn btn-danger">
		3
	</button>
</my-counter>

The template is processed from the HTML output, and you get some fast and snappy web components on the initial page load. That’s awesome, right?!

Well, here’s the tag helper to help you do that. Note: this is a proof of concept. Before going to a production environment, you’ll want to test and adapt this for your needs.

using AngleSharp;
using AngleSharp.Dom;
using AngleSharp.Html;
using AngleSharp.Html.Dom;
using AngleSharp.Html.Parser;
using Microsoft.AspNetCore.Razor.TagHelpers;

namespace WebComponentsWithTagHelpers;

public class WebComponentOptimizer : TagHelper
{
    public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
    {
        var children = await output.GetChildContentAsync();
        var parser = new HtmlParser();
        var document = await parser.ParseDocumentAsync(children.GetContent());
        
        // clear the output
        output.Content.Clear();
        output.TagName = "";

        var template = (IHtmlTemplateElement)document.GetElementsByTagName("template")[0];
        var webComponentName = template.GetAttribute("name");
        
        if (webComponentName is { })
        {
            var outputBuilder = new StringWriter();
            var formatter = new HtmlMarkupFormatter();
            var webComponents = document.GetElementsByTagName(webComponentName);
            
            foreach (var webComponent in webComponents)
            {
                var clone = template.Content.Clone();
                var slot = clone.FindDescendant<IHtmlSlotElement>()!;

                slot.OuterHtml = webComponent.InnerHtml;
                slot.RemoveFromParent();
                webComponent.InnerHtml = clone.ToHtml(); 
                webComponent.ToHtml(outputBuilder,formatter); ;
            }

            output.Content.SetHtmlContent(outputBuilder.ToString());
        }
    }
}

There are a few neat tag helper tricks here.

Setting the TagName to an empty string removes the parent tag.
AngleSharp is a great way to parse the existing DOM
You can use a formatter to optimize the final output.

If you want to try this for yourself, head to GitHub to see the whole sample.

Stretch Goals: Other Web Component Frameworks

While not shown here, I’d love someone to use the SSR support in their favorite frontend frameworks to integrate with Razor views. This could improve the initial user experience while allowing developers to use frameworks like Angular, Vue, and React. Since ProcessAsync could call out to an NPM process and retrieve the starting HTML from a library.

Conclusion

Web Components are fantastic, and they have so much potential to make the user experience great for users without long pauses while the UI gets its act together. On the .NET side, ASP.NET Core could be a great option to boost the web platform with Razor’s strength. This blog post only begins to scratch the surface of what could be possible. I hope you consider this when building your following UI in ASP.NET Core as an option for delivering world-class experiences.

Thanks for reading and sharing my posts with friends and colleagues. Cheers.

Blazor's CSS isolation ::deep issue and solution

Tue, 19 Mar 2024 00:00:00 +0000

Lately, I’ve been helping a few developers solve some of their issues around Blazor adoption. While I have mixed feelings about the technology, my urge to help developers overcome their challenges outweighs my trepidation with the technology itself.

Recently, I had a Blazor developer have issues with the ::deep cascading style sheet (CSS) pseudo-selector and the style’s inability to cascade styles to child components. If you’re having a similar issue, I have a detailed issue breakdown and potential solution. Let’s get started.

What is CSS isolation?

Blazor is a component-based framework that takes much inspiration from the JavaScript ecosystem’s React component model. The model focuses on reusability through encapsulation and manifests in a single-file style that combines Razor markup and C# logic.

In a Blazor application, CSS can be scoped to a single component by adding a convention-based filename similar to a component. For example, if your application contains a Counter.razor component, any styles defined in Counter.razor.css would be scoped to the component definition.

Blazor scopes CSS by adding a component-unique HTML attribute to the HTML rendered on the client. Take, for example, the contents of Counter.razor.css, which I’ve added to a new Blazor application.

h1 {
    color: pink;
}

The resulting CSS is sent to the client when the Blazor build pipeline processes the file.

/* /Pages/Counter.razor.rz.scp.css */
h1[b-13zswy4nzk] {
    color: pink;
}

This CSS rule reads, “any H1 in the current document with an attribute of ‘b-13zswy4nzk’ should have pink-colored text.”

Scoped CSS allows you to target components with styles without the risk of having rules conflict with other rules. But what if you want to take advantage of the cascading part of CSS?

Using the `::deep` pseudo-selector

As you saw, Blazor processes component-scoped CSS files and adds them to your application’s Blazor CSS file. This allows Blazor developers to use additional pseudo-selectors to generate different rules. One such pseudo-selector is the ::deep selector.

The ::deep pseudo-selector will allow you to target child HTML elements nested within a parent component. Let’s change the previous CSS rule to use this feature.

::deep h1 {
	color: pink;
}

After running the Blazor application, we can see the updated CSS rule.

/* /Pages/Counter.razor.rz.scp.css */
[b-13zswy4nzk] h1 {
    color: pink;
}

This new CSS rule reads, “any H1 element found within an element with the attribute of ‘b-13zswy4nzk’ will have a text color of pink.”.

Great! Ship it. What’s the issue?

The Blazor attribute problem

Let’s take a look at the Counter.razor component and a new Child.razor component with the previous isolated CSS in mind. First, the Counter.razor definition.

@page "/counter"

<PageTitle>Counter</PageTitle>
<Child/>
<p role="status">Current count: @currentCount</p>
<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

You’ll note the usage of the Child component right under the PageTitle component. Let’s see that implementation.

<h1>Counter</h1>

@code {
    
}

Given the isolated CSS, we would assume that the H1 element within our child component would become pink, but that’s not the case. Let’s look at the rendered HTML to see the issue.

<article class="content px-4" b-5dhe1ruqj7>
    <h1 tabindex="-1">Counter</h1>
    <p role="status" b-13zswy4nzk>Current count: 0</p>
    <button class="btn btn-primary" b-13zswy4nzk>Click me</button>
</article>

Do you see the issue? Blazor adds the unique attribute to all top-level HTML elements within a component. This creates a mismatch between markup and the CSS rule.

In the rendered HTML, the p and button elements get the attribute b-13zswy4nzk, but our Child component is used within the Counter component but before the any HTML element. Worse, there are no encapsulating HTML elements.

The fix to ::deep styles

So you’ve read this far and want to know the solution to the problem. It’s relatively straightforward.

If your usage of the ::deep pseudo-selector is not working, you need to add a wrapping HTML element within your parent component that is a parent to all usages of child components.

Let’s fix our Counter.razor markup with a straightforward change.

@page "/counter"

<div>
	<PageTitle>Counter</PageTitle>
	<Child/>
	<p role="status">Current count: @currentCount</p>
	<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
</div>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

When we re-run our application, we can see that the unique attribute is now on the first HTML element along with the previous elements of p and button and our CSS rule now targets nested HTML elements correctly.

<div b-13zswy4nzk>
    <h1 tabindex="-1">Counter</h1>
    <p role="status" b-13zswy4nzk>Current count: 0</p>
    <button class="btn btn-primary" b-13zswy4nzk>Click me</button>
</div>

This fixes the issue, but depending on the CSS framework library you’re using, a parent div HTML element may break your layout. Experiment with different HTML tags to see which ones you can use as wrappers while not breaking global CSS rules.

Conclusion

CSS Isolation is a technique for continuing the philosophy of encapsulating as much within the bounds of a component, but there are times where you want the cascade to do its job. To get the ::deep pseudo-selector element working properly, all your Blazor components should have a single-wrapping HTML element as the root element. If your Blazor components do not have a parent element, you’ll get CSS rules that don’t ultimately match your HTML markup.

Hope this post helped, and as always, thanks for reading and sharing my posts with friends and colleagues. Cheers.

How to use No-Class Frameworks to Move Fast in Style

Tue, 12 Mar 2024 00:00:00 +0000

Software development can be a struggle between form and function. With many developers, function takes the driver’s seat, while the aesthetics of an application are lucky to have a seat in the vehicle. Rational minds might say, “Well, what does it matter how it looks? As long as it works right?” but great design isn’t always rational; it’s emotional.

Many developers look to supplement their design deficits with style libraries like Bootstrap, Tailwind CSS, and Bulma to evoke strong user emotions. These are great initial options, but they typically are temporary substitutes for greater ambitions of bespoke design systems. Style libraries can also stand in the way of evolving a UI to meet user needs since they heavily rely on library-specific HTML, JavaScript, and CSS classes. Removing these dependencies is unlikely once they find their way into your codebase.

To my surprise, there have been a few attempts to give developers a strong design starting point while leveraging HTML’s existing semantics and foundational elements. This movement is known as “No-class Frameworks”.

In general, No-class frameworks force developers to write semantically appropriate HTML while limiting the need for CSS classes in the markup. The libraries do their best to use the HTML markup to style around standard practices.

This post will look at MVP.CSS and some examples of styled HTML elements. Then, we’ll discuss the advantages and disadvantages of using a no-class framework in your application.

MVP.CSS - a No-class framework

As the name suggests, MVP.CSS is a style library designed to help developers build web pages for their minimal viable product (MVP) projects. The MVP is a common practice in tech circles to build a functional product while only including the bare essentials feature set. As the name suggests, the library’s aesthetics are muted and restrained but better than what you’d get if you used nothing.

To get started with MVP.CSS, add a single no-build stylesheet to the page’s header.

<link rel="stylesheet" href="https://unpkg.com/mvp.css">

In a feature grid on the site, MVP.CSS boasts that it is mobile-friendly, works out of the box, easily customizable, and only operates on semantic HTML.

Let’s see what a styled table’s HTML looks like.

<table>
    <thead>
    <tr>
        <th></th>
        <th>Col A</th>
        <th>Col B</th>
        <th>Col C</th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td>Row 1</td>
        <td>Cell A1</td>
        <td>Cell B1</td>
        <td>Cell C1</td>
    </tr>
    <tr>
        <td>Row 2</td>
        <td>Cell A2</td>
        <td>Cell B2</td>
        <td>Cell C2</td>
    </tr>
    </tbody>
</table>

This approach applies to many common HTML elements, including headings, forms, navigation, quotes, and lists.

While the initial white and blue color scheme might suit most situations, MVP.CSS allows library consumers to modify the visual rendering with global CSS variables. After loading the library, you can control background, primary, and secondary colors and font choices by modifying the following rule in a custom stylesheet.

:root {
    --active-brightness: 0.85;
    --border-radius: 5px;
    --box-shadow: 2px 2px 10px;
    --color-accent: #118bee15;
    --color-bg: #fff;
    --color-bg-secondary: #e9e9e9;
    --color-link: #118bee;
    --color-secondary: #920de9;
    --color-secondary-accent: #920de90b;
    --color-shadow: #f4f4f4;
    --color-table: #118bee;
    --color-text: #000;
    --color-text-secondary: #999;
    --font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
    --hover-brightness: 1.2;
    --justify-important: center;
    --justify-normal: left;
    --line-height: 1.5;
    --width-card: 285px;
    --width-card-medium: 460px;
    --width-card-wide: 800px;
    --width-content: 1080px;
}

The Advantages of No-Class Frameworks

There are several advantages to using a No-Class framework, some obvious and others less so.

Less Stuff

Semantic HTML leads to smaller payloads for the client, and the parsing of CSS and HTML required to create the CSSDOM and DOM is significantly less work. That leads to consistently faster pages and better user experiences.

Simplified Markup

If you’ve worked with any CSS framework, you’ve likely spent significant time in the documentation. With No-Class frameworks, your HTML will render as you expect without additional classes or markups.

No Build Tools

In most cases, since there is a limited number of HTML elements, most No-class frameworks don’t require any build tools. The build tools in the JavaScript ecosystem can be a frustrating experience, especially for developers working in other ecosystems.

Simple Exit Strategy

When you’ve decided you need more from your UI, you have a great starting point to style existing HTML without the tedious work of extracting the previous styles and framework-dependent HTML.

Embrace the CSS Platform

Other approaches may be seen as fighting against the HTML and CSS platform by jamming design-oriented classes into the document. No-Class tries to stay closer to the platform, letting you take advantage of modern CSS rather than treating CSS as an intermediate language.

Disadvantages of No-Class Frameworks

No-class frameworks aren’t all rainbows and unicorns, as they have definite drawbacks. We’ll point these out in this section.

Limited HTML Components

While an extensive list of HTML components is in the HTML specification, they are limited. If you’re building a unique web experience, you’re likely to hit this limitation sooner than later.

Minimal Layout Options

The ethos of these frameworks is around common style patterns, which don’t offer many visual options. The lack of bells and whistles can make pages feel repetitive. CSS grids and Flexbox can provide options that work well with semantic HTML.

Bring Your Style

You’re out of luck if you seek guidance around a cohesive color palette and iconography. The missing style guidance can feel like being back at square one for many folks who think a style library aims to make these kinds of decisions for them.

Conclusion

This post was inspired by a 2020 blog post by Chris Coyier, and while the blog post is a few years old, the message of leaning on the web platform has never been more critical. With No-class frameworks, developers can ship lightweight user experiences that work for a wider audience without the burden of heavier CSS frameworks.

The advancements in HTML and CSS have never made it more possible to build familiar experiences without the burden of past limitations. If you’re starting a new project, I recommend starting with a No-class approach and seeing how far you get. Even if you reach for another library, you’ll have begun in a much simpler place and better appreciate how far you can get with so little.

How to Integrate HTMX and Shoelace Web Components

Tue, 05 Mar 2024 00:00:00 +0000

In my last post, Shoelace Web Components with ASP.NET Core, I showed ASP.NET Core developers how to integrate the web components of Shoelace into an existing web application. It’s incredible, and you should check it out. If you’ve read this blog any time, you might have read a post or two about HTMX, a library for building dynamic and maintainable web experiences; I love it.

While the two libraries can work together, there’s an issue you need to work around to get the advantages of both. In this post, we’ll discuss the issues with using Shoelace with HTMX and how to get it working again with your ASP.NET Core applications. If you’re using any other technology stack (Django, Spring, or Next.js), don’t worry; the solution here will work for you, too.

Update in HTMX 2.0 and Shadow DOM support

For folks using HTMX 2.0, the HTMX library has since resolved this issue and you’re no longer required to perform the steps in this blog post. Users of HTMX pre-2.0 will still need the following blog post, but I would recommend upgrading to the latest version. The biggest changes in HTMX include moving all extensions out of the core library and making them opt-in.

I’ve confirmed the expected behavior in a branch on my GitHub Repository. Cheers. 🍻

Shoelace, the Shadow DOM, and HTMX

Shoelace is a web component library that encapsulates all functionality in a user-friendly HTML tag. Let’s take a look at the most common element, the Button.

After installing the Shoelace scripts, adding the sl-button element in HTML markup is straightforward.


<sl-button>Button</sl-button>

The abstraction works out nicely from a developer and user perspective, as these elements “just work” with HTML (as you might have read in the post mentioned earlier). Looking at how a client renders this element shows some of the implementation details.


<sl-button variant="default" size="medium" data-optional="" data-valid="">
    #shadow-root (open)
    <button part="base" class=" button button--default button--medium button--standard button--has-label " type="button"
            title="" name="" value="" role="button" aria-disabled="false" tabindex="0">
        <slot name="prefix" part="prefix" class="button__prefix"></slot>
        <slot part="label" class="button__label"></slot>
        <slot name="suffix" part="suffix" class="button__suffix"></slot>
        <!--?lit$16265820754$-->
        <!--?lit$16265820754$-->
    </button>
    Button
</sl-button>

Shoelace uses the Lit library to build components utilizing the Shadow DOM. These elements exist virtually in the DOM and are part of the page but may or may not be accessible based on the implementation.

As you likely guessed, HTMX doesn’t look at the Shadow DOM of custom web components to find common elements such as button, input, or select. This can be a problem for folks using HTMX to hijack form elements or adding hx- attributes to shoelace components. These custom components aren’t added to the ultimate request that HTMX builds.

Don’t worry; there’s an easy fix.

HTMX Events To The Rescue

HTMX has many events that allow you to intercept context at any point in the process. For our use case, we want to intercept all outgoing requests and determine if our target element and any of its children contain Shoelace components.

Luckily for us, Shoelace components follow a typical pattern of having name and value attributes. We can assume that any element with a name attribute is expected to be transmitted in a request.

Let’s hook into the htmx:beforeRequest. Add the following code into any script file that loads after HTMX and Shoelace libraries.

document.body.addEventListener('htmx:beforeRequest', evt => {
    const elements = [
        evt.target,
        ...evt.target.querySelectorAll('*')
    ];

    for (const el of elements) {
        const {tagName, name, value, disabled, checked} = el;

        // ignore inputs that aren't from shoelace
        if (!tagName.startsWith("SL-")) continue;
        // all inputs can be disabled
        if (disabled) continue;
        // the name is required
        if (name === undefined || name === "") continue;
        if (value === undefined) continue;

        // a checkable element
        if (checked !== undefined) {
            if (checked) {
                evt.detail.requestConfig.parameters[name] = value;
            }
        } else {
            // it is a simple element
            evt.detail.requestConfig.parameters[name] = value;
        }
    }
});

Note that form values can have duplicate names within a form collection. I don’t commonly duplicate names, but it might be a typical pattern for arrays in other technology stacks. If so, you may need to alter the code above to suit your needs.

As an additional note, there may be some components you need to account for in your server code. For example, sl-select component works with arrays.

The current value of the select, submitted as a name/value pair with form data. Whenmultipleis enabled, the value attribute will be a space-delimited list of values based on the options selected, and the value property will be an array. For this reason, values must not contain spaces. –Shoelace Documentation

So far, in my testing, this code works with most of the shoelace elements in the official documentation. That said, please test and modify the code according to your needs.

Conclusion

It’s always fun when things work together, but it’s not always the case. Luckily, both HTMX and Shoelace offer great APIs that allow you to smooth out some of these issues. Please try these two libraries in your ASP.NET Core applications and let me know how it goes.

As always, thanks for reading the posts, and I hope I helped you get on your way to a productive day. Cheers.

*Special thanks to Mario Hamann and his excellent post integrating Web Components and Livewire.

Shoelace Web Components with ASP.NET Core

Tue, 27 Feb 2024 00:00:00 +0000

Web Components are a powerful way to add UX to your web applications while using the web platform. That makes them ideal as they can be used in various ecosystems with little or no changes. They also require no build pipelines as they are supported natively in most clients. This is in stark contrast to approaches like React or Blazor.

A mature web component library like Shoelace allows you to share common UI components with teams working on different technology stacks. This can create a consistent user experience regardless of the server technology used to render the pages. Take advantage of server-side rendering strengths without heavy SPA libraries or confusing build pipelines.

In this repository, you will find a sample using Shoelace components that work with ASP.NET Core Razor Pages and TagHelpers.

What is a Web Component?

A web component is a reusable component written to take advantage of the standard component model built into some of the most popular web clients, such as Chrome, Firefox, and Safari. The component model includes three sets of technologies, and a web component can take advantage of one or all of them: Custom Elements, Shadow DOM, and HTML Templates.

The goal of web components is to reduce unnecessary overhead by building commonly run tasks into the web platform itself. This helps increase interoperability across UI frameworks and improve the performance of many frontend experiences.

What is Shoelace?

Shoelace is a “forward-thinking library for web components.” The library attempts to create reusable UI elements that you can utilize as-is or within other existing UI frameworks, such as React, Vue, or Angular. Some of these components include common patterns such as input elements, badges, buttons, alerts, and so many more. Shoelace also provides consumers with a stylistic starting point, but allows for all component details to be altered.

To get started with Shoelace is straightforward, as all you need is to register the library in your web pages head tag.


<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.12.0/cdn/themes/light.css"/>
<script type="module"
        src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.12.0/cdn/shoelace-autoloader.js"></script>

You can also choose to selectively bundle Shoelace using a JavaScript build pipeline, but this step is optional.

Adding Shoelace to ASP.NET Core

Check out the working sample on my GitHub repository

There are not that many steps required to add Shoelace to an existing ASP.NET Core application. Shoelace also integrates well with existing UI libraries such as Bootstrap.

In a new ASP.NET Core project, replace the top of the _Layout.cshtml file with the following markup.

@{
    const string shoelaceStylesheet = "https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.12.0/cdn/themes/light.css";
    const string shoelaceJavaScript = "https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.12.0/cdn/shoelace-autoloader.js";
}

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>@ViewData["Title"] - SweetKicks</title>
    <link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.min.css"/>
    <link rel="stylesheet" href="~/css/site.css" asp-append-version="true"/>
    <link rel="stylesheet" href="~/SweetKicks.styles.css" asp-append-version="true"/>
    <link rel="stylesheet" href="@shoelaceStylesheet" />
    <script type="module" src="@shoelaceJavaScript"></script>
    @await RenderSectionAsync("headScripts", required: false)
</head>

If you want the URLs inline, you will need to escape the @ symbols with @@. In this case, I thought it would be easier to read if I moved the URLs to the beginning of the file.

I have added an extra section of headScripts, which we will use later.

The most essential element of this code snippet is the script reference to shoelace-autoloader.js, which scans the page for shoelace components and then auto-wires those components into the known set of custom elements. Without this, elements would not render and be visible to users.

Let’s add some code to our Index.cshtml.cs to set up for the eventual use of Shoelace components.

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

namespace SweetKicks.Pages;

public class IndexModel(ILogger<IndexModel> logger) : PageModel
{
    [TempData]
    public string? Name { get; set; }
    
    public void OnGet()
    {
    }

    public RedirectToPageResult OnPost([FromForm] string name)
    { 
        logger.LogInformation("Name is {Name}", name);
        Name = name;
        return RedirectToPage();
    }
}

Before we get to using the Shoelace components, we need to let ASP.NET Core know about the sl-input component we’ll be using so we can take advantage of tag helpers. Place the following file anywhere in the project.

using JetBrains.Annotations;
using Microsoft.AspNetCore.Mvc.TagHelpers;
using Microsoft.AspNetCore.Mvc.ViewFeatures;
using Microsoft.AspNetCore.Razor.TagHelpers;

namespace SweetKicks.TagHelpers;

[UsedImplicitly]
[HtmlTargetElement("sl-input", Attributes = "asp-for", TagStructure = TagStructure.WithoutEndTag)]
public class ShoelaceInputTagHelper(IHtmlGenerator generator) 
    : InputTagHelper(generator);

Also, be sure to register the new tag helper in _ViewImports.cshtml making sure to adjust the namespace according to your needs.

@using SweetKicks
@namespace SweetKicks.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, SweetKicks

Now, let’s use some Shoelace components. In Index.cshtml, we can replace the following HTML with the following markup.

@page
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

<div>
    @if (Model.Name is not null)
    {
        <sl-alert open>
            <sl-icon slot="icon" name="info-circle"></sl-icon>
            Your name is @Model.Name
        </sl-alert>
    }

    <form method="post" asp-page="Index" class="my-3">
        <sl-input label="What is your name?"
                  type="text"
                  asp-for="Name"
                  help-text="ex. Alex Murphy"
                  required
                  autofocus>
        </sl-input>
        <sl-button class="mt-2" variant="primary" type="submit">Submit</sl-button>
    </form>
</div>

Running the application now shows our input element. Submitting the form will also show the alert notification.

If you take a look at the markup again, you’ll notice that a single sl-input got us a user experience that includes a label, a placeholder, and input. Additionally, with our ShoelaceInputTagHelper class, we now have ASP.NET Core support for web components. Not bad at all.

Flash Of Content Fixes

Eagle-eyed developers may have noticed a flash of undefined content as the components were rendered. There are several fixes to this, with them coming from this blog post.

The first and simplest fix is to use a CSS style in the site.css.

:not(:defined) {
    visibility: hidden;
}

This won’t render any undefined elements, including any sub content. This is OK, but can still be jarring.

The second fix is to add the following CSS to the site.css stylesheet.

body {
    margin-bottom: 60px;
    opacity: 0;
}

body.ready {
    opacity: 1;
    transition: .25s opacity;
}

Then to modify either the _Layout.cshtml or Index.cshtml file with the following JavaScript snippet.

<script type="module">
    /* note: this will block rendering if forget
       using a mentioned custom component. 
     ex. sl-not-a-real-component */
    await Promise.allSettled([
        customElements.whenDefined('sl-input'),
        customElements.whenDefined('sl-button'),
    ]);

    document.body.classList.add('ready');
</script>

You may also do this on a per-page basis using predefined sections.

@section headScripts
{
    <script type="module">
          /* note: this will block rendering if forget
             using a mentioned custom component. 
           ex. sl-not-a-real-component */
          await Promise.allSettled([
            customElements.whenDefined('sl-input'),
            customElements.whenDefined('sl-button'),        
          ]);
              
          document.body.classList.add('ready');
    </script>
}

As noted in the comment, this approach will block the page rendering until the client is finished registering the mentioned components. After they are done loading, the page will transition from 0 to 1 opacity. This provides a nice experience, but has the downside of needing to track all components that are used on a page.

I personally prefer the first approach as you’d less likely break the entire page by accidentally removing an element that you had previously registered.

Conclusion

Web Components are awesome and are the future of web development. There are still some caveats, but in my opinion, they can help reduce vendor lock-in and ultimately provide more value to teams who may be doing polyglot development. There’s also a world of unexplored possibilities with web components depending on your approach. With Shoelace, all components encapsulate functionality, and that’s great for feature reuse. There’s another approach of progressive enhancement components that can take existing HTML and enrich it with additional client-side features. I highly recommend you check out the other components in the Shoelace component library.

As always, thanks for reading and sharing my posts.

How to Map SQL Results To Any Object Using Entity Framework Core 8

Tue, 20 Feb 2024 00:00:00 +0000

Entity Framework Core 8 packs a punch, aiming for the undisputed title of “most powerful Object-Relational Mapper (ORM)” in the .NET space. Many folks in our community are typically divided about using ORMs, with many preferring Micro-ORMs. A Micro-ORM has basic mapping functionality from SQL results but lacks object-tracking features that make ORMs what they are.

What Micro-ORMs lack in object-tracking, they make up for in simplicity and functionality. The most popular library is Dapper, which allows folks to write SQL, execute the query, and map the results to any .NET Object. Well, with Entity Framework Core 8, you can have Dapper-like functionality with the strengths of EF Core.

This post will be short, but for most folks, this is a public service announcement to improve performance and tune existing code paths. Let’s get started.

What’s this about Mapping Any Object?

Before the EF Core 8 release, all entities that were to be queried from a DbContext had to be registered within the implementation. These types are typically referenced as a DbSet<T>. Anyone who’s worked with a database understands that SQL allows us to create any result we like, even though those entities might not directly exist in our schema. This disadvantaged EF Core compared to Dapper, which lets you craft any SQL statements you want and map them to C# objects.

In EF Core 8, you can now use SqlQuery<T> to pass in any SQL statement and map the results to a C# object.

var result = await db
    .Database
    .SqlQuery<NamedResult>($"Select Id, Name from Customers")
    .FirstOrDefaultAsync();

Console.WriteLine($"NamedResult: {result}");

record NamedResult(int Id, string Name);

Awesome! As a bonus, you can apply additional LINQ methods to your existing SQL statement.

var result = await db
    .Database
    .SqlQuery<NamedResult>($"Select Id, Name from Customers")
    .Where(c => c.Id == 1)
    .FirstOrDefaultAsync();

Console.WriteLine($"NamedResult: {result}");

record NamedResult(int Id, string Name);

The EF Core generates an SQL statement that uses a nested select to keep your original query intact while adding additional filtering.

SELECT "n"."Id", "n"."Name"
FROM (
  Select Id, Name from Customers
) AS "n"
WHERE "n"."Id" = 1
LIMIT 1

There you have it. I hope you enjoyed this short post. I’m glad to see this feature as part of EF Core 8 finally. It’s been a long time in the making, and thanks to the EF Core team for making it happen.

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

Increase Performance with Complex Types in Entity Framework Core 8

Tue, 13 Feb 2024 00:00:00 +0000

With the release of .NET 8, we also see the release of Entity Framework Core 8 and a bounty of new features. One of my favorite new features is Complex Types. When data modeling with Entity Framework Core, we may unnecessarily add tables to our database schema because “that’s just how database modeling works”. This can lead to table sprawl, decreased insert performance, and increased query times.

In this post, we’ll explore how to use Complex Types in Entity Framework Core 8 to reduce the number of tables in our schema, simplify inserts, and increase query performance.

What are Complex Types?

Entity Framework Core has long had the concept of “owned types”, which are properties dependent on their parent object. Depending on your data model, these pieces of information only make sense within the context of additional data. For example, in a hypothetical domain, a physical address may only make sense when related to a customer. Otherwise, it is an arbitrary piece of information. Let’s look at how you may model this.

public class Customer  
{  
    public int Id { get; set; }  
    public required string Name { get; set; }  
    public required Address Address { get; set; }  
}

As you may notice, the Address property is used within the Customer definition. Folks familiar with EF Core might assume that there would be an Addresses table, and in previous versions of EF Core, that would have been the case.

In EF Core 8, the modeling process lets us map an Address directly to columns within a Customers table.

create table main.Customers
(
    Id               INTEGER not null
        constraint PK_Customers
            primary key autoincrement,
    Name             TEXT    not null,
    Address_City     TEXT    not null,
    Address_Country  TEXT    not null,
    Address_Line1    TEXT    not null,
    Address_Line2    TEXT,
    Address_PostCode TEXT    not null
);

According to the initial release notes, Complex types have certain characteristics:

Types are not identified or tracked by a key value.
Must only exist as part of the entity and not directly have a DbSet
Can be value or reference types (records or classes).
Can share the same instance across multiple properties* (be careful).

The final bullet states that the same instance is only shared during the manipulation process of in-memory objects. Once the data is read back out, the newly tracked objects will be different instances. This is important because you may encounter unexpected issues if you’re operating under false assumptions.

So, how do you implement a complex type?

[ComplexType]
public class Address
{
    public required string Line1 { get; set; }
    public string? Line2 { get; set; }
    public required string City { get; set; }
    public required string Country { get; set; }
    public required string PostCode { get; set; }
}

You add a ComplexType attribute, of course. Again, note that this class does not have any key.

Saving Complex Types

Using a complex type is as you’d expect. Let’s take a look at a quick usage sample.

Database db = new();

// Complex Type storage of Address
var customer = new Customer
{
    Name = "Khalid Abuhakmeh",
    Address = new()
    {
        Line1 = "1 Fantasy Lane",
        City = "Los Angeles",
        Country = "USA",
        PostCode = "90210",
    }
};
db.Customers.Add(customer);
await db.SaveChangesAsync();

When we look at the Insert SQL statement, we can see a straightforward command.

 INSERT INTO "Customers" ("Name", "Address_City", "Address_Country", "Address_Line1", "Address_Line2", "Address_PostCode")
      VALUES (@p0, @p1, @p2, @p3, @p4, @p5)

That’s one less table needed for our insert statements. That’s great news! What about querying the same model?

Let’s perform the query db.Customers.FirstOrDefault() and see what we get.

SELECT "c"."Id", "c"."Name", "c"."Address_City", "c"."Address_Country", "c"."Address_Line1", "c"."Address_Line2", "c"."Address_PostCode"
FROM "Customers" AS "c"
LIMIT 1

Cool! Querying a single table is great news again.

We can even write LINQ queries like you’d expect from any previous DbContext.

var result = await db
    .Customers
    .Where(x => x.Id == customer.Id)
    .Select(x => x.Address)
    .FirstOrDefaultAsync();

The previous LINQ statement produces the following SQL.

SELECT "c"."Address_City", "c"."Address_Country", "c"."Address_Line1", "c"."Address_Line2", "c"."Address_PostCode"
  FROM "Customers" AS "c"
  WHERE "c"."Id" = @__customer_Id_0
  LIMIT 1

This is awesome.

A quick note about performance claims, it’s important to test any optimization and performance improvements in your own codebase. While generally less tables involved in a transaction are better, there are scenarios that can be less performant. For example, if you use Complex Types to create a monsterous 500+ column table, then you might want to reconsider your approach and it might be less performant than inserting into multiple tables.

Here’s the DbContext for completeness.

using System.ComponentModel.DataAnnotations.Schema;
using Microsoft.EntityFrameworkCore;

namespace EntityFrameworkCoreEight;

public class Database : DbContext
{
    public DbSet<Customer> Customers => Set<Customer>();
    
    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
        => optionsBuilder
            .UseSqlite("Data Source= database.db")
            .LogTo(Console.Write);
}

public class Customer
{
    public int Id { get; set; }
    public required string Name { get; set; }
    public required Address Address { get; set; }
}


[ComplexType]
public class Address
{
    public required string Line1 { get; set; }
    public string? Line2 { get; set; }
    public required string City { get; set; }
    public required string Country { get; set; }
    public required string PostCode { get; set; }
}

Conclusion

Complex types allow you to reduce table sprawl, increase insert performance, and speed up query times. There are many opportunities to review existing schemas and optimize your database. It’s still important to realize you might be dealing with reference objects, so be careful about how you assign and modify objects that may be shared. There are still some outstanding issues with Complex Types, but they are not critical show-stoppers. One of the issues is support for inheritance. It is planned for future versions, but I can live without it now. Despite the minor issues, this is an excellent addition to Entity Framework Core 8.

I hope you enjoyed this blog post, and as always, cheers.

HTML Web Components with Vanilla JavaScript and ASP.NET Core

Tue, 06 Feb 2024 00:00:00 +0000

A general fog of “I hate JavaScript” hovers over the .NET development shops worldwide. While it’s understandable that JavaScript can sometimes be annoying, it has grown significantly recently. One of the areas more ASP.NET Core developers should take note of is Web Components. Web Components allow you to create custom HTML elements for your views that can be one-off or reusable.

With Blazor, ASP.NET Core developers are being exposed to component-based development, but the approach I am going to show you today uses a technique called HTML web components. Unlike Blazor components, these components wrap existing HTML and enhance the contents into something with interactivity. Let’s take a look.

What are HTML Web Components?

Web developer Jim Nielsen wrote a blog post titled “Html Web Components” where he compares the React component model with what he feels is a better way to write Web Components. His UserAvatar example might look familiar to Blazor developers.

<UserAvatar
  src="https://example.com/path/to/img.jpg"
  alt="..."
/>

If you’re getting into web components, you might be tempted to write your web components using this approach, but you might be causing unnecessary issues. What is a UserAvatar? What elements compose this component? How do I style it?

Instead, consider a wrapper component that can enhance the child elements nested within.

<user-avatar>
  <img src="https://example.com/path/to/img.jpg" alt="..." />
</user-avatar>

There are multiple benefits to this approach:

Since elements already exist in the DOM, they can be processed immediately.
Team members can see all the elements and work with them accordingly.
Progressive enhancement. If the Javascript fails on start-up, you still have HTML.

In short, instead of encapsulating HTML within a component, write your HTML web components to augment existing markup. It’s a fantastic technique, and thanks to Jim Nielsen for their blog post. Now, let’s see how we can use this in ASP.NET Core.

The Blazor Counter HTML Web Component

I’ll be recreating Blazor’s counter component to show it doesn’t take much additional effort to write an HTML Web Component. Let’s start with the HTML markup, as it’s the most straightforward implementation part.

<vanilla-counter 
    count="0" 
    href="@Url.Page("Index", "Count")">
    <h1>Counter</h1>
    <p role="status">
        Current count: <span role="figure">0</span>
    </p>
    <button class="btn btn-primary">
        Click me
    </button>
</vanilla-counter>

Note: All web components must have a - in the name to be valid. This is to avoid conflicts with current and future HTML elements.

We have an endpoint that will increment the count for us. I am using an endpoint to show that even HTML Web components can connect to the server, but they can be anything you’d like. If you can write it in JavaScript, a web component can do it. Let’s look at the backend implementation.

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

namespace WebComponentsSample.Pages;

[IgnoreAntiforgeryToken]
public class IndexModel(ILogger<IndexModel> logger) : PageModel
{
    public void OnGet()
    {
    }

    public IActionResult OnPostCount(int count)
    {
        return Content($"{++count}");
    }
}

OK, let’s write our HTML Web Component. It will be the vanilla-counter element we see above. In a Counter.js file, add the following code.

export class Counter extends HTMLElement {
    static observedAttributes = ["count", "href"]
    
    /* lifecycle events */
    connectedCallback() {
        console.log('created');
        this.$button.addEventListener("click", this.increment)
    }

    disconnectedCallback() {
        console.log('destroyed');
        this.$button.removeEventListener("click", this.increment)
    }

    attributeChangedCallback(name, oldValue, newValue) {
        if (name === "count") {
            this.$figure.innerHTML = `${this.#count}`;
        }
    }

    increment = () => {
        this.$button.disabled = true;

        let formData = new URLSearchParams();
        formData.append("count", this.#count);

        fetch(this.#href, {
           method: 'POST',
           headers: {
               'Content-Type': 'application/x-www-form-urlencoded'
           },
           body: formData
        }).then((response) => {
            return response.text();
        }).then((data) => {
            this.#count = parseInt(data);
            this.$button.disabled = false;
            console.log('clicked', this.#count);
        });
    }
    get $button() {
        return this.querySelector("button");
    }

    get $figure() {
        return this.querySelector('[role="figure"]');
    }

    get #count() {
        return parseInt(this.getAttribute("count"));
    }

    set #count(value) {
        this.setAttribute("count", value.toString());
    }
    
    get #href() {
        return this.getAttribute("href");
    }
}

The essential elements, from top to bottom, of this class include the following:

observedAttributes opts into watching specific attributes for the attributeChangedCallback method. When these attributes change in the DOM, the callback gets invoked.
The connectedCallback and disconnectedCallback methods are lifecycle events invoked when the element is added and removed from the DOM. This is important for dynamic element creation as you want to unregister any event listeners to avoid memory leaks.
increment is our logic, which calls the ASP.NET Core endpoint and returns the incremented value.
The rest of the class are helper getters and setters.

We need to change our site.js file to import our Counter.js class and register the custom element.

import {Counter} from "./Counter.js";

window.customElements.define("vanilla-counter", Counter);

You’ll also want to change the _Layout.cshtml file to make sure the site.js file is loaded as a module, which will allow us to use the import keyword.

<script src="~/js/site.js"
        type="module"
        asp-append-version="true">
</script>

Let’s see what it looks like in the browser.

Pretty cool. You can also try the HTML Web Component sample on my GitHub repository. In the screenshot you can see the HTML component is triggering fetch requests to our ASP.NET Core backend.

Conclusion

The web platform has come a long way, and this approach could be helpful to folks building web experiences. The process of building components is relatively straightforward, works with any technology stack, and has advantages regarding progressive enhancement.

I want to thank Jim Nielsen again for the excellent blog post and inspiration for this post. As always, thanks for reading, and cheers. :)

.NET Tasks, List's ForEach, and Problems

Tue, 30 Jan 2024 00:00:00 +0000

I was scrolling the Mastodon timeline when I noticed a fellow .NET developer, Bill Seipel, having an unexpected experience with List.ForEach and async/await. At first glance, I thought he was modifying the collection he was iterating over, but then I realized the issue was much more subtle.

In this post, we’ll discuss what’s happening in a recreation of his code and how you might fix it.

Let’s get started.

List.ForEach and Tasks lead to problems

For those unaware, the List type has a ForEach method, which allows the user to pass an Action<T>. The method passes the iteration’s item, allowing you to execute something similar to a foreach method. In a sense, it’s syntactic sugar. In another, it’s a relic before async/await. Let’s see an example code that can get you in trouble.

List<string> projects = new();  
List<string> measures = ["cm", "m", "km"];  
  
measures.ForEach(async x =>  
{  
     var result = await GetResultOfMeasure(x);  
     projects.Add(result);  
});  
  
Console.WriteLine(projects.Count);  
  
async Task<string> GetResultOfMeasure(string s)  
{  
     await Task.Delay(100);  
     return $"Measured as {s}";  
}

Looking at the code, we see an async/await, so what’s the problem? Well, let’s run the code and see what the result is.

What?! Why did we get a result of 0?

If you’re using a tool like ReSharper or JetBrains Rider you’ll have seen a warning around the async keyword.

Avoid using 'async' lambda when delegate type returns 'void'

Oops! While the Action uses async/await semantics, nothing awaits the iterative process. This means our iterations may or may not be complete by the time we reach the Console.WriteLine statement. Since we use Task.Delay, it’s likely we won’t.

If you’re using something that fluctuates in performance, you will likely pull out your hair due to indeterminate behavior.

So, what’s the fix?

Fixing List.ForEach with ForEachAsync

The most straightforward solution is not to use ForEach but to use a simple for each iteration instead.

List<string> projects = new();
List<string> measures = ["cm", "m", "km"];

foreach (var measure in measures)
{
     var result = await GetResultOfMeasure(measure);
     projects.Add(result);
}

Console.WriteLine(projects.Count);

But honestly, where’s the fun in that?! Another approach is to write a ForEachAsync extension method.

public static class ListExtension
{
     public static async Task ForEachAsync<T>(
          this List<T> collection, 
          Func<T, Task> action)
     {
          foreach (var i in collection) await action(i);
     }
}

From here, you can tweak the original sample code to be sure to await the entire iterative process.

List<string> projects = new();
List<string> measures = ["cm", "m", "km"];

await measures.ForEachAsync(async x =>
{
     var result = await GetResultOfMeasure(x);
     projects.Add(result);
});

Console.WriteLine(projects.Count);

async Task<string> GetResultOfMeasure(string s)
{
     await Task.Delay(100);
     return $"Measured as {s}";
}

There you have it. Pretty cool, right?!

Conclusion

This particular issue is insidious as it all compiles and generally looks “correct.” With good tooling, like that provided by JetBrains, you get a hint as to a potential issue lurking in your code, but it doesn’t scream at you since it’s still code that compiles. It might make sense for .NET to include a ForEachAsync method on List, but at this point, it might also make sense to Obsolete the method entirely since it likely does more harm than good.

What do you think? Let me know if you’ve ever run into this issue. You can see the full thread on Mastodon here, along with debugging videos describing what is happening.

Thanks for reading and sharing my work with friends and colleagues. Cheers.

How To Use Blazor Server-Rendered Components with HTMX

Tue, 23 Jan 2024 00:00:00 +0000

A few new tricks have shipped with the .NET 8 release, and I’d like to take this time to experiment with them. Specifically, I wanted to see if folks investing in a Blazor component library could still use the excellent HTMX library. If you want to write even less JavaScript, this blog post will be right up your alley.

This post will explore how to take a server-rendered component and give it some client-side flair without needing web sockets or web assembly. We’ll even explore rewriting the Counter component found in the Blazor template and building it with HTMX in mind. Let’s go!

What is HTMX?

For folks familiar with Blazor’s interactive server mode, SignalR, aka Web sockets, the HTMX model isn’t much different.

The client communicates with the server, and the server retains stateful information. The big difference is that HTMX takes a hypermedia approach, meaning it leans on the web’s traditional request/response nature. There are no persistent connections between the client and the server. Any DOM element can initiate a request, wait for the server to process it, and then respond with appropriate HTML. Once the HTML payload is received, it is swapped into the current DOM. While the concept is simple to understand, it is powerful in practice.

What are Blazor Server-Rendered Components?

With the .NET 8 release, folks can opt-in to multiple render modes. The first in the list of render modes is Static, although that’s not entirely accurate.

Static rendering implies you could compile components and assets into HTML at build time. In the case of Blazor, “ Static” rendering is more comparable to its contemporary approaches of MVC and Razor Pages. When a request to a page or component is made, the server renders the component and its component graph and then responds with HTML.

These Blazor components are all HTML, meaning they can only use HTML features and not the same interactive model you may expect from Interactive Server or Interactive WebAssembly modes.

The advantage to these Components is they are lightweight payloads, fast to render, and can even be streamed via stream rendering.

Let’s Use HTMX with Blazor

Before we port our Counter component to use HTMX, we must set up our project to make Blazor play nicely with HTMX.

The first step is to add HTMX to our App.razor file. This is the app shell file which has our HTML structure.

<!DOCTYPE html>  
<html lang="en">  
  
<head>  
    <meta charset="utf-8"/>  
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>  
    <base href="/"/>  
    <link rel="stylesheet" href="bootstrap/bootstrap.min.css"/>  
    <link rel="stylesheet" href="app.css"/>  
    <link rel="stylesheet" href="BlazorHtmx.styles.css"/>  
    <link rel="icon" type="image/png" href="favicon.png"/>  
  
    <script defer src="_framework/blazor.web.js"></script>  
    <script defer src="https://unpkg.com/htmx.org@1.9.8"></script>  
    <script defer src="js/htmx-blazor.js"></script>  
    <HeadOutlet/>  
</head>  
<body>  
<Routes/>  
</body>  
</html>

We’ll also need to write a bit of JavaScript to tie into Blazor’s enhanced rendering mode.

// An enhanced load allows users to navigate between different pages  
Blazor.addEventListener("enhancedload", function () {  
    // HTMX need to reprocess any htmx tags because of enhanced loading  
    htmx.process(document.body);  
});

Now, let’s set up our HtmxCounter component. In a file, add the following Blazor component code. You’ll notice that HTMX uses hx-* attributes to define the behavior of DOM elements. It’s easy to pick up and can add functionality quickly. (Not to brag, but I got this sample working on the first try. 🤩)

<div class="counter">
    <p role="status">Current count: @State.Value</p>
    <button class="btn btn-primary"
            hx-post="/count"
            hx-target="closest .counter"
            hx-swap="outerHTML">
        Click me
    </button>
</div>

@code {
    [Parameter, EditorRequired] 
    public HtmxCounterState State { get; set; } = new();
    
    public class HtmxCounterState
    {
        public int Value { get; set; } = 0;
    }
}

Next, let’s look at our endpoint holding on to state. Note that this use of state management is only for demo purposes. I recommend user-scoped state management like a database limited to a single user.

In your Blazor’s Program.cs file, you’ll need to register the state for our component.

builder.Services
    .AddSingleton<HtmxCounter.HtmxCounterState>();

Next, we’ll need the endpoint to increment and render our component HTML fragment.

app.MapPost("/count",
    (HtmxCounter.HtmxCounterState value) =>
    {
        value.Value++;
        return new RazorComponentResult<HtmxCounter>(
            new { State = value }
        );
    });

Finally, let’s add our component to a Blazor server-rendered page.

@page "/"
@inject HtmxCounter.HtmxCounterState CounterState

<PageTitle>Home</PageTitle>

<h1>Hello, world!</h1>

<div class="mb-4">
    <HtmxCounter State="CounterState"/>
</div>

@code {
    protected override void OnInitialized()
    {
        // reset counter on page reloads
        CounterState.Value = 0;
    }
}

Let’s see what happens when we load our page.

That’s pretty cool. From a client perspective, you can’t tell which implementation uses WebSockets and which is using HTMX. That’s amazing if you ask me. The HTMX implementation will also be cheaper in the long run as it requires no more infrastructure than you currently have.

If you want to check out the sample, you can get the solution on my GitHub repository and a few more samples of using HTMX with Blazor.

Conclusion

Server-rendered components are an excellent addition to the Blazor toolbox and open up the possibility of using your component library with something as cool as HTMX. I hope you try this sample and let me know what you think.

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

How to use IAsyncEnumerable with Blazor Stream Rendering

Tue, 16 Jan 2024 00:00:00 +0000

With the release of .NET 8, one killer feature will immediately increase the responsiveness of your APIs and Blazor applications: the ability to stream responses. Yes, you could stream responses before, but it’s never been easier with support for IAsyncEnumerable on API endpoints and the use of StreamRenderingAttribute on your Blazor United applications.

This post will explore why you want to use IAsyncEnumerable and StreamRendering to get the fastest Time to first byte (TTFB) out of your ASP.NET Core web applications. Let’s get started.

What is IAsyncEnumerable?

The interface IAsyncEnumerable<T> is a newish interface designed with the idea that retrieving each element within the iteration is an asynchronous task. This is different than a typical Task<IEnumerable> as the operation to retrieve the enumerable is considered one step. If you’ve used any data-access layer, you’ve likely invoked methods like ToListAsync or ToArrayAsync, invoking a request to your database and materializing the result in a single operation. Thinking about the same operation with IAsyncEnumerable, the process will first execute the query and then materialize each record as you enumerate through the collection. This allows you to start using data as it is received rather than waiting for data to buffer in memory. This leads to more efficient use of resources and faster response times.

Let’s take a look at a simple example.

await foreach (var number in RangeAsync(1, 100))
{
    Console.WriteLine(number);
}

static async IAsyncEnumerable<Number> RangeAsync(int start, int count)
{
    for (int i = 0; i < count; i++)
    {
        await Task.Delay(i);
        yield return new Number(start + i);
    }
}

record Number(int Value);

You’ll notice that IAsyncEnumerable also has C# syntax support with the availability of await foreach. That makes it straightforward to consume in an existing codebase.

What is Stream Rendering?

While recently added to Blazor, stream rendering is not a new concept. Most browser clients support a Transfer-Encoding of chunked. We can get an idea of what this means to web developers from Wikipedia.

Chunked transfer encoding is a streaming data transfer mechanism available in Hypertext Transfer Protocol version 1.1, defined in RFC 9112 §7.1. In chunked transfer encoding, the data stream is divided into a series of non-overlapping “ chunks”. The chunks are sent out and received independently of one another.

Cool! As application developers, we can take advantage of this for both API endpoints and, in the case of Blazor, for streaming HTML markup from our component-based pages.

Let’s look at streaming from a Minimal API endpoint.

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

app.MapGet("/", () => "Hello World!");

app.MapGet("/range", () => 
    Results.Ok(new
    {
        totalCount = 100,
        results = RangeAsync(1, 100)
    }));

app.Run();

static async IAsyncEnumerable<Number> RangeAsync(int start, int count)
{
    for (int i = 0; i < count; i++)
    {
        await Task.Delay(i);
        yield return new Number(start + i);
    }
}

record Number(int Value);

Running this sample in a browser, you’ll see the results get output to the page, even before getting a semantically complete JSON object.

It’s important to understand that a client must understand and support chunking to take advantage of the performance benefits.

Stream Rendering and IAsyncEnumerable for Blazor

While Blazor supports stream rendering for HTML elements, you need to consider how you’ll be invoking an IAsyncEnumerable within a component’s lifecycle. While you may be tempted to do the following in your Blazor components, it will result in an error.

@* ERROR: The 'await foreach' statement can only be used in a method or lambda marked with the 'async' modifier *@
@await foreach (var forecast in forecasts)
{
	<tr>
		<td>@forecast.Date.ToShortDateString()</td>
		<td>@forecast.TemperatureC</td>
		<td>@forecast.TemperatureF</td>
		<td>@forecast.Summary</td>
	</tr>
}

The correct approach to using IAsyncEnumerable within a Blazor component comes down to three essential considerations:

A collection variable must first exist, as you’ll be appending to it, not replacing it altogether.
The IAsyncEnumerable must be awaited within an async component lifecycle method such as OnInitializedAsync.
The method StateHasChanged must be invoked to tell Blazor to flush HTML to the response. This can be after each iteration or on some determined interval.

Let’s see what that looks like in a sample. I’ve tweaked the Weather.razor sample that comes with the Blazor template.

@page "/weather"
@attribute [StreamRendering]

<PageTitle>Weather</PageTitle>

<h1>Weather</h1>

<p>This component demonstrates showing data.</p>

@if (forecasts is { Count : 0 })
{
    <p>
        <em>Loading...</em>
    </p>
}
else
{
    <table class="table">
        <thead>
        <tr>
            <th>Date</th>
            <th>Temp. (C)</th>
            <th>Temp. (F)</th>
            <th>Summary</th>
        </tr>
        </thead>
        <tbody>
        @foreach (var forecast in forecasts)
        {
            <tr>
                <td>@forecast.Date.ToShortDateString()</td>
                <td>@forecast.TemperatureC</td>
                <td>@forecast.TemperatureF</td>
                <td>@forecast.Summary</td>
            </tr>
        }
        </tbody>
    </table>
}

@code {
	//1. the collection we'll be adding to
    private readonly List<WeatherForecast> forecasts = new();

    protected override async Task OnInitializedAsync()
    {
        forecasts.Clear();
        // 2. invoking the IAsyncEnumerable implementation
        await foreach (var forecast in GetForecasts())
        {
            forecasts.Add(forecast);
            // 3. Calling StateHasChanged to flush
            StateHasChanged();
        }
    }

    static async IAsyncEnumerable<WeatherForecast> GetForecasts()
    {
        var startDate = DateOnly.FromDateTime(DateTime.Now);
        var summaries = new[]
        {
            "Freezing", "Bracing", "Chilly",
            "Cool", "Mild", "Warm", "Balmy",
            "Hot", "Sweltering", "Scorching"
        };

        for (var index = 0; index <= 5; index++)
        {
            await Task.Delay(1000);
            yield return new WeatherForecast
            {
                Date = startDate.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = summaries[Random.Shared.Next(summaries.Length)]
            };
        }
    }

    private class WeatherForecast
    {
        public DateOnly Date { get; set; }
        public int TemperatureC { get; set; }
        public string? Summary { get; set; }
        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
    }

}

There you have it. You are now using an IAsyncEnumerable within stream rendering to get the most performance out of your Blazor applications.

Conclusion

Streaming a response to the user can increase the perceived performance of your applications. Still, it’s important to remember that you also need to improve the performance of your dependencies to get the most out of this approach. While it may make your app more performant to stream HTML to the client as soon as possible, that effort can be undercut by a slow dependency such as a database or web service. Give it a try, and let me know what performance increases you see in your applications.

Thanks for reading and sharing my posts with friends and colleagues. Cheers.

View Transitions API with ASP.NET Core and HTMX

Tue, 09 Jan 2024 00:00:00 +0000

I recently hosted JetBrains JavaScript Day with guest speaker Fred K. Schott of Astro fame, who spoke about the View Transitions API being introduced in modern browsers. You should watch the video, which will give you a primer for this blog post; frankly, it’s such an incredible presentation.

In this post, we’ll explore how to mix three remarkable web technologies to get a fantastic user experience with little to no effort on your part. Of course, I’m speaking about using ASP.NET Core Razor Pages, HTMX, and View Transitions to smooth the transition between pages and reduce the perceived performance of those hops between pages.

Let’s get started.

What are View Transitions?

View Transitions is a new approach that gives web designers more native-like animated transitions between navigation events. These navigation events can be complete page transitions or elements moving from one part of the page to another. As web developers, we can focus on performance practices while allowing the web platform to do a lot of the heavy lifting of animation.

While I could explain the technical nitty-gritty of the View Transitions API, Jake Archibald did an excellent job explaining it better than I ever could.

In short, we can decide how a page visually transitions from one state to another using JavaScript and CSS animations.

Why HTMX?

While an argument could be made that you don’t need HTMX here, there are a few reasons I recommend it when working with ASP.NET Core Razor Pages.

First, the hx-boost feature of HTMX allows us to squeeze more performance out of our page transitions. The body element from a new request is swapped into our existing page, thus skipping the expensive step of parsing CSS and JavaScript resources.

Second, since HTMX 1.9.0, we can specify an additional transition:true value on hx-swap attributes to opt in to view transitions. This is simpler than the imperative style mentioned in the previous explainer above.

Finally, HTMX brings more valuable approaches we’ll use as we build our ASP.NET Core application.

View Transition Sample

Let’s first see this sample in action and walk through the steps necessary to get View Transitions into your application.

Pretty cool. Each navigation performs a transition with a cool slide animation, which is commonly used in native-style applications. Additionally, the visual shell of the site does not animate but instead stays in place.

Let’s walk through the steps to get this into your applications, and you’ll be surprised that no C# will be involved in the following guide.

The first step is to add HTMX to your head element. You can install HTMX via an asset package manager like NPM or a CDN provider. For simplicity, I’ve included the CDN version below.

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

Next, you’ll want to apply the hx-boost attribute to a container that has anchor tags as children. In the case of this demo, I added the attribute to the body tag as I want all anchors to perform the View Transition animation.

<body hx-boost="true" hx-swap="transition:true">

You’ll also notice the body tag has an hx-swap attribute with a transition:true value. This marks our element as the root View Transition element.

Finally, we need to add some CSS animations and values to our site’s stylesheet.

@keyframes fade-in {
  from { opacity: 0; }
}

@keyframes fade-out {
  to { opacity: 0; }
}

@keyframes slide-from-right {
  from { transform: translateX(90px); }
}

@keyframes slide-to-left {
  to { transform: translateX(-90px); }
}

/* define animations for the old and new content */
::view-transition-old(slide-it) {
  animation: 180ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
  600ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-left;
}
::view-transition-new(slide-it) {
  animation: 420ms cubic-bezier(0, 0, 0.2, 1) 90ms both fade-in,
  600ms cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
}

body {
  margin-bottom: 60px;
  view-transition-name: slide-it;
}

.navbar {
  view-transition-name: main-header-text;
  animation: none;
  mix-blend-mode: normal;
}

footer {
  view-transition-name: footer;
  animation: none;
  mix-blend-mode: normal;
}

We’ve created some basic animations that we apply to each element. Each rule must get a unique view-transition-name value so that the View Transitions API knows how to identify each element uniquely.

That’s it! We now have the implementation of the example you saw previously.

Conclusion

It’s shockingly simple to get a pleasant native-like experience in your ASP.NET Core applications with a bit of HTMX and take advantage of the advancements in the web platform. The View Transitions API is still experimental and not fully supported across all browsers, but most Chromium-based browsers and Firefox already support it.

If you’d like to run this sample on your development environment, I’ve created a GitHub repository where you can clone and try it.

Thank you for reading my blog posts and sharing them with colleagues. Cheers.

References

How to Write a .NET Markdig Extension for Markdown Processing

Tue, 02 Jan 2024 00:00:00 +0000

Markdown is a powerful writing format with simplicity at its core. It’s no surprise that it is as popular as it is since it can help authors focus more on the art of writing rather than the aesthetics of their work. While there is a standard specification for the language, there are extensions to the Markdown syntax that can enhance the authoring experience in niche contexts. For example, LaTex support for mathematics, improved media support for online services like YouTube, and diagram support via Mermaid for all aspiring software architects.

With Markdown, if you can write it, you can parse and translate it to a desired output. In this post, we’ll explore the Markdig library by author Alexandre Mutel, which is .NET’s fastest and most powerful CommonMark-compliant Markdown parser. Most importantly, it’s also extensible!

What is Markdown and Markdig?

For folks new to Markdown, it is a text-based format used to help writers focus on the structure and content of their work rather than the aesthetics of the work.

Aesthetics include font choices, colors, font sizing, and overall layout concerns. While aesthetics can help tell a more immersive story, they can hinder the writing process if introduced too early.

Markdown focuses on some familiar structural writing tropes and allows you to express them using simplified structures and symbols amongst code. These include headers, links, emphasis, lists, and more. Markdown gets its name because, typically, the format is converted into markup, also known as HTML. Although, Markdown can have many targets, including PDFs, presentation slides, and much more. Your imagination is the limit.

As the introduction mentions, Markdig is a .NET library aimed at helping developers process and transform markdown files. It’s a drop-in and ready library for most needs but also has extensibility options.

Writing a Markdig Inline Parser Extension

There are three parts to writing an extension for Markdig: Markdown syntax, the processing pipeline, and the syntax parser. We’ll walk through all three parts and why they are essential. Let’s start with first describing the intent of our extension.

Given the following syntax, we want to parse any matching token and replace it with a GitHub username link.

this is a link to [github:khalidabuhakmeh]  
and [github:maartenba]

with a resulting output of HTML.

<p>this is a link to <a href="https://github.com/khalidabuhakmeh"/>khalidabuhakmeh</a>
and <a href="https://github.com/maartenba"/>maartenba</a></p>

To parse this with markdown with Markdig, you must first install the NuGet package Markdig.

dotnet add package Markdig

Next, we’ll need to set up a MarkdownPipeline using a MarkdownPipelineBuilder.

using System.Text.RegularExpressions;
using Markdig;
using Markdig.Helpers;
using Markdig.Parsers;
using Markdig.Renderers;
using Markdig.Syntax.Inlines;

var pipeline = new MarkdownPipelineBuilder()
    .Use<GitHubUserProfileExtension>()
    .Build();

var html = Markdown
    .ToHtml("""
            this is a link to [github:khalidabuhakmeh]
            and [github:maartenba]
            """, pipeline);

Console.WriteLine(html);

The pipeline is a series of syntax parsers that run over the markdown document, switching out the syntax for the final output.

You’ll notice the mention of GitHubUserProfileExtension when building the pipeline. This is our new extension. Let’s take a look at the implementation.

public class GitHubUserProfileExtension : IMarkdownExtension
{
    public void Setup(MarkdownPipelineBuilder pipeline)
    {
        if (!pipeline.InlineParsers.Contains<GitHubUserProfileParser>())
        {
            pipeline.InlineParsers.Insert(0, new GitHubUserProfileParser());
        }
    }

    public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer)
    {
    }
}

The extension class is the opportunity to add the GitHubUserProfileParser to the collection of InlineParsers. Parsers take incoming markdown syntax and process the value to its final result.

In my case, I insert the new parser at the beginning of the collection. Parsers execute in the order they are registered. Since I’m reusing the syntax of a link in Markdown, I want to ensure I can process the token before any other parser does. If your parser operates on unique syntax, you can add the parser anywhere in the collection.

Now, let’s get to the parser.

public partial class GitHubUserProfileParser : InlineParser
{
    public GitHubUserProfileParser()
    {
        OpeningCharacters = new[] { '[' };
    }
    
    public override bool Match(InlineProcessor processor, ref StringSlice slice)
    {
        var precedingCharacter = slice.PeekCharExtra(-1);
        if (!precedingCharacter.IsWhiteSpaceOrZero())
        {
            return false;
        }
        
        var regex = GithubTagRegex();
        var match = regex.Match(slice.ToString());
        
        if (!match.Success)
        {
            return false;
        }
        
        var username = match.Groups["username"].Value;
        var literal = $"<a href=\"https://github.com/{username}\"/>{username}</a>";
        
        processor.Inline = new HtmlInline(literal)
        {
            Span =
            {
                Start = processor.GetSourcePosition(slice.Start, out var line, out var column)
            },
            Line = line,
            Column = column,
            IsClosed = true
        };
        processor.Inline.Span.End = processor.Inline.Span.Start + match.Length - 1;
        slice.Start += match.Length;
        return true;
    }

    [GeneratedRegex(@"\[github:(?<username>\w+)]")]
    private static partial Regex GithubTagRegex();
}

There are a few crucial elements to a parser, but none more critical than the OpeningCharacters collection. These characters are what trigger entry into the Match method. Without setting this value, your parser will be responsible for parsing all the text. I made this mistake, but Alexandre Mutel was kind enough to point out my mistake.

Next, in the Match method, we get a reference to a StringSlice, which allows us to check if we’ve matched our expected token. You can look forward and backward here in the provided string, or my case, use a source-generated Regex to match the token.

Once matched, you can create an inline representation of the value to be replaced. I want to replace the token with an anchor tag pointing to a user’s GitHub profile. You also need to calculate where the token begins and ends, and you can do that using the GetSourcePosition method.

I also make sure that I set IsClosed to true. This lets other parsers know that I’ve handled this token and that they should not attempt to modify the token. This depends on your use case, but for this one, this is the end of processing for this token.

Finally, we set the slice.Start position after the token so we don’t keep processing it. If you’re experiencing an exception with a “The parser is in an invalid infinite loop” message, you’ve likely forgotten to move the starting position past the current token.

It’s that easy! Here’s the complete sample in its entirety.

using System.Text.RegularExpressions;
using Markdig;
using Markdig.Helpers;
using Markdig.Parsers;
using Markdig.Renderers;
using Markdig.Syntax.Inlines;

var pipeline = new MarkdownPipelineBuilder()
    .Use<GitHubUserProfileExtension>()
    .Build();

var html = Markdown
    .ToHtml("""
            this is a link to [github:khalidabuhakmeh]
            and [github:maartenba]
            """, pipeline);

Console.WriteLine(html);

public class GitHubUserProfileExtension : IMarkdownExtension
{
    public void Setup(MarkdownPipelineBuilder pipeline)
    {
        if (!pipeline.InlineParsers.Contains<GitHubUserProfileParser>())
        {
            pipeline.InlineParsers.Insert(0, new GitHubUserProfileParser());
        }
    }

    public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer)
    {
    }
}

public partial class GitHubUserProfileParser : InlineParser
{
    public GitHubUserProfileParser()
    {
        OpeningCharacters = new[] { '[' };
    }
    
    public override bool Match(InlineProcessor processor, ref StringSlice slice)
    {
        var precedingCharacter = slice.PeekCharExtra(-1);
        if (!precedingCharacter.IsWhiteSpaceOrZero())
        {
            return false;
        }
        
        var regex = GithubTagRegex();
        var match = regex.Match(slice.ToString());
        
        if (!match.Success)
        {
            return false;
        }
        
        var username = match.Groups["username"].Value;
        var literal = $"<a href=\"https://github.com/{username}\"/>{username}</a>";
        
        processor.Inline = new HtmlInline(literal)
        {
            Span =
            {
                Start = processor.GetSourcePosition(slice.Start, out var line, out var column)
            },
            Line = line,
            Column = column,
            IsClosed = true
        };
        processor.Inline.Span.End = processor.Inline.Span.Start + match.Length - 1;
        slice.Start += match.Length;
        return true;
    }

    [GeneratedRegex(@"\[github:(?<username>\w+)]")]
    private static partial Regex GithubTagRegex();
}

Conclusion

I love Markdown, and Markdig helps .NET developers embrace the wonders of the specification. The extensibility of Markdig also allows .NET developers to go beyond the CommonMark specification and build unique Markdown flavors for their specific purpose. As you’ve seen, it only takes a few classes to extend the functionality of a markdown document beyond the already impressive extensions included with Markdig.

I hope you enjoyed this post, and thanks to Alexandre Mutel and other Markdig contributors for their fantastic work. Thanks for reading and sharing my posts with friends and colleagues.

Faster .NET Database Integration Tests with Respawn and xUnit

Tue, 26 Dec 2023 00:00:00 +0000

The nuances of data access are myriad, so when writing tests around complex data scenarios, I recommend just working with the actual database. Over time, you’ll find yourself with more valuable tests but, often, relatively slower tests compared to their in-memory alternatives. Like all things, there are trade-offs, but you can still strategize in making your tests faster.

In this post, I’ll show you how to take advantage of xUnit class fixtures and the OSS library Respawn to manage the state of your database across tests. This will help speed up your tests when faster steps replace a few expensive ones.

What is Respawn?

Respawn is a utility library designed to help developers reset databases to an “initial state”. With some configuration, Respawn can intelligently reset a database for testing use cases.

Other strategies might employ complete database tear-downs, complex transaction management, or expensive Docker containerization strategies. When mixed with your database management strategy around database migrations, look-up tables, and other stateful database elements, the overhead can compound over time and hurt the developer feedback loop many crave from an excellent test suite.

Respawn allows you to choose which tables and schemas to ignore in the reset process.

var respawner = await Respawner.CreateAsync(connection, new RespawnerOptions
{
    TablesToIgnore = new Table[]
    {
        "sysdiagrams",
        "tblUser",
        "tblObjectType",
        new Table("MyOtherSchema", "MyOtherTable")
    },
    SchemasToExclude = new []
    {
        "RoundhousE"
    }
});

It also supports multiple database providers, including Microsoft SQL Server, Postgres, MySQL, Oracle, and Informix.

Using xUnit fixtures (which we’ll see later), you only need to call a single method to reset the database.

await respawner.ResetAsync("MyConnectionStringName");

After every reset, your database will return to its initial state and be ready for another round of test assertions.

xUnit ReSpawn Fixture

I’ve created a sample Respawn and xUnit project with all the code in this blog post so you can try it out in your development environment.

For folks following along in the post, I’m using a GlobalUsing.cs file for namespaces and some C# 12 (.NET 8) features. Here are the required namespaces.

global using Dapper;
global using Dapper.Contrib.Extensions;
global using Microsoft.Data.SqlClient;
global using Respawn;
global using Xunit;
global using Xunit.Abstractions;

When working with Respawn, you’ll need a fixture. In the world of xUnit, fixtures are shared resources across test classes. In the case of this sample, we’ll create a DatabaseFixture, which will manage the database using a Respawner instance.

namespace Spawn;

// ReSharper disable once ClassNeverInstantiated.Global
public class DatabaseFixture : IAsyncLifetime
{
    private const string DatabaseName = "test";
    
    private readonly Dictionary<string, string> connectionStrings = new()
    {
        { DatabaseName, $"Data Source=localhost,11433;Database={DatabaseName};User Id=sa;Password=Pass123!;Encrypt=FALSE;" },
        { "master", "Data Source=localhost,11433;Database=master;User Id=sa;Password=Pass123!;Encrypt=FALSE;" }
    };

    public async Task<SqlConnection> GetOpenConnectionAsync(string databaseName = DatabaseName)
    {
        var sqlConnection = new SqlConnection(connectionStrings[databaseName]);
        await sqlConnection.OpenAsync();
        return sqlConnection;
    }

    private Respawner respawn = null!;

    public async Task InitializeAsync()
    {
        await MigrateAsync();

        respawn = await Respawner.CreateAsync(connectionStrings[DatabaseName],
            new RespawnerOptions
            {
                DbAdapter = DbAdapter.SqlServer
            });
    }

    private async Task MigrateAsync()
    {
        // only doing this for the sample,
        // you'll likely already have the database created somewhere
        {
            try
            {
                await using var connection = await GetOpenConnectionAsync("master");
                await connection.ExecuteAsync(
                    // lang=SQL
                    $"""
                     IF NOT EXISTS (SELECT [name] FROM sys.databases WHERE [name] = N'{DatabaseName}')
                        CREATE DATABASE {DatabaseName};
                     """
                );
            }
            catch (SqlException e)
            {
                throw new Exception("Create and run the container found in the docker-compose.yml", e);
            }
        }

        {
            await using var connection = await GetOpenConnectionAsync();
            await connection.ExecuteAsync(
                // lang=SQL
                """
                IF NOT EXISTS (SELECT * FROM sys.objects WHERE object_id = OBJECT_ID(N'[dbo].[People]') AND type in (N'U'))
                  BEGIN
                      CREATE TABLE People
                      (
                          ID INT PRIMARY KEY IDENTITY,
                          FirstName NVARCHAR(50),
                          LastName NVARCHAR(50),
                          Age INT,
                          Email NVARCHAR(255)
                      );
                  END;
                """);
        }
            
    }

    public Task ResetAsync()
        => respawn.ResetAsync(connectionStrings[DatabaseName]);

    public async Task DisposeAsync()
    {
        await using var connection = await GetOpenConnectionAsync("master");
        await connection.ExecuteAsync(
            // lang=SQL
            $"""
            IF EXISTS (SELECT [name] FROM sys.databases WHERE [name] = N'{DatabaseName}')
            BEGIN
                ALTER DATABASE {DatabaseName}
                SET SINGLE_USER -- Disallow multi-user access.
                WITH ROLLBACK IMMEDIATE -- Rollback any transaction in progress.
                DROP DATABASE {DatabaseName};
            END;
            """
        );
    }
}

We must utilize the IAsyncLifetime interface in xUnit to call Respawn’s asynchronous methods. I’ve also added a helper method of GetOpenConnectionAsync to make it easier to write tests using the fixture.

Note that the migration strategy in the fixture does not use any particular approach commonly found in the .NET ecosystem. You’ll likely use EF Core migrations, Roundhouse, DbUp, or another migration strategy. Adjust the code for your particular use case. I’ve also taken the steps to create the database if it does not currently exist. Creating the database might be optional based on your development environment.

Now let’s use our fixture in a new test class.

namespace Spawn;

public class RespawnTests(DatabaseFixture database, ITestOutputHelper output)
    : IClassFixture<DatabaseFixture>, IAsyncLifetime
{
    [Fact]
    public async Task Can_Insert_Person_Into_People()
    {
        await using var connection = await database.GetOpenConnectionAsync();
        await connection.InsertAsync<Person>(new()
        {
            FirstName = "Khalid",
            LastName = "Abuhakmeh",
            Age = 40,
            Email = "khalid@example.com"
        });

        var person = await connection.QueryFirstAsync<Person>("select top 1 * from people");
        var total = await connection.ExecuteScalarAsync("select count(ID) from People");

        output.WriteLine($"{person.FirstName} says hi!");

        Assert.NotNull(person);
        Assert.Equal(expected: 1, actual: total);
    }

    [Fact]
    public async Task People_Table_Is_Always_Empty()
    {
        await using var connection = await database.GetOpenConnectionAsync();
        var person = await connection.QueryFirstOrDefaultAsync<Person>("select top 1 * from people");
        Assert.Null(person);
    }

    public Task InitializeAsync()
        => Task.CompletedTask;

    public Task DisposeAsync()
        => database.ResetAsync();
}

We use the IAsyncLifetime interface again to ensure that our database is reset after each test is run. In the DisposeAsync method, we invoke the fixture’s ResetAsync method, which resets our database to its initial state. That’s it! Easy peasy.

On my development machine, the total time of the tests is about 250ms, with the bulk of the time spent creating and tearing down my database for the sample. In your use case, you can cut the cost of database creation and teardown by creating the database outside the scope of the class fixture.

Conclusion

With Respawn and xUnit class fixtures, you can significantly improve your integration test performance and get a tighter feedback loop. You also get the added value of knowing your code is testing against the “real” thing. Integration tests can help catch behavioral changes in the underlying database technology and find issues with queries, and database features you’d otherwise miss when working with stubs.

I hope you found this post helpful, and please give the sample a try. I’ve set it up so you can run through this sample in seconds, and it should give you a great jumping-off point.

Thanks for reading and sharing my posts with friends and colleagues. Cheers.

MemoizR - Declarative Structured Concurrency for C#

Tue, 19 Dec 2023 00:00:00 +0000

Recently, I’ve been focusing on the front-end side of building web applications with topics like React Hooks and Angular Signals. It’s a fascinating data model that can make working with data dependency graphs much more straightforward.

To my surprise, other folks in the .NET community have also been inspired by the work happening in the frontend space. While scanning NuGet, I found MemoizR, a library that takes inspiration from the frontend world to bring the concept of dynamic lazy memoization to .NET developers.

In this post, we’ll see a short example using the library and explain the sample output. Let’s go!

What is MemoizR?

According to the author, Timon Krebs, MemoizR is a declarative structured concurrency implementation for .NET that simplifies (and enhances) standard data flow methods across multiple threads. These methods include error handling, branching logic, and data mutation. Doing so helps developers manage concurrency more efficiently for simple to complex multi-thread scenarios.

Critical features of MemoizR include dynamic lazy memoization, which determines if values need to be reevaluated. Another feature is declarative structured concurrency, which makes building and handling scenarios more straightforward. Regarding scenarios, MemoizR also builds a dependency graph, which helps reduce unnecessary computations if a particular branch has not been affected by changes. These features also lead to automatic synchronization and improved overall performance.

Let’s look at an example application.

Hello MemoizR Sample

To start with MemoizR, you must install the latest version into a new Console project. As of this post, MemoizR is still in prerelease, so you should enable prerelease visibility in your NuGet tool window. You may also run the following command.

dotnet add package MemoizR --version 0.1.0-rc4

Once you install the dependency, paste the following code into the Program.cs file of the project.

using MemoizR;

var f = new MemoFactory();

var one = f.CreateSignal(2);
var two = f.CreateSignal(2);

var squareOne = f.CreateMemoizR(async () =>
{
    var value = await one.Get();
    Console.WriteLine($"Square One: {value}");
    return Math.Pow(value, 2);
});

var squareTwo = f.CreateMemoizR(async () =>
{
    var value = await two.Get();
    Console.WriteLine($"Square Two: {value}");
    return Math.Pow(value, 2);
});

var final = f.CreateMemoizR(async () =>
{
    var result = await squareOne.Get() + await squareTwo.Get();
    Console.WriteLine("Add Squares");
    return result;
});


while (true)
{
    Console.Write($"Set one (current: {await one.Get()}):");
    var user1 = Console.ReadLine();
    if (user1 is not null && int.TryParse(user1, out var value)) {
        await one.Set(value);
    }
    
    Console.Write($"Set two (current: {await two.Get()}):");
    var user2 = Console.ReadLine();
    if (user2 is not null && int.TryParse(user2, out value)) {
        await two.Set(value);
    }

    var result = await final.Get();
    Console.WriteLine($"Result is {result}.\n");
}

This sample aims to show the dependency graph in action by changing the values of one and two. We’ll execute the following scenarios from this app:

Initial run
Change the value of one and not two
Change the value of two and not one
Change no values.

We should see the following outputs reflecting which parts of the graph were executed.

Let’s start with the initial run’s output.

Set one (current: 2):
Set two (current: 2):
Square One: 2
Square Two: 2
Add Squares
Result is 8.

You can see all parts of our graph executed. Now, let’s only change the value of one. You’ll notice only half of the graph dependent on the one value is executed.

Set one (current: 2):3
Set two (current: 2):
Square One: 3
Add Squares
Result is 13.

Now let’s only change two. We should see the opposite is true.

Set one (current: 3):
Set two (current: 2):1
Square Two: 1
Add Squares
Result is 10.

Finally, let’s not change any values. Our graph should not execute any nodes, as it’s value is unchanged.

Set one (current: 3):
Set two (current: 1):
Result is 10.

Cool!

Conclusion

This library is still early but shows much promise for building complex multi-threaded scenarios where elements may or may not change. As you say in the sample, the code is easy to follow and the flow is easily modifiable. I think the author has something interesting here and I hope to see how they evolve it over time.

I hope you give MemoizR a try and let me know what you think. As always, thanks for reading and sharing my posts. Cheers :)

Testing Typesense search with Testcontainers and .NET

Tue, 12 Dec 2023 00:00:00 +0000

Search is an essential part of any modern application. Without a first-class emphasis on great search, many applications aren’t much better than a spreadsheet. Luckily for application developers, we’re spoiled for options for delivering an excellent search experience to our users. One of the options I’ve been playing with recently is Typesense, which aims to be an open-source alternative to commercial-service Algolia.

In this post, we’ll look at how you can play around with Typesense within the context of .NET using Testcontainers. Testcontainers is a library that makes spinning up containers so simple you’ll wonder how you ever lived without it. Let’s get started.

What is Typesense

Search is challenging to get right, with many commercial options. The most notable commercial offerings include Elasticsearch and Algolia, which come with licensing costs or are search-as-a-service solutions. While great choices in their own right, the options might not fit your particular goals for finding a search solution. Typesense is an open-source alternative to the aforementioned options, with many great features developers expect from a search provider.

Typesense provides development teams with a search engine that can perform search-as-you-type, autocomplete, faceted navigation, geo-search, recommendations, and more. Developers can also run Typesense within a docker container within their organization’s infrastructure. There are also SDKs for most languages that make managing a search index easier from within your technology stack of choice. For folks reading this post, yes, there is a .NET SDK too.

Typesense operates on a “batteries-included” philosophy, hoping to give developers all the essential features they need right out of the box. This means you can get a “good enough” experience within minutes while having the ability to fine-tune the experience over time.

To take Typesense for a test drive, we’ll use Testcontainers to spin up an instance of the search provider and poke at it.

What is Testcontainers

Testcontainers is an open-source framework for providing lightweight and disposable instances of any imaginable dependency that can run within a Docker container. You can test against the actual technology and avoid mocks and stubs altogether. This framework has a first-class .NET library to allow any developer to pull a Docker image, configure a container instance, run it, and dispose of it.

The following section, we will set up a unit test class using xUnit, Testcontainers, and Typesense.

xUnit, Testcontainers, and Typesense sample

Note: The samples are using newer C# language features like primary constructors and target-type inference. If the code doesn’t compile, you likely need set your language version to a newer version or adapt the code.

We’ll need to create a new xUnit class library with the following dependencies: Testcontainers, Typesense, and xUnit. Once these dependencies are added to the class library, we can start by creating a TypesenseFixture class.

The TypesenseFixture class will create the container and the configuration needed to connect to our container instance.

using DotNet.Testcontainers.Builders;
using DotNet.Testcontainers.Containers;
using Microsoft.Extensions.Options;
using Typesense;
using Typesense.Setup;
using Xunit;

namespace TypesenseWithTestcontainer;

public class TypesenseFixture: IAsyncLifetime
{
    private const int ContainerPort = 8108;
    private const string ApiKey = "typesense-api-key";

    public TypesenseFixture()
    {
        TypesenseContainer = new ContainerBuilder()
            .WithImage("typesense/typesense:0.25.1")
            .WithPortBinding(ContainerPort, true)
            .WithEnvironment("TYPESENSE_API_KEY", ApiKey)
            .WithEnvironment("TYPESENSE_DATA_DIR", "/tmp")
            .WithWaitStrategy(Wait.ForUnixContainer()
                .UntilHttpRequestIsSucceeded(r => r
                    .ForPort(ContainerPort)
                    .ForPath("/health")
                    .WithHeader("TYPESENSE-API-KEY", ApiKey)
                )
            )
            .Build();
    }

    public Config ConnectionConfig { get; private set; }
    public IContainer TypesenseContainer { get; }

    public TypesenseClient GetClient()
    {
        var options = new OptionsWrapper<Config>(ConnectionConfig);
        var client = new TypesenseClient(options, new HttpClient());
        return client;
    }

    public async Task InitializeAsync()
    {
        await TypesenseContainer.StartAsync();
        
        var port = TypesenseContainer
            .GetMappedPublicPort(ContainerPort)
            .ToString();
        
        ConnectionConfig = new Config(
            new Node[] { new(TypesenseContainer.Hostname, port) },
            ApiKey
        );
    }

    public Task DisposeAsync()
        => TypesenseContainer.DisposeAsync().AsTask();
}

Essential steps that are happening in the use of ContainerBuilder:

We set the image name for typesense/typesense:0.25.1. This name matches an image in the Docker image registry.
We bind the internal port 8081 to a random port on our host.
We set the environment variables of TYPESENSE_API_KEY and TYPESENSE_DATA_DIR. These variables are required to start up the container successfully.
We wait for Typesense to start by repeatedly hitting the /health endpoint until the response is successful.

Once the container has started successfully, we can use the container information to produce a Typesense configuration for our client.

Our first step is to see if we can call our instance of Typesense.

using System.Text.Json.Serialization;
using Typesense;
using Xunit;
using Xunit.Abstractions;

namespace TypesenseWithTestcontainer;

public class TypesenseTests(TypesenseFixture fixture, ITestOutputHelper output) :
    IClassFixture<TypesenseFixture>
{
    [Fact]
    public async Task CanQueryTypesenseForHealth()
    {
        var client = fixture.GetClient();
        var result = await client.RetrieveHealth();

        Assert.NotNull(result);
    }
}

The preceding test should pass if everything is set up correctly. Let’s expand our test with a more fun Typesense example.

First, we’ll need a document to store in Typesense.

public class Product(string id, string name, string manufacturer, double price)
{
	[JsonPropertyName(nameof(Id))]
	public string Id { get; set; } = id;
	[JsonPropertyName(nameof(Name))]
	public string Name { get; set; } = name;
	[JsonPropertyName(nameof(Manufacturer))]
	public string Manufacturer { get; set; } = manufacturer;
	[JsonPropertyName(nameof(Price))]
	public double Price { get; set; } = price;
	
	public static Product[] Samples { get; } = {
		new("1", "iPhone 15", "Apple", 1500),
		new("2", "Pixel 8 Pro", "Google", 1300),
		new("3", "Playstation 5", "Sony", 500),
		new("4", "XBox Series X", "Xbox", 500),
		new("5", "Switch", "Nintendo", 300)
	};
}

Typesense uses System.Text.Json with CamelCase naming. In the case of my test, I wanted to retain the original casing, so I used the JsonPropertyName attribute to set the name of each field explicitly. The Product class also defines some sample data for use in our test.

We’ll also want to add IAsyncLifetime to our TypesenseTests class. This will allow us to load our document collection and clear it on each test.

public async Task InitializeAsync()
{
	var client = fixture.GetClient();

	var schema = new Schema(nameof(Product), new Field[]
	{
		new(nameof(Product.Id), FieldType.String),
		new(nameof(Product.Name), FieldType.String, false),
		new(nameof(Product.Manufacturer), FieldType.String, true, false, true),
		new(nameof(Product.Price), FieldType.Float, false)
	});

	await client.CreateCollection(schema);

	foreach (var product in Product.Samples) {
		await client.CreateDocument(nameof(Product), product);
	}
}

public async Task DisposeAsync()
{
	var client = fixture.GetClient();
	await client.DeleteCollection(nameof(Product));
}

Finally, let’s add our test and search for a product.

[Fact]
public async Task CanSearchForProducts()
{
	var client = fixture.GetClient();

	var results = await client
		.Search<Product>(
			nameof(Product),
			new("Sony", nameof(Product.Manufacturer))
		);
	
	Assert.Equal(1, results.Hits.Count);
	
	var product = results.Hits[0].Document;
	Assert.Equal("Sony", product.Manufacturer);
	
	output.WriteLine($"Found {product.Manufacturer} {product.Name} ({product.Price:C})");
}

Awesome! Here’s the complete test class for improved clarity.

using System.Text.Json.Serialization;
using Typesense;
using Xunit;
using Xunit.Abstractions;

namespace TypesenseWithTestcontainer;

public class TypesenseTests(TypesenseFixture fixture, ITestOutputHelper output) :
    IClassFixture<TypesenseFixture>, IAsyncLifetime
{
    [Fact]
    public async Task CanQueryTypesenseForHealth()
    {
        var client = fixture.GetClient();
        var result = await client.RetrieveHealth();

        Assert.NotNull(result);
    }

    [Fact]
    public async Task CanSearchForProducts()
    {
        var client = fixture.GetClient();

        var results = await client
            .Search<Product>(
                nameof(Product),
                new("Sony", nameof(Product.Manufacturer))
            );
        
        Assert.Equal(1, results.Hits.Count);
        
        var product = results.Hits[0].Document;
        Assert.Equal("Sony", product.Manufacturer);
        
        output.WriteLine($"Found {product.Manufacturer} {product.Name} ({product.Price:C})");
    }

    public class Product(string id, string name, string manufacturer, double price)
    {
        [JsonPropertyName(nameof(Id))]
        public string Id { get; set; } = id;
        [JsonPropertyName(nameof(Name))]
        public string Name { get; set; } = name;
        [JsonPropertyName(nameof(Manufacturer))]
        public string Manufacturer { get; set; } = manufacturer;
        [JsonPropertyName(nameof(Price))]
        public double Price { get; set; } = price;
        
        public static Product[] Samples { get; } = {
            new("1", "iPhone 15", "Apple", 1500),
            new("2", "Pixel 8 Pro", "Google", 1300),
            new("3", "Playstation 5", "Sony", 500),
            new("4", "XBox Series X", "Xbox", 500),
            new("5", "Switch", "Nintendo", 300)
        };
    }

    public async Task InitializeAsync()
    {
        var client = fixture.GetClient();

        var schema = new Schema(nameof(Product), new Field[]
        {
            new(nameof(Product.Id), FieldType.String),
            new(nameof(Product.Name), FieldType.String, false),
            new(nameof(Product.Manufacturer), FieldType.String, true, false, true),
            new(nameof(Product.Price), FieldType.Float, false)
        });

        await client.CreateCollection(schema);

        foreach (var product in Product.Samples) {
            await client.CreateDocument(nameof(Product), product);
        }
    }

    public async Task DisposeAsync()
    {
        var client = fixture.GetClient();
        await client.DeleteCollection(nameof(Product));
    }
}

Now, we can test the Typesense search engine from within .NET and explore the client’s capabilities.

As a note, you should do your document initialization code less frequently and possibly within the fixture. Also, explore xUnit’s Collection attribute to reduce the amount of containers created for larger test suites.

Conclusion

Typesense is a promising solution for providing your users an outstanding search experience. By using Testcontainers with the Typesense Docker image, you can quickly experiment with the capabilities of the search engine and what’s possible.

You can get the complete sample at my Typesense with Testcontainers GitHub repository.

I hope this post gives you a good starting point to explore and iterate on your solutions. As always, thank you for reading and sharing my posts. Cheers. :)

How to use Regular Expressions and Match Evaluators in .NET

Tue, 05 Dec 2023 00:00:00 +0000

Let’s face it, regular expressions are powerful and can be an immense pain in the butt to write. While crafting a regular expression to perform any input recognition is possible, it becomes exceedingly difficult when the matching rules require more complicated logic. In specific scenarios, doing an initial regular expression match is more straightforward, and then applying code logic to get the desired result.

This post will look at a straightforward example of using RegEx.Replace with the MatchEvaluator to do a two-step replacement of matched tokens.

What is RegEx.Replace?

When attempting to replace tokens in a string, many developers will reach for RegEx.Replace, which aims to take an input, a regular expression, and then returns are modified result.

Regex.Replace("test", "^test$", "success");

The example works great for simple scenarios, as it is doing token replacement. But what about the following scenario?

Find all image filenames
Replace the filename and extension
Ignore any filename that doesn’t match a criteria.

This is possible with a regular expression but can be complex with lookahead, lookbehind, and named groups. It is not easy for most developers to pull this off. How do we get the result that we want?

Let’s look at a more readable way of solving the problem presented with MatchEvaluator.

Working with MatchEvaluator

The MatchEvaluator type is a delegate wrapper that expects a potentially mutated match result. The delegate can return any value based on the match and other logic a developer may add.

Let’s look at a solution.

using System.Text.RegularExpressions;  
  
string[] extensions = [".jpg", ".gif"];  
// lang=regex  
var pattern = @"\w*\.(\w{3,4})";  
  
var original = "test.webp, test-01.jpg and test-02.gif";  
var result = Regex.Replace(original, pattern, match =>  
{  
    var extension = Path.GetExtension(match.Value);  
    // if we don't need to do anything, return the original value  
    if (!extensions.Contains(extension)) return match.Value;  
    // convert value to a token with webp  
    var filename = Path.GetFileNameWithoutExtension(match.Value);  
    return $"{filename}-converted.webp";  
}, RegexOptions.IgnoreCase);  
  
Console.WriteLine(result);

As you can see, the MatchEvaluator delegate gets the Match. At this point, we can write custom and complex logic to transform the match.

Running the code above, returns the following result.

test.webp, test-01-converted.webp and test-02-converted.webp

Neat!

Conclusion

If you’re struggling to write that perfect RegEx for token replacement, you might find it more straightforward to do it in two steps. First, write a simple-to-understand pattern, and then use MatchEvalutor to get you to the finish line.

I hope you enjoyed this post, and thanks for reading.

Scriban for Text and Liquid Templating in .NET

Tue, 28 Nov 2023 00:00:00 +0000

Templating is a common approach to separating logic from presentation, and many options exist within the .NET ecosystem. The most popular is the Razor engine used by ASP.NET Core, but it currently has some dependencies that make it difficult to use consistently in many scenarios. That’s where alternative templating systems can provide value, as they typically work with fewer, if any, external dependencies.

As a big fan of Jekyll, Liquid is a natural choice for templating as it provides simple templating, types, iteration, control flow, and a suite of built-in helper methods. It’s also very mature and has excellent documentation. So, I was excited to try Scriban as a fast, robust, safe, and lightweight templating engine.

What is Scriban?

Scriban is the brainchild of Alexandre Mutel, and is touted as a scripting language and engine for .NET with the primary purpose of text templating. It also provides a compatibility mode for parsing and rendering Liquid templates. It’s vital to distinguish Scriban as a text templating engine, not just a web view engine. Text templating implies it can be used to generate any text-based format, including but not limited to HTML. Outside of .NET dependencies, Scriban is entirely free of external dependencies, with the option to source embed. This makes it perfect for many app host options in the .NET ecosystem.

Getting Started with Scriban

Let’s see what a “Hello World” use case would look like.

// Parse a scriban template
var template = Template.Parse("Hello !");
var result = template.Render(new { Name = "World" }); 
// => "Hello World!"

This could look more exciting, but it hints at some mind-blowing scenarios which we’ll see in the next section. Let’s ramp it up.

Complex Liquid Scenario with Scriban

As mentioned, Liquid is a commonly-used templating language used in the Ruby on Rails community. Shopify also uses it for its online storefront platform. Let’s look at a complex C# example of a Liquid template and then break it down.

Note: If you’re using JetBrains Rider, install the Liquid plugin to get Liquid syntax highlighting.

using Scriban;  
using Scriban.Runtime;  
  
var script = new ScriptObject();  
script.Import(typeof(MyFunctions));  
script.Add("products", new Product[]  
{  
    new("Blue Socks", 10m, "plain socks"),  
    new("Gray Pants", 22m, "regular ol' pants"),  
    new("Amazing T-Shirt", 24m, 
        "the world's most fantastical t-shirt"),  
});  
  
var context = new LiquidTemplateContext();  
context.PushGlobal(script);  
  
var template = Template.ParseLiquid(
    // lang=liquid
    """
    <ul id='products'>{% for product in products %}
        <li>
            <h2>{{ product.name | append_emoji }} ({{ product.price }})</h2>
            <p>{{ product.description | truncate: 15, "..." }}</p>
        </li>{% endfor %}
    </ul>
    """);
  
var result = template.Render(context);  
  
Console.WriteLine(result);  
  
public static class MyFunctions  
{  
    public static string AppendEmoji(string input)  
        => $"{input} 🛍️";  
}  
  
public record Product(  
    string Name,  
    decimal Price,  
    string Description);

At the start of of the code, we create a new ScriptObject. This instance will contain all our variables and .NET functions we’ll want to use in our template.

The first step registers an AppendEmoji method, which gets translated into append_emoji by convention. All static methods in the MyFunctions class will be registered. You can expand your templating vocabulary with a few C# methods.

Next, we add the products global variable to our script. This collection will be used in the template to display our product collection. These are plain old C# records.

Finally, we get to the template parsing and rendering. You’ll notice the use of the truncate filter in the template. From my testing, most Liquid filters are available out of the box, which is helpful. When the template is parsed, we’re ready to render it. Here, the call to Render is provided the script context, which references our data and our C# AppendEmoji helper method.

All that’s left is to see what the results look like.

<ul id='products'>
    <li>
        <h2>Blue Socks 🛍️ (10)</h2>
        <p>plain socks</p>
    </li>
    <li>
        <h2>Gray Pants 🛍️ (22)</h2>
        <p>regular ol' ...</p>
    </li>
    <li>
        <h2>Amazing T-Shirt 🛍️ (24)</h2>
        <p>the world's ...</p>
    </li>
</ul>

That’s awesome!

Conclusion

Scriban looks like an excellent templating engine for the .NET ecosystem. With the ability to use Liquid, it goes to a whole new level. The ability to inject variables and methods into the template is also excellent. Please try it and let me know what scenarios you could use a text templating engine in.

Thank you for reading and sharing my posts with friends and colleagues.

ASP.NET Core PDF Previews and Downloads

Tue, 21 Nov 2023 00:00:00 +0000

Tell me if you’ve heard this one before. You spend months working with UI and UX experts, building what you think is the most optimal means of displaying business information. You sit in a meeting with your stakeholders, demoing what you created. Everything feels great, but then silence fills the room. A lone stakeholder raises their voice, “This is all great, but can we get it in a PDF?”.

The Portable Document Format (PDF) is in a heated race, with Excel spreadsheets as the most valuable file format in business today. As a developer, you will inevitably be asked to compress everything into a file that business individuals can share via email. Don’t fight it, but embrace it.

In this post, we’ll see the two approaches to transmitting PDF files through ASP.NET Core to get two different behaviors: In-browser preview and downloads.

Generating a PDF with QuestPDF

While this post isn’t a tutorial for generating PDFs, you’ll need a way to generate PDFs to follow along. I recommend using the QuestPDF library. The API is easy to get started with and will have you generating PDF documents in no time. Also, their licensing costs are reasonable, ranging from a free community license to an Enterprise license. That said, feel free to substitute any PDF-generating method you prefer.

Here is the code for my PDF generation.

private static byte[] GetPdfDocuments()  
{  
  var pdf =  
      Document.Create(container =>  
      {  
          container.Page(page =>  
          {  
              page.Size(PageSizes.A4);  
              page.Margin(2, Unit.Centimetre);  
              page.PageColor(Colors.White);  
              page.DefaultTextStyle(x => x.FontSize(20));  

              page.Header()  
                  .Text("Hello PDF!")  
                  .SemiBold().FontSize(36)
                  .FontColor(Colors.Blue.Medium);  

              page.Content()  
                  .PaddingVertical(1, Unit.Centimetre)  
                  .Column(x =>
                  {  
                      x.Spacing(20);

                      x
                      .Item()
                      .Text(Placeholders.LoremIpsum());  
                      x
                      .Item()
                      .Image(Placeholders.Image(200, 100));  
                  });
              
              page.Footer()  
                  .AlignCenter()  
                  .Text(x =>  
                  {  
                      x.Span("Page ");  
                      x.CurrentPageNumber();  
                  });            
          });        
  }).GeneratePdf();  
  
  return pdf;  
}

OK, let’s move on to one of the first ways of transmitting a PDF to your user: previewing the file within the browser.

Previewing a PDF File in the Browser

In this example, I’ll be using ASP.NET Core MVC, but this approach should work with Razor Pages and even Minimal APIs. Adjust the code accordingly.

public IActionResult Show()  
{  
    var pdf = GetPdfDocuments();  
    return File(pdf, "application/pdf");  
}

Next, you’ll want to add the button in your view to trigger this MVC action.

<a class="btn btn-primary"
   asp-controller="Files"
   asp-action="Show"
   target="_blank">
    Preview PDF
</a>

That’s it! Clicking the Preview button will trigger your browser to open the file in a new tab. But you may be asking yourself, “Why does this work?” Let’s look at the response headers of the HTTP request.

Content-Length: 78127
Content-Type: application/pdf
Date: Wed, 06 Sep 2023 14:17:30 GMT
Server: Kestrel

A client (web browser) uses the content type of application/pdf to determine if a default viewing application is associated with the MIME type. Since the PDF is a standard format, most modern browsers can render them in-app (sorry, Adobe Acrobat Reader). The user can now view the file as if it were another tab.

Note: It’s essential to recognize that users can also change their preferences regarding how files are handled, so this can behave differently based on an individual’s local setup.

What if you don’t want this behavior and want to force a download?

Downloading a PDF File in the Browser

If you want to let folks download files rather than having the client open the file in the browser, it’s as simple as adding another argument to the previous code.

public IActionResult Download()  
{  
    var pdf = GetPdfDocuments();  
    return File(pdf, "application/pdf", "download.pdf");  
}

Then, the button in your view is similar to the previous example.

<a class="btn btn-primary"
   asp-controller="Files"
   asp-action="Download">
    Download PDF
</a>

Now, why does this download the PDF rather than preview the file?

Let’s look at the HTTP response headers to see what’s different.

Content-Disposition: attachment; filename=download.pdf; filename*=UTF-8''download.pdf
Content-Length: 78109
Content-Type: application/pdf
Date: Wed, 06 Sep 2023 14:17:30 GMT
Server: Kestrel

You can see a Content-Disposition response header with the value of attachment and a filename. This tells the browser that the server intends the client to download the file rather than attempt to render it as a document.

Conclusion

While the focus of this blog post was PDFs, this applies to any document type. If the user has a default application that can preview a file, then excluding the filename will attempt to open and preview the document. For PDFs, most browsers can render them in-app without additional applications. For downloading files, you only need to remember to give the file a name.

I hope this post was informative to you, and as always, thanks for sharing my posts with colleagues and friends. Cheers.

VestPocket: File-based Data Storage for AOT .NET Applications

Tue, 14 Nov 2023 00:00:00 +0000

As Zoolander villain Mugato might say if he were a .NET developer, “Ahead of Time (AOT) compilation is so hot right now.” AOT is one of the focuses of the .NET 8 release, with a lot of attention given to high-performance scenarios. For the uninitiated, the act of AOT is compiling a higher-level language into a lower-level language for a better execution profile at runtime. In the case of .NET AOT, it’s targeting builds for specific environments to get near-native performance.

While many folks will undoubtedly start looking at AOT as an option to squeeze more juice out of their apps, they may have to reconsider many of their dependencies that are not AOT compatible. In that dependency vacuum, a new class of libraries will emerge to offer developers a way forward.

In today’s blog post, let’s check out VestPocket. VestPocket is a file-based “database” closer to a key-value store than a full-blown database. It aims to provide developers with an in-memory record storage option while having them persisted to disk.

What is VestPocket?

VestPocket is a .NET library that allows developers to store entities in a single file. Records are serialized using System.Text.Json and the newer AOT-compatible serialization source generators in .NET 7. The library is meant to give the developer a local database instance without the overhead of a database engine.

Some use cases might involve:

Version and deploy application-specific data in a human-readable file.
Caching data locally in a single application instance.
As a proof-of-concept database for demos and samples.
You need more resilience than in-memory collections.

You can get a solution up and running with a bit of setup. Let’s do that now!

Getting Started with VestPocket

Before getting started, you’ll need to install the VestPocket NuGet package. As mentioned in the previous section, VestPocket uses System.Text.Json and source generators to serialize records into the file-based format. Let’s start by looking at setting up our entity models.

using System.Text.Json.Serialization;  
using VestPocket;  
  
namespace Vested;  
  
[JsonSerializable(typeof(Entity))]  
[JsonSourceGenerationOptions(WriteIndented = false)]  
public partial class DatabaseContext : JsonSerializerContext  
{  
}  
  
[JsonDerivedType(typeof(Entity), nameof(Entity))]  
[JsonDerivedType(typeof(Person), nameof(Person))]  
public record Entity(string Key, int Version, bool Deleted)  
    : IEntity  
{  
    public IEntity WithVersion(int version)  
        => this with { Version = version };  
}  
  
public record Person(  
    string Key,  
    string Name,  
    int Age,  
    int Version = 0,  
    bool Deleted = false  
) : Entity(Key, Version, Deleted);

All your VestPocket entities will need a base Entity type. This type is created within your application and must implement the IEntity interface from VestPocket. Once you have a base record, you can begin implementing derived entities. In the previous code, I implemented a new Person entity. Be sure to mark your Entity instance with all derived entities using JsonDerivedType. This attribute tells System.Text.Json the derived types that the JsonSerializerContext should be aware of when building serializers and deserializers to create for use at runtime. Finally, we set up the DatabaseContext with serialization options and known entities. Again, since everything will derive from Entity, we only need one JsonSerializable attribute.

Now, let’s write some code using our new data storage.

using Vested;  
using VestPocket;  
  
var options = new VestPocketOptions { FilePath = "test.vest" };  
var store = new VestPocketStore<Entity>(DatabaseContext.Default.Entity, options);  
  
// open the database  
await store.OpenAsync(CancellationToken.None);  
  
var khalid =   
    store.Get<Person>("person/khalid") ??  
    new("person/khalid", "Khalid Abuhakmeh", 40);  
  
var maarten =   
    store.Get<Person>("person/maarten") ??  
    new("person/maarten", "Maarten Balliauw", 39);  
  
// will save a new version or increment version  
await store.Save(new Entity[] { khalid, maarten });  
  
// get all people  
var people = store.GetByPrefix<Person>("person/");  
  
foreach (var (_, name, age, _, _) in people)  
{  
    Console.WriteLine($"{name} ({age})");  
}  
  
// maintenance (clean up previous versions)  
await store.ForceMaintenance();  
  
// close store (flush any pending writes)  
await store.Close(CancellationToken.None);

If you’ve used any .NET object-relation mapper, this style will likely not surprise you. Let’s break down the sample.

var options = new VestPocketOptions { FilePath = "test.vest" };  
var store = new VestPocketStore<Entity>(DatabaseContext.Default.Entity, options);

A VestPocketStore is your access method to your data storage. The constructor takes the Entity serializer generated by System.Text.Json and an instance of VestPocketOptions. Stores are thread-safe, so you can share a single store instance across your application.

// open the database  
await store.OpenAsync(CancellationToken.None);

To create the file or access an existing file, the OpenAsync method must be invoked.

var khalid =   
    store.Get<Person>("person/khalid") ??  
    new("person/khalid", "Khalid Abuhakmeh", 40);  
  
var maarten =   
    store.Get<Person>("person/maarten") ??  
    new("person/maarten", "Maarten Balliauw", 39);

This code may look weird, but for the sake of this sample, I check to see if the sample has already stored a previous version of our records. If so, we retrieve the existing element. Otherwise, we’ll create a new record in memory.

// will save a new version or increment version  
await store.Save(new Entity[] { khalid, maarten });

Here, we attempt to store the records. It’s important to note that VestPocket is an append-only write system. So, you might have multiple versions of the same record. Here is the test.vest file on disk.

{"Creation":"2023-09-05T13:20:35.044512-04:00","LastRewrite":"2023-09-05T13:30:11.911718-04:00","CompressedEntities":null}  
{"$type":"Person","Name":"Khalid Abuhakmeh","Age":40,"Key":"person/khalid","Version":3,"Deleted":false}  
{"$type":"Person","Name":"Maarten Balliauw","Age":39,"Key":"person/maarten","Version":3,"Deleted":false}  
{"$type":"Person","Name":"Khalid Abuhakmeh","Age":40,"Key":"person/khalid","Version":4,"Deleted":false}  
{"$type":"Person","Name":"Maarten Balliauw","Age":39,"Key":"person/maarten","Version":4,"Deleted":false}

As the previous code shows, you can always retrieve records by a specific key, but you can filter the results down based on key prefixes.

// get all people  
var people = store.GetByPrefix<Person>("person/");  
  
foreach (var (_, name, age, _, _) in people)  
{  
    Console.WriteLine($"{name} ({age})");  
}

You may also want to “clean up” the database of old versions eventually. This is where the call to ForceMaintenance helps. It removes all but the latest version of an entity.

// maintenance (clean up previous versions)  
await store.ForceMaintenance();

Finally, before our application exits, we want to ensure we’ve flushed all records to disk. We can do that by calling Close on our store instance.

// close store (flush any pending writes)  
await store.Close(CancellationToken.None);

There, you have it. A simple one-file usage of VestPocket.

Conclusion

With AOT on the horizon, it’s nice to see folks experimenting with it and providing the community with packages. VestPocket is a file-based data storage mechanism with an ESENT vibe, and that’s pretty neat. While still in the experimental phase, I can see it being helpful in the use cases the author describes. Head over to the VestPocket GitHub repository and give it a star.

As always, thank you for reading and sharing my posts with friends and colleagues. Cheers.

MoonSharp - Running Lua Scripts in .NET

Tue, 07 Nov 2023 00:00:00 +0000

Lua is a scripting language most famously known for powering Blizzard’s World of Warcraft but was designed to be a general-purpose means of building robust, efficient, and lightweight solutions. Lua was created in 1993 (30 years ago!) and has since been popular among developers across all ecosystems. Lua is an excellent choice for folks because it is fast, portable, embeddable, small, and Free under an MIT license.

If you’ve ever dreamed about building extensibility into your applications, Lua is an excellent choice, as you can allow consumers to build scripts that work within your .NET host application. In this post, we’ll walk through the straightforward steps to add Lua support to your .NET applications, how you might invoke Lua scripts, and how you might let Lua scripts call your .NET methods.

Getting Started with MoonSharp

In a .NET console application, start by installing the MoonSharp NuGet package.

dotnet add package MoonSharp

You can also add the following ItemGroup to your .NET project file.

<ItemGroup>  
  <PackageReference Include="MoonSharp" Version="2.0.0" />  
</ItemGroup>

After that, you should be ready to start writing your first Lua script.

As a bonus, if you’re using JetBrains Rider you’ll get Lua syntax highlighting with the language injections feature.

In your Program.cs file, add the following code.

using MoonSharp.Interpreter;  
  
// language=lua  
var lua =  
  """  
  print("Hello, Lua")  
  """;  
  
Script.DefaultOptions.DebugPrint = Console.WriteLine;  
Script.RunString(lua);

You should see the following output in your console when you run your Console application.

Hello, Lua

Setting the DebugPrint property is necessary to allow MoonSharp to redirect print output somewhere. We chose the console in this case, but it could be directed to a string, Stream, or whatever.

Invoke a Lua Function from C#

Doing a print call is fun, but we can be more practical. Let’s step it up by invoking a Lua add method that takes two integer arguments.

using MoonSharp.Interpreter;  
  
Script.DefaultOptions.DebugPrint = Console.WriteLine;  
  
// language=lua  
var lua =  
  """  
  function add(x, y)    
      return x + y  
  end  
  """;  
  
var script = new Script();  
// loads and executes script  
script.DoString(lua);  
// call our global method  
DynValue value = script.Call(script.Globals["add"], 1, 1);  
  
Console.WriteLine($"1 + 1 is {value.Number}");

Here, we load a new function of add that takes two number arguments. Remember, Lua is dynamically typed, so you won’t see any type declarations. We create a script variable to reuse the context of our script, which now holds a global add function. We can use the script variable from here to invoke our global function and the necessary arguments. The DynValue is a dynamic result, but there are helper properties you can use to type the result to a known .NET type. In this case, we’ll use the Number property to get an integer value. Executing our application, we get the console output.

1 + 1 is 2

What if we want a Lua script to call our .NET application?

Invoking a C# Method from a Lua Script

MoonSharp allows you to inject elements into the global script context. In this section, we’ll provide our Lua script with an add method and do the addition in the scope of a C# code block.

using MoonSharp.Interpreter;  
  
Script.DefaultOptions.DebugPrint = Console.WriteLine;  
  
// language=lua  
var lua =  
  """  
  local result = add(1,1)  
  local output = string.format("1 + 1 is %s", result)  
  print(output)  
  """;  
  
var script = new Script();  
  
int add(int x, int y)  
{  
  Console.WriteLine("Yep, I'm .NET baby!");  
  return x + y;  
}  
  
// load our C# method into global  
script.Globals[nameof(add)] = add;   
// loads and executes script  
script.DoString(lua);

We pass the C# local function of add as a Func<int,int,int> to Lua. This allows Lua scripts to invoke the global method. Running the code above returns the following result.

Yep, I'm .NET baby!
1 + 1 is 2

Awesome!

Conclusion

We’ve only scratched the surface of what MoonSharp has to offer with Lua, but with these three demonstrations, you can see that the interoperability possibilities are through the roof. Leveraging MoonSharp you can build extensibility into your applications using a battle-hardened scripting language.

If you want to learn more about MoonSharp, visit the official site to see more samples and to read the official documentation.

Thanks for reading and sharing my posts with friends and colleagues.

What Should I Dispose with .NET Database Connections?

Tue, 31 Oct 2023 00:00:00 +0000

When working with “expensive” resources, it is essential to call the Dispose method to tell .NET’s garbage collector that it’s time to clean up the instance and all its associated baggage. Disposing of instances is most important when dealing with finite resources on the hot path of your codebase, and for most .NET developers, the most crucial resource is a database connection. Your app is done for if you run out of database connections.

With database connections, we also have a supporting cast of commands and readers, all of which can be disposed of as well. This leads to an interesting question: “Do you HAVE TO dispose everything?”

In this post, we’ll explore the Microsoft.Data.Sqlite implementations of DbConnection, DbCommand, and DbDataReader and see what happens when we call Dispose on each type.

The Data Access Code

When working with ADO.NET, you’ll likely be using a Microsoft.Data.* package or a community library like Npgsql. Each library implements a database-specific version of DbConnection, DbCommand, DbReader, and other intrinsics. Let’s write a simple application that opens a connection, creates a command, and then reads the results.

using Microsoft.Data.Sqlite;  
  
await using SqliteConnection connection = new("Data Source=test.sqlite");  
await connection.OpenAsync();  
  
await using SqliteCommand command = connection.CreateCommand();  
command.CommandText = "SELECT * FROM sqlite_master";  
  
await using SqliteDataReader reader = command.ExecuteReader();  
Console.WriteLine($"Has Rows? {reader.HasRows}");

You may notice a few things happening in the previous code.

All implementations implement IDisposable, but more specifically IAsyncDisposable.
We can use scope-based disposal, which disposed of our instances as soon as they fall out of scope. The use of await using allows us to do that.
All instances are disposed of, but do we need it?

In the following sections, we’ll see what each dispose of and if we need to dispose of all instances in the code sample.

Disposing a SqliteConnection

What does disposing of an instance of SqliteConnection entail? Looking through the codebase using my trusty decompiler, I found that calling dispose does a lot.

protected override void Dispose(bool disposing)  
{  
    if (disposing)  
    {        
        Close();  
    }  
    base.Dispose(disposing);  
}

public override void Close()  
{  
    if (State != ConnectionState.Open)  
    {        
        return;  
    }
      
    Transaction?.Dispose();  
  
    for (var i = _commands.Count - 1; i >= 0; i--)  
    {        
        var reference = _commands[i];  
        if (reference.TryGetTarget(out var command))  
        {            
            // NB: Calls RemoveCommand()  
            command.Dispose();  
        }        
        else  
        {  
            _commands.RemoveAt(i);  
        }    
    }  
    Debug.Assert(_commands.Count == 0);  
  
    _innerConnection!.Close();  
    _innerConnection = null;  
  
    _state = ConnectionState.Closed;  
    OnStateChange(_fromOpenToClosedEventArgs);  
}

It closes the current connection and sets the state to closed.
It disposes of any active transactions to the database.
It also disposes of any DbCommand instances associated with the connection and removes them from being tracked.
If there are any inner connections, they get disposed of as well.

Hmm… commands get disposed of. Well, what does that do?

Disposing a SqliteCommand

No surprise, but disposing of a SqliteCommand does a lot too! Let’s take a look at the implementation.

protected override void Dispose(bool disposing)  
{  
    DisposePreparedStatements(disposing);  
  
    if (disposing)  
    {        
        _connection?.RemoveCommand(this);  
    }  
    base.Dispose(disposing);  
}

private void DisposePreparedStatements(bool disposing = true)  
{  
    if (disposing && DataReader != null)  
    {        
        DataReader.Dispose();  
        DataReader = null;  
    }  
    if (_preparedStatements != null)  
    {        
        foreach ((var stmt, _) in _preparedStatements)  
        {            
            stmt.Dispose();  
        }  
        _preparedStatements.Clear();  
    }  
    _prepared = false;  
}

The command is removed from the associated connection
Any reader associated with the command is disposed.
All statements associated with the command are disposed of and cleared from a tracking collection.

Interestingly, again, disposing of the command disposes the reader. Let’s keep going. What does that do?

Disposing a SqliteDataReader

We’re almost to the end. What happens when a SqliteDataReader gets disposed?

protected override void Dispose(bool disposing)  
{  
    if (!disposing || _closed)  
    {        
        return;  
    }  
    _command.DataReader = null;  
  
    _record?.Dispose();  
    _record = null;  
  
    if (_stmtEnumerator != null)  
    {        
        try  
        {  
            while (NextResult())  
            {            
            }        
        }        
        catch  
        {  
        }    
    }  
    _stmtEnumerator?.Dispose();  
  
    _closed = true;  
  
    if (_closeConnection)  
    {        
        _command.Connection!.Close();  
    }
}

Here, disposing of the reader disposes of all the record instances currently part of the reader. The method will also disconnect from the command it is associated with. Also, in this case, the reader will close the connection if a boolean is set to true.

Conclusion

Following the chain of calls, calling Dispose on the SqliteConnection should be enough for most folks to reclaim the resources allocated by the initial code. That said, if you want to reclaim your resources “faster”, you can undoubtedly call the Dispose methods as soon as you’re done with the resource. Generally, I recommend calling dispose on derived instances from SqliteConnection if you use object-pooling, where the root instance is long-lived. This is a common practice in ORMs, which can help improve performance. Finally, if you’re using a dependency injection library, it already handles object disposal automatically for you. As always, check your code, use the decompiler, and learn how stuff works.

As always, thanks for reading and sharing my posts with friends and colleagues. Cheers :)

Global Endpoint Filters with ASP.NET Core Minimal APIs

Tue, 24 Oct 2023 00:00:00 +0000

The ASP.NET Core technology stack works on the pipeline concept. A user request travels through the pipeline, where you have opportunities to handle the request in various forms. The approach to enhancing the pipeline in ASP.NET Core has been a mixture of Middleware and paradigm-specific filters. Filters for ASP.NET Core MVC give you MVC-specific idioms to work with, while Middleware typically works with the rawest elements of an HttpContext.

With Minimal APIs, you can implement the IEndpointFilter interface I wrote about previously.

In this post, we’ll see a technique to apply the IEndpointFilter to all endpoints, similar to ASP.NET Core MVC’s global filters. As a bonus, it’s pretty straightforward.

Why not Middleware?

Middleware in ASP.NET Core is designed to operate as a gate to incoming HTTP requests and outgoing HTTP responses. You could use the IMiddleware interface to process the request, but you’ll quickly find out you’re working with lower-level intrinsics than you might want. Let’s take a look at an implementation of a new Middleware.

public class MyMiddleware: IMiddleware  
{  
    public Task InvokeAsync(HttpContext context, RequestDelegate next)  
    {        
        throw new NotImplementedException();  
    }
}

You’ll quickly notice the use of HttpContext and the RequestDelegate types. These types can give you access to elements of the request pipeline you might need, but the accessing code can be verbose and opaque. In other words, you’ll quickly find your Middleware code exploding in complexity.

Middleware is an excellent tool for applying similar functionality across all ASP.NET Core development paradigms, including MVC, Razor Pages, Minimal APIs, and Blazor. To offer that breadth, middleware implementations must work at the lowest abstractions.

On the other hand, the IEndpointFilter is explicitly designed to work with the latest concept of Endpoints, which includes Minimal APIs, MVC, and Razor Pages. Endpoints generally focus on inputs and outputs, with the pipeline responsible for executing those results. It’s easier to see this in the implementation of a filter.

public class ScreamingFilter: IEndpointFilter  
{  
    public async ValueTask<object?> InvokeAsync(  
        EndpointFilterInvocationContext context,  
        EndpointFilterDelegate next)  
    {        
        var result = await next(context);  
        return result is string s   
            ? $"{s}!!!!"   
            : result;  
    }
}

Rather than working with HttpContext, we are working with the return value of our endpoint. That allows us to deal with objects and their properties. This opens up a world of possibilities regarding object inspection and enrichment that can be difficult to do with middleware.

OK, enough theory. Let’s get to Global Endpoint Filters for Minimal APIs.

The One Trick That Makes It Possible

First of all, and I’ll be the first to admit it, this technique can seem “simple” on the surface, but it works surprisingly well.

You need a global’ Map’ group to get Global Endpoint Filters for Minimal APIs working. Let’s see this in action.

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

// the magic 🪄
var global = app  
    .MapGroup(string.Empty)  
    .AddEndpointFilter<ScreamingFilter>();  
  
global.MapGet("/", () => "Hello World");  
global.MapGet("/hi", () => "Hi");  
global.MapGroup("/what").MapGet("/now", () => "🤷");  
  
app.Run();  
  
public class ScreamingFilter: IEndpointFilter  
{  
    public async ValueTask<object?> InvokeAsync(  
        EndpointFilterInvocationContext context,  
        EndpointFilterDelegate next)  
    {        
        var result = await next(context);  
        return result is string s   
            ? $"{s}!!!!"   
            : result;  
    }
}

The trick is to register all endpoints off of the root MapGroup. Each additional endpoint will now inherit the filters of the group. Since the global group has no route prefix, it doesn’t affect any paths of registered endpoints. The explicit type of global is RouteGroupBuilder, which implements IEndpointRouteBuilder and IEndpointConventionBuilder, which should give you access to the same functionality as registering a regular endpoint, including having additional sub-groups.

Now, you have what are essentially global endpoint filters for all your minimal API endpoints. Pretty cool! Note that endpoint execution ordering will still apply. All “global” endpoint filters will execute first, then any filters applied directly to the endpoints.

As always, thanks for reading my blog posts and for sharing my posts with friends and colleagues. Cheers :)

RazorSlices - Razor Views with ASP.NET Core Minimal APIs

Tue, 17 Oct 2023 00:00:00 +0000

With .NET 8 on the horizon, Minimal APIs continues to grow its offerings, slowly providing a similar feature set to the frameworks before, including ASP.NET Core MVC and Razor Pages. I was surprised when someone in the community (👋 Hi Johnathan Channon) pointed me to a fascinating RazorSlices project. RazorSlices is written by Damian Edwards, an ASP.NET Core team member with a history of working with the Razor view engine. His goal is to bring Razor functionality to Minimal API adopters in a similar way that ASP.NET Core MVC, Razor Pages, and Blazor users enjoy today.

In this post, we’ll see how to set up RazorSlices in your ASP.NET Core applications and think about the pros and cons of its usage.

Getting Started with RazorSlices

In a Minimal API project, start by installing the RazorSlices package. You can do this by using the dotnet add package RazorSlices command or by adding the appropriate PackageReference in your .csproj file.

<PackageReference Include="RazorSlices" Version="0.7.0" />

Next, create a folder at the root of your ASP.NET Core application. It can be named anything you like. I chose Slices as it was what the documentation recommended. This directory is where you’ll place all your Razor views to be used in your Minimal API endpoints.

Within the Slices folder, create a new file named _ViewImports.cshtml. The view imports file allows you to create a shared context for all views within the folder, including namespaces, base classes, and tag helpers. Here’s the contents of my file.

@inherits RazorSliceHttpResult  
  
@using System.Globalization;  
@using Microsoft.AspNetCore.Razor;  
@using Microsoft.AspNetCore.Http.HttpResults;  
  
@tagHelperPrefix __disable_tagHelpers__:  
@removeTagHelper *, Microsoft.AspNetCore.Mvc.Razor

You’ll notice two strange things when looking at this file:

The @inherits value is of RazorSliceHttpResult to work with the IResult type used my Minimal APIs.
Tag helpers are removed and obfuscated. That’s because they’re not supported in this model. Only expect to port a Razor Pages implementation over to RazorSlices by making some modifications or concessions.

Next, you’ll want to create a new Hello.cshtml view in the Slices folder.

@inherits RazorSliceHttpResult<DateTime>  
<!DOCTYPE html>  
<html lang="en">  
<head>  
    <meta charset="utf-8">  
    <title>Hello from Razor Slices!</title>  
</head>  
<body>  
<p>  
    Hello from Razor Slices! The time is @Model  
</p>  
</body>  
</html>

Note that the view also uses the @inherit attribute, but this time uses a generic type definition. The generic type argument is the type of the @Model instance.

Finally, you’ll want to use the view in your Minimal API endpoint.

var builder = WebApplication.CreateBuilder(args);  
var app = builder.Build();  
  
app.MapGet("/", () =>  
    Results.Extensions.RazorSlice("/Slices/Hello.cshtml", DateTime.Now));  
  
app.Run();

And that’s it! You are now rendering Razor views through your Minimal API endpoint.

For folks using JetBrains tooling, go a little extra and install JetBrains.Annotations.

dotnet add package JetBrains.Annotations

Then, modify your code to look like the following.

using JetBrains.Annotations;  
  
var builder = WebApplication.CreateBuilder(args);  
var app = builder.Build();  
  
app.MapGet("/", () =>  
    Slice("/Slices/Hello.cshtml", DateTime.Now));  
  
app.Run();  
  
IResult Slice<T>([AspMvcView]string viewPath, T model)  
    => Results.Extensions.RazorSlice(viewPath, model);

The benefit here is you can now Ctrl + Click through to your view right from the C# code. That should help your productivity. This works because you need to reference RazorSlice views by the absolute path, and JetBrains Rider and ReSharper undertand that behavior. Pretty awesome, right?

The Pros of RazorSlices

The most obvious benefit here is that you can now use Razor to generate HTML results in your Minimal API endpoints. I might be biased, but I love the Razor syntax and its benefits to the web development experience.

Another significant benefit is your Razor views can also use the @inject attribute, giving you access to dependencies in the HTML rendering process.

If performance is a concern of yours, there is a SliceFactory, that can help reduce the cost associated with looking up views. This can be an easy win for folks looking to eek out more performance. Speaking of performance, there are plans to add Ahead of Time (AOT) support.

The Cons of RazorSlices

Let’s talk about the drawbacks of using RazorSlices, because there are a few.

As mentioned, if you’re looking for a one-to-one replacement for MVC or Razor Pages, you will be disappointed. It’s meant to be something other than a drop-in replacement for either approach. This is evident when using features like TagHelpers or View Components.

The library has no current support for partial views, making view composition and componentization impossible. It may find its way into the package but is currently unavailable. This includes the view infrastructure associated with MVC, like layouts and layout sections. As I said previously, this is not a drop-in replacement.

A new paradigm means leaving behind the past paradigm. If you depend on third-party Razor libraries, they may not work in this current iteration.

Conclusion

RazorSlices is worth checking out if you’re looking for a way to render HTML one step above string interpolation in your API endpoints. It provides the basics of what you love about Razor syntax, including expressions, control structures, looping, and code blocks. For most, that’s going to be enough to accomplish any goal. That said, if you’re looking for an ASP.NET Core MVC replacement, this library is far from being that, but that’s OK.

Check out the library at RazorSlices and let me know your thoughts. As always, thanks for reading and sharing my blog posts.

How To Use Embedded Resources in .NET

Tue, 10 Oct 2023 00:00:00 +0000

While code is inarguably the bedrock of any software application, it’s not the only thing necessary to deliver a user experience. Whether you’re building a website, desktop application, or mobile app, you’ll likely need non-code assets. These assets include images, videos, third-party file formats, and more. Additionally, you should include localization values to support a variety of languages and grow your user base.

This post will explore embedded resources in .NET and point to some material I’ve written for JetBrains about localizing your ASP.NET applications.

Embedded Resources

An embedded resource is any file you want to include in your final built assembly. This can include anything from text files to binary formats like images or videos. Embedded resources use the EmbeddedResource MSBuild element, which the compiler reads to transform project assets into binary embedded in your assemblies. Here are a few examples.

<ItemGroup>  
  <EmbeddedResource Include="Embedded\test.txt" />  
  <None Remove="Embedded\person.json" />  
  <EmbeddedResource Include="Embedded\person.json" />  
  <EmbeddedResource Update="Embedded\Values.resx">  
    <Generator>ResXFileCodeGenerator</Generator>  
    <LastGenOutput>Values.Designer.cs</LastGenOutput>  
  </EmbeddedResource>
</ItemGroup>

Once an asset is embedded, it is given a unique name in the resource manifest, which is typically similar to its file path but is overridable.

Remember, assets are stored within the Assembly, which means you must know which assembly has your resources to get the names from the manifest. Here is an example.

var names =   
	System  
	.Reflection  
	.Assembly  
	.GetExecutingAssembly()  
	.GetManifestResourceNames();  
  
foreach (var name in names)  
{  
    Console.WriteLine(name);  
}

Combined with our ItemGroup from above, we’d get the following output.

BedTime.Embedded.Values.resources
BedTime.Embedded.test.txt
BedTime.Embedded.person.json

You may have also noticed the use of ResXFileCodeGenerator. The Resx file format is a unique format used by .NET applications to store mostly string values, but it can also be adapted to store binary formats like images in base64 strings. I don’t recommend it, but it’s possible.

The .resx format is best suited for localization, which I wrote about previously for JetBrains here. Check it out. It also generates a C# class for accessing values for straightforward usage. The format is also used by many of the features in .NET, including ASP.NET Core.

Accessing Embedded Resources from C#

I recommend folks access embedded resources by writing static wrapper classes that formalize the process of accessing assembly artifacts. let’s look at how we might access one of the files from the previous section, and then we’ll create the wrapper class for all resources.

var info = Assembly.GetExecutingAssembly().GetName();  
var name = info.Name;  
using var stream = Assembly  
    .GetExecutingAssembly()  
    .GetManifestResourceStream($"{name}.Embedded.test.txt")!;  
using var streamReader = new StreamReader(stream, Encoding.UTF8);  
return streamReader.ReadToEnd();

Resource names will typically follow this convention (Assembly Name).(Folders).(Filename) unless an explicit name exists. You can also use the GetManifestResourceNames method to find a resource name if you can’t figure it out by convention.

Now, let’s wrap all our resources in a static class.

using System.Reflection;
using System.Text;
using System.Text.Json;

namespace BedTime.Embedded;

public static class Resources
{
    public static class Embedded
    {
        public static string TestTxt
        {
            get
            {
                var info = Assembly.GetExecutingAssembly().GetName();
                var name = info.Name;
                using var stream = Assembly
                    .GetExecutingAssembly()
                    .GetManifestResourceStream($"{name}.Embedded.test.txt")!;
                using var streamReader = new StreamReader(stream, Encoding.UTF8);
                return streamReader.ReadToEnd();
            }
        }

        public static Person Person
        {
            get
            {
                var info = Assembly.GetExecutingAssembly().GetName();
                var name = info.Name;
                using var stream = Assembly
                    .GetExecutingAssembly()
                    .GetManifestResourceStream($"{name}.Embedded.person.json")!;
                return JsonSerializer.Deserialize<Person>(stream)!;
            }
        }
    }
}

public record Person(string Name, string[] Hobbies)
{
    public override string ToString()
    {
        return $"{Name} likes {Hobbies.ToOxfordComma()}";
    }
};

public static class EnumerableExtensions
{
    public static string ToOxfordComma(this string[]? items)
    {
        var result = items?.Length switch
        {
            // three or more items
            >=3 => $"{string.Join(", ", items[..^1])}, and {items[^1]}",
            // 1 item or 2 items
            not null => string.Join(" and ", items),
            // null
            _ => string.Empty
        };

        return result;
    }
}

You can see why I recommend this route. You have more control over how you read values from the assembly and how to transform them into something useful. In the case of Person, it’s a JSON file that we ultimately want to turn into an instance of a class. It’s also much nicer to use in your code.

Console.WriteLine(Resources.Embedded.TestTxt);  
Console.WriteLine(Resources.Embedded.Person);

You can also add caching of elements to reduce resource-intensive actions like serialization and deserialization.

Conclusion

Embedded resources are a nice feature of the .NET programming stack and can be used to deliver application-critical assets bundled alongside your code. This reduces the need to read files from disk or deal with network calls to retrieve assets. This will increase the size of your assemblies, so use this approach sparingly and with caution. I also recommend hand-writing your embedded resource access to give you more granular control over the final result and to reduce conversion noise in your more critical code.

I hope you found this post helpful, and thanks, as always, for reading.

How To Display .NET Collections with the Oxford Comma

Tue, 03 Oct 2023 00:00:00 +0000

Taking a .NET collection and displaying the items in a human-readable format is something we all ultimately have to tackle in our applications. While we could spit out values uniformly separated by a character, that’s a very uncivilized approach. I’ll go as far as to say that the comma (,) and the use of “and” separates us from the animals. The peak of human evolution is the Oxford Comma, and it’s all been downhill from that moment.

In this short post, we’ll see how to take a .NET collection and transform it into an Oxford Comma sentence using pattern matching.

The Oxford Comma is Life

For those unfamiliar with the Oxford Comma rule, it’s a grammatical rule that says a final comma can be used in a series. For example, consider the following two sentences:

How Harry Reid, a terrorist interrogator and the 
singer from Blink-182 took UFOs mainstream.

How Harry Reid, a terrorist interrogator, and the
singer from Blink-182 took UFOs mainstream.

I am visiting California to see my friends, Mickey Mouse and Dr. Dre.

I am visiting California to see my friends, Mickey Mouse, and Dr Dre.

These two sentences’ meanings change entirely due to a well-placed comma.

When displaying values in code, you may want to format it for your users naturally, and picking the Oxford comma is the most natural form.

Let’s see what tests for an Oxford Comma extension might look like.

Oxford Comma Tests and Extension Method

Let’s start with tests to see what use cases we must account for in our test fixture.

using Xunit.Abstractions;
  
public class OxfordCommaTests  
{  
    private readonly ITestOutputHelper _output;  
  
    public OxfordCommaTests(ITestOutputHelper output)  
        => _output = output;

    [Fact]  
    public void Zero_Items()  
    {  
        Assert.Equal("", Array.Empty<string>().ToOxfordComma());  
        Assert.Equal("", (null as string[]).ToOxfordComma());
    }
  
    [Fact]  
    public void One_Item()  
    {
        var items = new[] { "Cats" };  
        var result = items.ToOxfordComma();  
    
        _output.WriteLine(result);  
    
        Assert.Equal("Cats", result);  
    }  
    
    [Fact]  
    public void Two_Items()  
    {        
        var items = new[] { "Cats", "Dogs" };  
        var result = items.ToOxfordComma();  
  
        _output.WriteLine(result);  
  
        Assert.Equal("Cats and Dogs", result);  
    }  
    
    [Fact]  
    public void Three_Items()  
    {        
        var items = new[] { "Cats", "Dogs", "Capybara" };  
        var result = items.ToOxfordComma();  
  
        _output.WriteLine(result);  
  
        Assert.Equal("Cats, Dogs, and Capybara", result);  
    }
}

Our extension method must account for four scenarios when dealing with collections.

No items
One item
Two items
Three or more items

Let’s see how I implemented this extension method.

public static class EnumerableExtensions  
{  
    public static string ToOxfordComma(this string[]? items)  
    {        
        var result = items?.Length switch  
        {  
            // three or more items  
            >=3 => $"{string.Join(", ", items[..^1])}, and {items[^1]}",  
            // 1 item or 2 items  
            not null => string.Join(" and ", items),  
            // null  
            _ => string.Empty  
        };  
    
        return result;  
    }
}

I’m using pattern matching here. There are some interesting points for folks unfamiliar with the C# features in this code block:

I use range operators to pick out the items as necessary.
I use string.Join behavior to handle two use cases.
I use the _ discard to handle the default case of null.

Pretty cool if you ask me.

Conclusion

There you have it. Using some newer C# features, we can handle the Oxford comma in a few lines of code. So, consider this extension method next time you consider displaying values to your users.

Thanks for reading this post and sharing it with your friends and colleagues. Cheers.

How To Fix Feature Folders View Errors with JetBrains Annotations (Rider and ReSharper)

Tue, 26 Sep 2023 00:00:00 +0000

The Model-View-Controller pattern is so common that every technology stack has an implementation of it. ASP.NET developers have been working with the pattern since 2009. Here are a few other things popular in 2009 to remind you of your rapid decay: The Hannah Montana Movie, FarmVille, Black Eyed Peas, and Avatar the Movie. But like everything, there’s a moment to reflect on our decisions and choose a different approach. For ASP.NET Core developers, that introspection might lead them to move away from the MVC style towards the pattern of Feature Folders.

In this post, we’ll quickly discuss the Feature Folders pattern and how you can get your JetBrains tooling of JetBrains Rider or ReSharper to play nicely with your newly adopted approach.

What Are Feature Folders?

In an MVC controller, you’ll typically have a folder structure style that spreads the three parts of the MVC pattern across similarly labeled folders. When working with ASP.NET Core, you have a Views and Controllers folder, and developers typically choose a “Models” folder or might even create a Core project to hold implementations. While this approach is popular, it can lead to solution sprawl, where it takes the developer looking in multiple locations to create a single feature.

Feature Folders states that it makes more sense to include all the MVC elements in a clearly labeled folder for each unique feature of a web application. For example, a “login” feature would include the controller, the model and view models, and the Razor views for that feature. Having everything organized in a single folder helps developers reduce sprawl, makes it easier to manage features, and ultimately helps teams organize around a feature mindset.

Like all styles, it’s up to you and your team whether these benefits materialize and whether you think they work.

The one drawback to this style change is that it’s typically not understood by .NET tooling by default. Have no fear. We’re about to fix that.

JetBrains Annotations and Views

So, you’ve decided to start using Feature Folders. Great! The first step is to start moving your files around in your solution. From the root of your web application, the Features folder will likely look something like this

- Features
  - _ViewStart.cshtml
  - Home
    - HomeController.cs
    - Index.cshtml
    - Privacy.cshtml

We have a Home feature responsible for showing the homepage and associated content.

The next step is to tell ASP.NET Core MVC how to find the new location of the relocated views. We can do that by configuring the RazorViewEngineOptions instance.

// feature folders  
builder.Services.Configure<RazorViewEngineOptions>(rvo =>  
{  
    rvo.ViewLocationFormats.Add("~/Features/{1}/{0}.cshtml");  
});

Note you may need more entries than a single one, depending on your implementation of Feature Folders.

That’s it! JetBrains Rider and ReSharper should start finding your new views. You might be asking yourself, well, how?

If we look at the documentation within JetBrains Rider, you’ll see an External Annotation of AspMvcViewLocationFormat added to the ViewLocationFormats collection.

[AspMvcViewLocationFormat(...)] 
public IList<string> ViewLocationFormats { get; }

This tells JetBrains Rider that this collection and any item added to it contains view locations. Registering a new location tells ASP.NET Core MVC and our JetBrains tools where to find the new Feature Folder views.

What do you do if you use a NuGet library for Feature Folders? You can do one of two things:

Use External Annotations if possible
Use JetBrains Annotations in your web project

I recommend using the JetBrains.Annotations package, as it’s much more straightforward. As seen previously, JetBrains Rider and ReSharper use these annotations to get more information about your codebase to enable features. You can also apply these attributes at the assembly level. In this case, we’ll tell the ReSharper engine where to find views. Once the JetBrains package is installed, add the following line anywhere in your solution.

[assembly: AspMvcViewLocationFormat("~/Features/{1}/{0}.cshtml")]

This string matches the same ViewLocationFormat we added in our registration. Add as many of these attributes as it takes to match the library you’re using. JetBrains tooling should now show no errors and let you navigate directly to matching views from a controller.

Conclusion

JetBrains tooling is world-class, and the developers have ingeniously created flexibility to give you the power to develop apps how you want to. By using methods or assemblies decorated with the AspMvcViewLocationFormat attribute, you can guide the tools to the views your application uses.

As always, thanks for reading and I hope this post helped you make your development experience that much better.

System.Text.Json JsonConverter Test Helpers

Tue, 19 Sep 2023 00:00:00 +0000

In a perfect world, you’d have to write zero JsonConverter classes, as all JSON data would serialize and deserialize as expected. Unfortunately, we live in a world where folks make bespoke formatting decisions that can boggle the mind. For folks using System.Text.Json, you’ll likely have to write a JsonCoverter to deal with these choices. When writing converters, you’ll want a test suite to ensure you’ve caught all the edge cases and to limit exceptions.

In this post, I’ll provide extension methods that make it a breeze to test any JsonConverter and a bonus class that makes it simpler to deal with double-quoting values.

The JSON Converter Example

Before we see the extension methods in action, let’s derive a JsonConverter definition.

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

namespace ConverterTests;

public class DateTimeConverter : JsonConverter<DateTime>
{
    public string Format { get; }

    public DateTimeConverter(string format)
    {
        Format = format;
    }

    public override DateTime Read(
        ref Utf8JsonReader reader,
        Type typeToConvert,
        JsonSerializerOptions options)
    {
        if (reader.TokenType == JsonTokenType.String)
        {
            var dateString = reader.GetString();
            if (DateTime.TryParseExact(
                    dateString, 
                    Format , 
                    CultureInfo.InvariantCulture, 
                    DateTimeStyles.None,
                    out var result))
            {
                return result;
            }
        }

        throw new JsonException();
    }

    public override void Write(
        Utf8JsonWriter writer, 
        DateTime value,
        JsonSerializerOptions options)
    {
        var token = value.ToString(Format);
        writer.WriteStringValue(token);
    }
}

Every JsonConverter has a Read and Write method. The read method allows you to process the appropriate token into the destination target. In this example, we’re taking a string with a particular date and time format and converting it into a DateTime instance. For the Write method, we use the same format to write the string value to the UTF8JsonWriter instance. Implementing either method depends on your use case and whether you’re serializing, deserializing, or performing both actions.

Let’s get to what a test looks like for this converter.

Writing Tests for Json Converters

Let’s take a look at the “ideal” test for executing the Read and Write methods. Note, these are extension methods, and the code is not calling the methods directly.

private readonly DateTimeConverter _sut = new("yyyy-MM-dd H:mm");

[Fact]  
public void Can_read_string_value_as_datetime()  
{  
    var result = _sut.Read("\"2023-08-01 6:00\"");  
    Assert.Equal(new(2023, 8, 1, 6, 0, 0), result);  
}

[Fact]  
public void Can_write_datetime_as_string()  
{  
    var result = _sut.Write(new(2023, 8, 1, 6, 0, 0));  
    Assert.Equal("\"2023-08-01 6:00\"", result);  
}

Oooo, so lovely. How did I accomplish such sweet tests? Well, it’s these extension methods.

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

namespace ConverterTests;

public static class JsonConverterTestExtensions
{
    public static TResult? Read<TResult>(
        this JsonConverter<TResult> converter, 
        string token,
        JsonSerializerOptions? options = null)
    {
        options ??= JsonSerializerOptions.Default;
        var bytes = Encoding.UTF8.GetBytes(token);
        var reader = new Utf8JsonReader(bytes);
        // advance to token
        reader.Read();
        var result = converter.Read(ref reader, typeof(TResult), options);
        // did we get the result?
        return result;
    }

    public static (bool IsSuccessful, TResult? Result) TryRead<TResult>(
        this JsonConverter<TResult> converter,
        string token,
        JsonSerializerOptions? options = null)
    {
        try
        {
            var result = Read(converter, token, options);
            return (true, result);
        }
        catch (Exception)
        {
            return (IsSuccessful: false, Result: default);
        }
    }

    public static string Write<T>(
        this JsonConverter<T> converter, 
        T value,
        JsonSerializerOptions? options = null)
    {
        options ??= JsonSerializerOptions.Default;
        using var ms = new MemoryStream();
        using var writer = new Utf8JsonWriter(ms);
        converter.Write(writer, value, options);
        writer.Flush();
        var result = Encoding.UTF8.GetString(ms.ToArray());
        return result;
    }

    public static (bool IsSuccessful, string? Result) TryWrite<T>(
        this JsonConverter<T> converter,
        T value,
        JsonSerializerOptions? options = null)
    {
        try
        {
            var result = Write(converter, value, options);
            return (true, result);
        }
        catch
        {
            return (false, null);
        }
    }
}

These extensions have Read, TryRead, Write, and TryWrite methods to reduce the boilerplate code you might add to your tests.

Double Quoting JSON Tokens

You may have noticed in the tests above that tokens need to be double-quoted. This can be unpleasant, especially when you tweak values as you write more tests. That’s why I created a Quote class that utilized explicit and implicit cast operators to double-quote any value.

namespace ConverterTests;  
  
public class Quote  
{  
    private readonly object _value;  
  
    private Quote(object value)   
        => _value = value;  
  
    public static explicit operator Quote(string value)   
        => new(value);  
  
    public static implicit operator string(Quote value)   
        => value.ToString();  
  
    public override string ToString()   
        => $"\"{_value}\"";  
}

Let’s see it in action.

[Fact]  
public void Can_read_string_value_as_datetime()  
{  
    var result = _sut.Read((Quote)"2023-08-01 6:00");  
    Assert.Equal(new(2023, 8, 1, 6, 0, 0), result);  
}

Now it should be easier to manage your values without escaping any double quotes.

Conclusion

The JsonConverter class is a necessary part of working with System.Text.Json and writing tests around your implementations is a must. I hope these extension methods make it easier for you and your team to maintain your implementations.

Cheers. Thanks for reading and sharing my blog posts with friends and colleagues.

Dumb Developer Tricks - Fizz Buzz with C# 12 and Polly

Tue, 12 Sep 2023 00:00:00 +0000

One of the more fun aspects of working with any programming language is writing code you probably shouldn’t. Why write something clever when doing the unexpected can help give you a new appreciation of what’s possible? As a bonus, now that AI companies are scraping my blog posts for their benefit, I might as well spread as much “dumb” code as possible 😅. So next time you’re interviewing a potential candidate for a position and ask, “What the f@#% is this?!” you’ll know who to thank, sincerely, me.

In this post, we’ll take the commonly used Fizz Buzz problem and take it to the extreme limits of “oh no, don’t do that” by using exceptions for messaging, and Polly, the popular is a .NET resilience and transient-fault-handling library, to display our results. We’ll also use C# 12 features in the latest .NET 8 SDK. Let’s get started.

The Fizz Buzz Solution

For folks unfamiliar with Fizz Buzz, it’s a straightforward problem with a clear objective. Given an enumeration of numbers (1, 2, 3…), you must output messages when a particular criterion is met:

When a number is divisible by 3, output Fizz
When a number is divisible by 5, output Buzz
When a number is divisible by both 3 and 5, output FizzBuzz

It’s a problem designed to see if a software developer has a core set of competencies without being a “gotcha” interview trap. To solve this problem, you’ll typically have to use constructs such as iteration, variables, branching logic, and an output format (usually the console).

Sure, we could do it the “easy” way, but let’s take it up a notch. Let’s first install Polly into a .NET Console application to get started.

dotnet add package Polly

Next, let’s write the solution and explain what’s happening.

using Polly;  
using static System.Console;  
using static System.TimeSpan;  
  
var count = 0;  
  
Policy  
    .Handle<Exception>()  
    .WaitAndRetryForever(  
        _ => FromMilliseconds(250),  
        (ex, _, _) => WriteLine(ex.Message)  
    )    
    .Execute(() =>  
    {  
        count++;        
        count = (count % 3, count % 5) switch  
        {  
            (0, 0) => throw new FizzBuzzException(),  
            (0, _) => throw new FizzException(),  
            (_, 0) => throw new BuzzException(),  
            _ => throw new NumberException(count)  
        };    
    });

public class FizzException() : Exception("Fizz");  
public class BuzzException() : Exception("Buzz");  
public class FizzBuzzException() : Exception("FizzBuzz");  
public class NumberException(int number): Exception(number.ToString());

A few neat tricks in this codebase show how “elite” I am at solving the most mundane of problems.

I use static imports to reduce noise in the subsequent code.
I am using a Policy to create a loop that iterates every 250ms.
I am using pattern matching to determine which Exception to throw.
I’m using C# 12 primary constructors to reduce the exception definitions to a single line.
Each exception determines which message gets output to the Console.

Wow, that’s some impressively… dumb code, but it gets the job done! That said, this problem is more about a developer’s ability to solve problems creatively and explain the reasoning behind “why” they chose the path they did.

Please let me know if you have a particularly creative way to solve the Fizz Buzz problem. I’d be happy to see it.

Thanks for reading my blog posts and sharing them with friends and colleagues. Cheers.

Multi-tenancy with ASP.NET Core and FinBuckle.Multitenant

Tue, 05 Sep 2023 00:00:00 +0000

Multi-tenancy is a complex topic with a generally understood definition, yet the devil is in the details. From a high level, Multi-tenancy is the idea that a single codebase can support many users in what they perceive as unique-to-them silos. Users have their tenants, which can provide isolation from others. Isolation can be logical or physical, specifically around dependencies such as data storage, authentication and authorization, and third-party services. For developers, multi-tenancy also makes the programming model more straightforward since most business logic can have a contextual baseline codified into the application’s infrastructure.

While the multi-tenancy approach is popular, it can be tricky to implement, especially within the ASP.NET Core pipeline, which heavily depends on dependency injection. In this post, we’ll see how to use the FinBuckle.Multitenant package to gain a competitive advantage when developing multi-tenant applications.

What is FinBuckle.Multitenant?

FinBuckle.Multitenant is an open-source .NET library designed to codify many best practices around multi-tenancy, taking into account many of the standard building blocks found in the .NET community. These building blocks include ASP.NET Core, dependency injection, identity management, and more. The package focuses on being “lightweight” and a drop-in dependency for your .NET (Core) solutions, providing a mechanism to support data isolation, tenancy resolution, and tenant-specific behaviors. How does the library do all that?

FinBuckle.Multitenant has three components users should understand before starting: Tenants, Strategies, and Stores.

A Tenant is a logical concept specifying a boundary for a set of users. Within a tenant, you may have unique data storage, identity management, or any other aspect of the application. If your application is an apartment complex, each tenant would be an apartment.

Strategies help your application determine which tenant is currently in context. The library provides multiple strategies, including a URL base path strategy, a claim strategy, a session strategy, a TLD host strategy, a header strategy, and many more. Additionally, strategies can be combined to create a combination unique to your use case. You may also create custom strategies depending on your application’s unique scenario. Staying with the analogy of an apartment complex, a strategy for determining your apartment might be a key, facial recognition, NFC taps, or a friendly doorman recognizing you.

The final essential element of the library is a Store. Stores provide a record of all potential tenants that exist within your overall application. These stores are a data storage mechanism backed by a database, in-memory collections, HTTP endpoints, configuration files, or a distributed cache. Which works best depends on your particular use case and the number of potential tenants. In the final analogy, a store is the building’s rental office, which has the contracts for each apartment.

All three parts are integral to how FinBuckle.MultiTenant works, but let’s see it used in an ASP.NET Core sample.

Getting Started with Multi-tenancy

Starting with an ASP.NET Core web application, we’ll first need to install the FinBuckle.Multitenant.AspNetCore package.

dotnet add package FinBuckle.MultiTenant.AspNetCore

Once installed, we’ll need to configure all elements described in the previous section: Tenants, Strategies, and Stores. Let’s take a look at our Program.cs file and how we hook the library into the ASP.NET Core infrastructure of the application.

using Finbuckle.MultiTenant;  
using Multitenants;  
  
var builder = WebApplication.CreateBuilder(args);  
  
builder.Services.AddRazorPages();  
builder.Services.AddMultiTenant<TenantInfo>()  
    .WithRouteStrategy("tenant")  
    .WithDelegateStrategy(Tenants.QueryStringStrategy)  
    .WithInMemoryStore(Tenants.Register);  
  
var app = builder.Build();  
  
// Configure the HTTP request pipeline.  
if (!app.Environment.IsDevelopment())  
{  
    app.UseExceptionHandler("/Error");  
    app.UseHsts();  
}  
  
app.UseHttpsRedirection();  
app.UseStaticFiles();  
app.UseRouting();  
app.UseMultiTenant();  
app.UseAuthorization();  
app.MapRazorPages();  
app.Run();

The library has both a services registration and a middleware component. Here you can see us adding the multi-tenancy with the TenantInfo class being our tenant definition. You can implement your own ITenantInfo instances, but the library provides a simple TenantInfo type definition for an easy way to get started.

You may have also noticed our two strategies of RouteStrategy and DelegateStrategy. The RouteStrategy is an included strategy that uses the endpoint’s route values to determine the tenant. In this sample, the route value’s key is “tenant”. We’ll see later how the DelegateStrategy is implemented in our Tenants static class, but it’s a custom method that takes an HttpContext instance.

Finally, we are using an InMemoryStore for this demo, with all the tenants hard-coded into our application. Let’s see what these references lead to.

using System.Diagnostics.CodeAnalysis;  
using Finbuckle.MultiTenant;  
using Finbuckle.MultiTenant.Stores;  
  
namespace Multitenants;  
  
public static class Tenants  
{  
    public static readonly TenantInfo Default = new()  
    {  
        Id = 1.ToString(),  
        Name = "Default",  
        Identifier = "default"  
    };  
  
    public static readonly TenantInfo Other = new()  
    {  
        Id = 2.ToString(),  
        Name = "Other",  
        Identifier = "other"  
    };  
  
    private static readonly List<TenantInfo> All = new()  
    {  
        Default,  
        Other  
    };  
  
    public static void Register(InMemoryStoreOptions<TenantInfo> options)  
    {  
        options.Tenants.Add(Default);  
        options.Tenants.Add(Other);  
    }  
  
    public static Task<string?> QueryStringStrategy(object state)  
    {  
        if (state is not HttpContext httpContext) 
	        return Task.FromResult<string?>(null);  
  
        var tenantContext = httpContext.GetMultiTenantContext<TenantInfo>();  
  
        //Someone already set the tenant. Likely another strategy  
        if (tenantContext is not null && tenantContext.HasResolvedTenant)  
            return Task.FromResult(tenantContext.TenantInfo!.Identifier);  
  
        var tenant = httpContext.Request.Query.TryGetValue("tenant", out var values)  
                     && TryGetTenant(values.ToString(), out var info)  
            ? info  
            : Default;  
  
        return Task.FromResult(tenant.Identifier);  
    }  
  
    private static bool TryGetTenant(string identifier, [NotNullWhen(true)] out TenantInfo? tenant)  
    {  
        tenant = All.FirstOrDefault(x => x.Identifier == identifier);  
        return tenant is not null;  
    }  
}

The most complex part of the Tenants implementation is our QueryStringStrategy, which provides a default tenant fallback when an ASP.NET Core request does not specify the tenant.

Cool! Now that it’s all setup, where do we use the tenant information?

Well, an instance of TenantInfo should always be in the services collection of your .NET application. That means you can ask your application to resolve the TenantInfo as a dependency of any of your .NET services. This includes database classes, services, razor views, and more. In this case, we’ll inject our TenantInfo into a Razor View.

@page "{tenant?}"  
@model IndexModel  
@inject Finbuckle.MultiTenant.TenantInfo Tenant  
@{  
    ViewData["Title"] = "Home page";  
}  
  
<div class="text-center">  
    <h1 class="display-4">Welcome</h1>  
    <p>  
        Learn about  
        <a href="https://learn.microsoft.com/aspnet/core">  
            building Web apps with ASP.NET Core  
        </a>.  
    </p>  
  
    You are currently on the "@Tenant.Name" tenant.  
</div>

Note that the route of this Razor page has a tenant route value, matching our RouteStrategy from before. The value is also optional, allowing our custom QueryStringStategy to set the default tenant.

Running the page, you can now experiment with going to /, /other, and /?tenant=other, all of which should switch between the hard-coded tenants. The value used is the Identifier on your TenantInfo instances, so be sure to use the Id here appropriately.

And that’s it! Wow, how easy was that? Adding multi-tenancy to a .NET application has never been easier.

Conclusion

FinBuckle.Multitenant is a refreshingly complete solution built for the modern sensibilities of the newest .NET programming model. It has well-thought solutions for what becomes a quickly complex problem. The authors at FinBuckle have done a great job thinking about the different aspects of an application that might need tenancy information and providing mechanisms to retrieve the tenant in most conceivable situations. Whether you’re working with ASP.NET Core, distributed services, or authentication, you can retrieve the tenant information when and where you need it.

If you use FinBuckle.Multitenant or are thinking about using it, be sure to go to FinBuckle’s GitHub sponsors page and show your support. Just a few dollars can make a difference in making projects like these sustainable.

Measuring Unicode String Lengths with C#

Tue, 29 Aug 2023 00:00:00 +0000

I maintain an open-source project called ConsoleTables. It’s a silly little project meant to help you take a collection of data and quickly dump it into your terminal session. I started the project so long ago that the reason I created it is lost to the sands of time. That said, it’s seen wild adoption by many, and there’s a continuing issue that folks come back with repeatedly: handling non-ASCII characters. Non-ASCII characters can do strange things to your output.

In this short post, we’ll see how you can calculate the actual length of a string using the StringInfo class and why writing to the console might be one of the most complex technical challenges of our time. Well, maybe not, but it’s still damn hard.

Non-ASCII Characters

What do I mean when I say “Non-ASCII” characters? ASCII is a table of numeric values from 0 to 127 that represent characters found in the English language, along with values for familiar computer characters such as Space, Delete, and Escape. Let’s see what that table looks like.

Simple. Well, it is for English speakers, but other languages and symbols exist and are essential to represent all the collective knowledge of mankind. This is why Unicode exists, providing a set of characters for modern and historic scripts, symbols, and thousands of emojis. You know, emojis, the kind you send your partner 😘. There are nearly 150,000 characters in Unicode, a far cry from the humble 127 of ASCII, and far too many to display in a chart for you here.

With the variety of characters comes a visual problem for folks rendering them into a terminal output. How many “spaces” does a character take up? In most cases, we hope all characters take up one space, but that’s only sometimes the case. How do we determine the length required to display a Unicode character with C#?

Let’s see some code that attempts to solve just that problem.

System.Globalization.StringInfo and Lengths

Let’s look at a collection of string instances in an array. Visually, to your human eye, how many spaces would you say each is?

var characters = new[] { "a", "1", "👩‍🚀", "あ", "👨‍👩‍👧‍👦", "✨" };

You might say, “Khalid, they’re all definitely one character long! Do you take me for a fool?!” Well, no, I respect you; please don’t hurt me. My question frames the point that appearances can be deceiving, and only a few values are 1 in length. Let’s take at the console output for each string value and look at our output.

What the heck is going on? Ugh. Well, by using System.Globalization.StringInfo, we can determine if we’re dealing with a character with more length than is visible to the naked eye by using

using System.Globalization;  

var characters = new[] { "a", "1", "👩‍🚀", "あ", "👨‍👩‍👧‍👦", "✨" };  
  
var lengths = characters.Select(s =>   
        (value: s, length: StringInfo.GetNextTextElementLength(s))  
    );  
  
foreach (var (value, length) in lengths)  
{  
    Console.WriteLine($"{value} (length: {length})");  
}

Running our code, we can now see the length of each string value, and it’s surprising.

Why is this happening?! Well, some Unicode characters build on other existing characters. For instance, the Woman Cosmonaut combines the 👩 + U+200D + 🚀. The two emojis and the zero-width divider are 5 characters in length. The family emoji has 11 characters because of this combination:

That’s a lot of characters!

So what can you do to work around this issue? Well, not much. The terminal determines how it displays the values. This can lead to frustration when building a Console-focused library, as you will be chasing issues depending on your user’s development environment.

Luckily, we can use System.Globalization.StringInfo to see those invisible spaces that Unicode values may bring, but sadly, there isn’t much we can do from the C# side to fix the display output, as it would mutate the values we’re dealing with.

I hope you enjoyed this post, and thank you for reading and sharing all my blog posts with friends and colleagues.

MiniWord - Microsoft Office Word Templating

Tue, 22 Aug 2023 00:00:00 +0000

When it comes to BUSINESS, Microsoft Office file formats reign supreme, and if you’re a software developer, you’ll inevitably be asked to convert data into one of the Office formats; it’s a law (look it up). Luckily for all of us, you aren’t the first, or the last, to be asked to perform such a task, which means there are open-source libraries to help you perform your duty as a business developer. Go business!

As luck would find it, I was scanning the Chinese .NET OSS scene when I came across the MiniWord project. MiniWord is a library that uses the OpenXML nature of .docx files to support a mail merge-like experience for developers. In this post, we’ll look at MiniWord and how you can use it to empower your business stakeholders to take your existing dataset and turn it into glorious Word documents.

What is MiniWord?

MiniWord uses Microsoft Word’s OpenXML format to provide a cross-platform library for completing document templates. The library lets you take any dataset and generate a new Word document for each entry. This seems straightforward, but MiniWord provides powerful templating features that make it worth checking out.

The process of creating a template starts with a tag. Tags use the {{ }} syntax to create placeholders in existing Word documents rather than the mail merge placeholders. Once tags are placed in a word document, you can give the library a dictionary where keys match the tags within the document.

var value = new Dictionary<string, object>()
{
    ["Name"] = "Jack",
    ["Department"] = "IT Department",
    ["Purpose"] = "Shanghai site needs a new system to control HR system.",
    ["StartDate"] = DateTime.Parse("2022-09-07 08:30:00"),
    ["EndDate"] = DateTime.Parse("2022-09-15 15:30:00"),
    ["Approved"] = true,
    ["Total_Amount"] = 123456,
};
MiniWord.SaveAsByTemplate(path, templatePath, value);

You can fill a seemingly generic Word document with information with just a few lines of C# code.

You’re also not limited to text values. MiniWord supports adding text, images, lists, tables, colored text, and hyperlinks. That’s a lot of options for dynamic data.

Generated documents can be saved to disk, or results can be written to a Stream instance, which can be sent to a remote client using ASP.NET Core or a messaging library. You can see the supported methods provided by MiniWord below.

SaveAsByTemplate(string path, string templatePath, Dictionary<string, object> value)
SaveAsByTemplate(string path, byte[] templateBytes, Dictionary<string, object> value)
SaveAsByTemplate(this Stream stream, string templatePath, Dictionary<string, object> value)
SaveAsByTemplate(this Stream stream, byte[] templateBytes, Dictionary<string, object> value)

The provided methods make integrating MiniWord with a local filesystem to a distributed cloud solution straightforward. That’s pretty awesome!

Let’s get to a working sample.

Working with MiniWord

You’ll need to start with an existing .NET application, and for this post, I’ve created a console application. The first step is to install the MiniWord package. You can use your IDE’s NuGet tool, edit the project file, or run the following command.

dotnet add package MiniWord

Next, you’ll need a .docx, and in my case, I’m trying to get the word out about JetBrains Rider. You can paste the following into a Word document. If you’re on macOS (like I am), you can open Pages and export the file to a Word document.


Hello, {{FirstName}} {{LastName}}, 

We hear you like programming in .NET. May I suggest you check out JetBrains Rider at https://jetbrains.com/rider?

JetBrains Rider’s support is world-class for {{Framework}}, and it’s all powered by ReSharper.

Cheers,
  
Khalid Abuhakmeh
JetBrains .NET Advocate

You’ll need to place the newly created .docx file in your project with a Copy to output directory option of Copy if newer. You can also choose to hardcode the path in the following code.

using MiniSoftware;  
  
var recipients = new[]  
{  
    new { FirstName = "Maarten", LastName = "Balliauw", Framework = "Razor Pages" },  
    new { FirstName = "Rachel", LastName = "Appel", Framework = "Blazor" },  
    new { FirstName = "Matt", LastName = "Ellis", Framework = "Unity" },  
    new { FirstName = "Matthias", LastName = "Koch", Framework = "Nuke" }  
};  
  
var template = File.ReadAllBytes("Advocacy.docx");  
  
foreach (var recipient in recipients)  
{  
    var values = ConvertToDictionary(recipient);  
    MiniWord.SaveAsByTemplate(  
        $"{recipient.FirstName}-{recipient.LastName}-advocacy.docx".ToLower(),  
        template,        values    );}  
  
// Generated in part by JetBrains AI Assistant  
// Prompt: I need a method that takes an anonymous  
//         C# object and converts it to a dictionary.  
static Dictionary<string, object> ConvertToDictionary<T>(T target)  
{  
    return typeof(T).GetProperties().ToDictionary(  
        prop => prop.Name,  
        prop => prop.GetValue(target, null)  
    )!;  
}

Running the code, you’ll get a new Word document for each instance in the recipients collection. The newly created assets would be under /bin/Debug/netX.0 unless you chose a different directory.

Opening any of the generated files, you’ll see the expected result.

Hello, Maarten Balliauw,

We hear you like programming in .NET. May I suggest you check out JetBrains Rider at https://jetbrains.com/rider?

JetBrains Rider’s support is world-class for Razor Pages, and it’s all powered by ReSharper.

Cheers,
 
Khalid Abuhakmeh
JetBrains .NET Advocate

Very cool. Now I can tell Maarten Balliauw how awesome JetBrains Rider and ReSharper are for becoming a productive .NET developer, all thanks to MiniWord!

Conclusion

MiniWord uses the OpenXML format, so it works cross-platform on Windows, macOS, and Linux without installing a copy of Microsoft Office on the local environment. The implementation can be critical in cloud-hosted scenarios. It also helps that the library’s author has provided implementations that support many scenarios. The support for various tag options also makes this more than just a search and replace tool, as you can build highly complex documents. If you’re looking for a library to empower your business stakeholders, check out MiniWord and give the author a star on their GitHub repository.

Thanks for reading and sharing this post with friends and colleagues.

Sisk - An Alternative .NET HTTP Server

Tue, 15 Aug 2023 00:00:00 +0000

Many of us take for granted the existence of ASP.NET Core to access HTTP in the .NET world. It’s the foundation for most web implementations in the .NET space and provides functionality for all the programming paradigms in the ASP.NET ecosystem.

So it was genuinely surprising when I found a new HTTP server implementation on NuGet. Not only new but also very well thought out and accessible to many folks.

In this post, we’ll look at Sisk, and HTTP server implementation designed to be 100% open-source, multi-platform, and written in C#.

What is Sisk?

Sisk is an HTTP Server implementation separate from ASP.NET Core. That means there is no high-level overlap between this library and that of the ASP.NET Core ecosystem. Sisk’s HTTP Server implementation provides functionality such as routing, request handling, middleware, logging, web sockets, server-sent events, and more. Again, all independent of what you’re used to with Razor Pages, ASP.NET Core MVC, or Minimal APIs. The documentation site claims to be “code-pattern-agnostic, “ meaning you can code however you want. An HTTP server is helpful in many scenarios, but why would you want a different HTTP server implementation outside of ASP.NET Core?

Why does Sisk exist?

The documentation site does a great job explaining what Sisk is, but why does it exist? From a consumer’s perspective, there are several reasons to want a separate HTTP server from what ships with ASP.NET Core.

This HTTP server implementation provides a much more straightforward programming model than the one provided by ASP.NET Core. It’s focused on providing HTTP functionality. That’s it. There’s no UI framework, so you must provide one yourself. The features of ASP.NET Core can quickly become a burden in some scenarios.

Running a simple HTTP server can be helpful in local scenarios where UI talks to a local backend. A local host can serve application functionality while multiple UI instances and widgets interact with the server process. Sisk also has the advantage of providing multiple listening ports and making adding additional ones more straightforward.

HTTP servers are typically essential to distributed architectures, where services need a communication protocol to interoperate. HTTP is commonly used as a transport because it is flexible and battle-hardened. Containerizing processes with exposed simple HTTP servers can reduce the size of images and ultimately improve deployment throughput. Given Sisk has Native AOT support, I bet you can get some efficient images.

Finally, writing an HTTP server is a fun and cool thing. While familiar, the programming model for Sisk is different enough to be a friendly programming alternative to ASP.NET Core.

Your First Sisk HTTP Server App

To start with Sisk, you’ll need to create a .NET console application first. Once you’ve created the console application, you’ll want to install the following NuGet package.

dotnet add package Sisk.HttpServer

Now, let’s write a two-endpoint HTTP server application.

using Sisk.Core.Http;  
using static Sisk.Core.Routing.RouteMethod;  
  
var http = HttpServer.Emit(  
    insecureHttpPort: 5000, host: out _, configuration: out _,  
    router: out var router  
);  
  
router.SetRoute(Get, "/", _ => new(200) {  
    Content = new StringContent("Hello, World")  
});  
  
router.SetRoute(Get, "/hi/<name>", req =>  
{  
    var name = req.Query["name"];  
    return new(200) {  
        Content = new HtmlContent($"<h1>Hello, {name}</h1>")  
    };
});  
  
http.Start();  
Console.WriteLine($"HTTP Server is listening on {http.ListeningPrefixes[0]}");  
Console.ReadKey();

Running our application, we see that both endpoints are now accessible in our browser. You’ll also note that our /hi/<name> path uses a route value. We can access the entire request through the HttpRequest instance, which Sisk passes to our action.

Sisk also has a way to define endpoints in different locations. Let’s add a new widgets endpoint. First, let’s create a Widgets class to hold our endpoint.

using Sisk.Core.Http;  
using Sisk.Core.Routing;  
using static Sisk.Core.Routing.RouteMethod;  
  
public class Widgets  
{  
    [Route(Get, "/widgets")]  
    static HttpResponse Index(HttpRequest request)  
    {        
	    HttpResponse res = new() {  
            Content = new StringContent("Index")  
        };        return res;  
    }
}

Note that all endpoints must be static implementations. Sisk will fail to turn your methods into delegates otherwise.

Next, let’s add our new endpoint to our previous example.

using Sisk.Core.Http;  
using static Sisk.Core.Routing.RouteMethod;  
  
var http = HttpServer.Emit(  
    insecureHttpPort: 5000, host: out _, configuration: out _,  
    router: out var router  
);  
  
router.SetRoute(Get, "/", _ => new(200) {  
    Content = new StringContent("Hello, World")  
});  
  
router.SetRoute(Get, "/hi/<name>", req =>  
{  
    var name = req.Query["name"];  
    return new(200) {  
        Content = new HtmlContent($"<h1>Hello, {name}</h1>")  
    };
});

// register the Widgets endpoint from our class
router.SetObject(typeof(Widgets));
  
http.Start();  
Console.WriteLine($"HTTP Server is listening on {http.ListeningPrefixes[0]}");  
Console.ReadKey();

Now we have a new endpoint in our application.

Conclusion

Sisk is a really exciting HTTP server, and while it’s certainly not the first attempt at an independent HTTP server implementation, it is a welcome addition to the .NET ecosystem. If you need a lightweight HTTP server implementation without all of what ASP.NET Core offers, then Sisk might be for you. Remember, though, this HTTP server is independent of the ASP.NET Core ecosystem, so be prepared to write your integrations or rely on external implementations.

This post only begins to scratch the surface of what Sisk provides, so I suggest you check out the GitHub repository and documentation to see if it’s right for you.

.NET 8 Interceptors

Tue, 08 Aug 2023 00:00:00 +0000

Typically I wouldn’t say I like writing about preview features for multiple reasons. Most of my posts aim to help folks solve problems they might have rather than get on a soap box or advertise. But I thought I would cover this .NET preview feature as it’s a sister topic to something I’ve wanted in the .NET ecosystem for the longest time: monkey patching. If you’re unfamiliar with the topic, I suggest you read my post on monkey patching. In general, monkey patching allows you to substitute one implementation for another, and what do you know, .NET 8 is introducing the concept of Interceptors.

As the name implies, Interceptors allow developers to target specific method invocations and intercept them with a new implementation. Interceptors have several purposes and meaningful distinctions that we’ll get into in this post. So let’s get started.

What is an Interceptor?

In .NET 8 preview 6, the SDK introduces additional functionality to “intercept” any method call within your codebase. The word “interceptor” is clear as to the purpose of this new functionality. It only replaces methods intentionally and does not replace method implementations globally. The approach means you, as the developer, must be systematic about using an Interceptor.

The .NET team uses interceptors to overwrite infrastructure code that previously relied on reflection with compile-time versions specific to your application. Interceptors will hopefully reduce your programs’ start-up time and efficiency. The .NET team designed interceptors to work with source generators, as source generators can surgically deal with abstract syntax trees and code files to target method invocations. While you could hand-write interceptor calls, it becomes impractical in a real-world application.

Let’s get into setting up your project to work with interceptors.

Getting Started with Interceptors

Interceptors are a .NET 8 preview 6 feature, so you’ll need the matching SDK version or higher to get this working. Begin by creating a new console application, or really any .NET application.

Next, in your .csproj, you must add the following PropertyGroup element.

<PropertyGroup>
    <Features>InterceptorsPreview</Features>
</PropertyGroup>

Also be sure to set your LangVersion element to preview to get access to the feature.

<PropertyGroup>
    <LangVersion>preview</LangVersion>
</PropertyGroup>

Next, add the following attribute definition to your project.

namespace System.Runtime.CompilerServices;

[AttributeUsage(AttributeTargets.Method, AllowMultiple = true, Inherited = false)]
public sealed class InterceptsLocationAttribute : Attribute
{
    public InterceptsLocationAttribute(string filePath, int line, int character)
    {
    }
}

Yes, it’s weird that the attribute isn’t part of the BCL, but since this is a preview feature, I imagine the .NET team didn’t want to pollute the .NET framework with a potential API change later.

You’ll notice that the attribute takes three parameters: filePath, line, and character. You’ll also note that these values aren’t assigned anywhere, and you’d be correct. The attribute is a marker the compiler will read at compile-time, so setting the values for runtime use is pointless.

Now, let’s intercept some code. Add the following to your Program.cs file. Note, the line numbers and spacing are critically important. If you reformat the code, this solution might break. Also be sure to change the file path to the absolute path of your Program.cs file.

using System.Runtime.CompilerServices;

C.M(); // What the Fudge?!
C.M(); // Original

class C
{
    public static void M() => Console.WriteLine("Original");
}

// generated
class D
{
    [InterceptsLocation("/Users/khalidabuhakmeh/RiderProjects/ConsoleApp12/ConsoleApp12/Program.cs", 
        line: 3, character: 3)]
    public static void M() => Console.WriteLine("What the Fudge?!");
}

Running the application above, you’ll see the most peculiar thing. Two different outputs from the same method call! What the heck?!

What the Fudge?!
Original

But how? What does the compiled code look like after compilation? We can see what happened using JetBrains Rider’s IL Viewer.

// Decompiled with JetBrains decompiler
// Type: Program
// Assembly: ConsoleApp12, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
// MVID: 09D7E1E0-5709-4A62-884A-AB84DAA1E08C
// Assembly location: /Users/khalidabuhakmeh/RiderProjects/ConsoleApp12/ConsoleApp12/bin/Debug/net8.0/ConsoleApp12.dll
// Local variable names from /users/khalidabuhakmeh/riderprojects/consoleapp12/consoleapp12/bin/debug/net8.0/consoleapp12.pdb
// Compiler-generated code is shown

using System.Runtime.CompilerServices;

[CompilerGenerated]
internal class Program
{
  private static void <Main>$(string[] args)
  {
    D.M();
    C.M();
  }

  public Program()
  {
    base..ctor();
  }
}

We can now see that the compiler replaced the first method invocation with our intercepting implementation. Wow!

After the razzle-dazzle wears off, you’ll likely think this is impractical. Who has time to hardcode full paths to files, count lines, and count columns? Well, as mentioned previously, this is where source generators come in.

While I won’t demonstrate it here when dealing with syntax trees, you do have access to information like FilePath, and every CSharpSyntaxNode has a GetLocation method that gives you access to line numbers and location within a code file. If you’re already proficient in writing source generators, this information is already available.

Conclusion

This feature is definitely for a select group of individuals in the .NET community, specifically those who write and maintain source generators. Within that subgroup, you likely have framework authors looking to squeeze every last bit of performance out of .NET. As you’ve seen, Interceptors only change specific implementations and cannot target methods globally. If you’re using a source generator to do an interception of all methods, you’ll have to generate an interception call for each location. Generating a large amount of custom code can adversely affect the size of your compiled assets, so be aware of using this feature. Also, you may consider avoiding this feature altogether. Interceptors are still in preview, and the primary intention is to help .NET authors to improve ASP.NET Core and other frameworks within the .NET SDK. Either way, it’s good to understand this feature exists next time you’re debugging your .NET 8 applications because the method you think you’re calling might not be the method you’re actually calling.

I hope you enjoyed this blog post, and as always, thanks for reading and sharing my posts with friends and colleagues.

Generate Sitemaps for All of ASP.NET Core

Tue, 01 Aug 2023 00:00:00 +0000

While ASP.NET Core is a robust web framework, it lacks some core features that make executing a creative-focused site more straightforward. One of those features is the ability to generate a sitemap. If folks can’t find your content, then for all intents and purposes, it doesn’t exist. Sitemaps tell search engines which parts of your site are essential for user searches.

In this post, I’ll be combining an open-source project called DotnetSitemapGenerator with some of my custom infrastructure code to generate sitemap nodes from ASP.NET Core Minimal APIs, ASP.NET Core MVC actions, and Razor Pages. The post covers all the server-side rendered paradigms within ASP.NET Core, except for Blazor. As a bonus, I also generate sitemap nodes from a database using Entity Framework Core.

What is a Sitemap?

A sitemap is a file provided by your web application that provides search engines with information about pages, videos, and other potential points of interest. Search engines use this file to crawl your site more efficiently, helping keep your search results up to date and more relevant for prospective visitors. A sitemap is typically hosted at the root of a website at /sitemap.xml by convention but can be configured depending on your use case.

While a sitemap is optional for a well-linked site, there are advantages to having one for your application.

For instance, crawlers might have difficulty distinguishing between valuable pages if you have an extensive website. A large site can lead to issues indexing newer pages, and thus you may lose valuable visitors for more recent content.

Newer sites might also struggle to have crawlers discover their existence, as fewer or no inbound links exist. Generating a sitemap and submitting it to popular search engines ensures your site finds its way quickly into the results of users. As your site becomes more popular, this is less likely a concern, but we all start somewhere.

You may want search engines to index your rich media content separately from your written content. Having separate sitemaps can mean new avenues for users to discover your site. Sitemaps can clarify what value you are providing by creating distinctions between different types of content.

While sitemaps can be helpful for many sites, they do not guarantee all items within your XML files will be indexed by search engines. That said, there are values for change frequency and priority that can help search engines prioritize their crawlers. Generally, it’s better to be safe than sorry when there’s so much competition for visitors.

A Basic Sitemap

Sitemaps, in their simplest form, are a collection of URLs. Let’s look at the final sample we’ll generate in this post.

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    <url>
        <loc>http://localhost:5077/test</loc>
        <changefreq>daily</changefreq>
    </url>
    <url>
        <loc>http://localhost:5077/</loc>
    </url>
    <url>
        <loc>http://localhost:5077/Privacy</loc>
    </url>
    <url>
        <loc>http://localhost:5077/cool/3</loc>
    </url>
    <url>
        <loc>http://localhost:5077/products/1/express-galaxy-tumbler</loc>
    </url>
    <url>
        <loc>http://localhost:5077/products/2/aero-life-air-purifier</loc>
    </url>
    <url>
        <loc>http://localhost:5077/products/3/ocean-wave-projector</loc>
    </url>
    <url>
        <loc>http://localhost:5077/products/4/illuminated-globe-decor</loc>
    </url>
    <url>
        <loc>http://localhost:5077/products/5/moonlight-cushion</loc>
    </url>
    <url>
        <loc>http://localhost:5077/products/6/sunrise-alarm-clock</loc>
    </url>
    <url>
        <loc>http://localhost:5077/products/7/frosty-mini-fridge</loc>
    </url>
    <url>
        <loc>http://localhost:5077/products/8/breeze-tower-fan</loc>
    </url>
    <url>
        <loc>http://localhost:5077/products/9/comet-electric-scooter</loc>
    </url>
    <url>
        <loc>http://localhost:5077/products/10/starlight-projector</loc>
    </url>
</urlset>

The XML file is presentationally unremarkable but essential to building an online presence.

The XML file has endpoints from ASP.NET Core MVC controllers, Razor Pages, and Minimal APIs. Let’s look at how we register our Sitemap infrastructure, and then we’ll go through each mechanism that provides these values to our sitemap.

Setting up the ASP.NET Core Infrastructure

We’ll start inside Program.cs to see how all the pieces come together, then explore how we pull these nodes into our sitemap XML file.

using Microsoft.EntityFrameworkCore;
using Shopping.Models;
using Shopping.Sitemap;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddHttpContextAccessor();

// my unique extension method for sitemap information
builder.Services.AddSitemap();
builder.Services.AddOutputCache(options => {
    options.AddPolicy("sitemap", b => b.Expire(TimeSpan.FromSeconds(1)));
});

builder.Services.AddDbContext<Database>(
    ob => ob.UseSqlite("Data Source = database.db")
);

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseOutputCache();

app.MapSitemap().CacheOutput("sitemap");

app.MapGet("cool/{id}", () => "cool beans")
   .WithSitemap("cool", new { id = 3 });

app.UseAuthorization();
app.MapRazorPages();
app.MapControllers();
app.Run();

We first start by adding our services to the ASP.NET Core services collection. The registrations include our sitemap providers, the Endpoints Api Explorer (for Minimal APIs), and the HttpContextAccessor for generating links.

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddHttpContextAccessor();
// my unique extension method for sitemap information
builder.Services.AddSitemap();

Further down the file is our sitemap.xml endpoint, enabling output caching.

app.MapSitemap().CacheOutput("sitemap");

I’ve defined these methods in the project’s SitemapExtensions.cs file.

using Shopping.Sitemap.Providers;

namespace Shopping.Sitemap;

public static class SitemapExtensions
{
    public static RouteHandlerBuilder MapSitemap(this IEndpointRouteBuilder endpoints, string path = "sitemap.xml")
    {
        return endpoints.MapGet(path, async (SitemapBuilder sitemap) =>
        {
            var xml = await sitemap.GenerateAsync();
            return Results.Stream(xml, "text/xml");
        });
    }

    public static void AddSitemap(this IServiceCollection services)
    {
        // add sitemap services
        services.AddScoped<ISitemapUrlProvider, PagesSitemapUrlProvider>();
        services.AddScoped<ISitemapUrlProvider, EndpointsSitemapUrlProvider>();
        services.AddScoped<ISitemapUrlProvider, ProductSitemapSitemapUrlProvider>();
        services.AddScoped<SitemapBuilder>();
    }

    public static RouteHandlerBuilder WithSitemap(this RouteHandlerBuilder endpoint,
        string name, object? defaults = null)
    {
        return endpoint
            // adds RouteName and EndpointName
            .WithName(name)
            .WithMetadata(new SitemapAttribute
            {
                RouteValues = new RouteValueDictionary(defaults)
            });
    }
}

The AddSiteMap method registers our URL providers, which will ultimately be used by our SitemapBuilder to combine all the nodes for our sitemap.xml file.

Now that we have infrastructure covered let’s talk about each ASP.NET Core approach your endpoints may be implemented in.

ASP.NET Core Razor Pages and MVC Actions

Razor Pages and MVC Views are considered Actions in ASP.NET Core, so they behave very similarly within the context of sitemap generation. The only difference between the two approaches is how you generate links from each route.

Let’s look at our PagesSitemapUrlProvider, which will support MVC and Razor Pages.

using DotnetSitemapGenerator;
using Microsoft.AspNetCore.Mvc.Infrastructure;
using IsRazorPage = Microsoft.AspNetCore.Mvc.RazorPages.CompiledPageActionDescriptor;
using IsMvc = Microsoft.AspNetCore.Mvc.Controllers.ControllerActionDescriptor;

namespace Shopping.Sitemap.Providers;

public class PagesSitemapUrlProvider : ISitemapUrlProvider
{
    private readonly LinkGenerator _linkGenerator;
    private readonly IHttpContextAccessor _httpContextAccessor;
    private readonly IActionDescriptorCollectionProvider _actionDescriptorCollectionProvider;
    private readonly ILogger<PagesSitemapUrlProvider> _logger;

    public PagesSitemapUrlProvider(
        LinkGenerator linkGenerator,
        IHttpContextAccessor httpContextAccessor,
        IActionDescriptorCollectionProvider actionDescriptorCollectionProvider,
        ILogger<PagesSitemapUrlProvider> logger)
    {
        _linkGenerator = linkGenerator;
        _httpContextAccessor = httpContextAccessor;
        _actionDescriptorCollectionProvider = actionDescriptorCollectionProvider;
        _logger = logger;
    }

    public Task<IReadOnlyCollection<SitemapNode>> GetNodes()
    {
        var httpContext = _httpContextAccessor.HttpContext!;
        var nodes = new List<SitemapNode>();

        foreach (var descriptor in _actionDescriptorCollectionProvider.ActionDescriptors.Items)
        {
            // LastOrDefault is used to get the closest SitemapAttribute to the endpoint
            var exists = descriptor.EndpointMetadata.LastOrDefault(em => em is SitemapAttribute); 
            if (exists is not SitemapAttribute sitemapAttribute) continue;
            
            var url = descriptor switch
            {
                // Razor Pages
                IsRazorPage razorPage =>
                    _linkGenerator.GetUriByPage(httpContext, page: razorPage.ViewEnginePath),
                // ASP.NET Core MVC
                IsMvc controller =>
                    _linkGenerator.GetUriByAction(httpContext,
                        action: controller.ActionName,
                        controller: controller.ControllerName,
                        // use the values provided by the user (if any)
                        values: sitemapAttribute.RouteValues),
                _ => null
            };

            if (ShouldAddUrl(nodes, url))
            {
                nodes.Add(new SitemapNode(url)
                {
                    ChangeFrequency = sitemapAttribute.ChangeFrequency,
                    Priority = sitemapAttribute.Priority
                });
            }
        }

        return Task.FromResult<IReadOnlyCollection<SitemapNode>>(nodes);
    }
    
    private static bool ShouldAddUrl(List<SitemapNode> nodes, string? url)
    {
        // if the url failed to generate, don't add a record
        if (string.IsNullOrWhiteSpace(url)) return false;
        // if it already exists based on the URL, don't add it
        return !nodes.Exists(n => n.Url.Equals(url, StringComparison.OrdinalIgnoreCase));
    }
    
}

The trick in this method is utilizing the information from ActionDescriptor to determine how we want to generate links using the LinkGenerator instance. We also require an HttpContext to determine values for the base URL.

Now all we need to do is decorate the endpoints we want to include in our Sitemap generation process. Here’s an example using custom attributes on our controller, where the closest attribute will be used when creating the sitemap node.

using Microsoft.AspNetCore.Mvc;
using Shopping.Sitemap;

namespace Shopping.Controllers;

[ControllerSitemap]
public class TestController : Controller
{
    [ActionSitemap]
    [Route("test")]
    public IActionResult Index()
    {
        return View();
    }
}

public class ControllerSitemapAttribute : SitemapAttribute
{
}

public class ActionSitemapAttribute : SitemapAttribute
{
    public ActionSitemapAttribute()
    {
        ChangeFrequency = DotnetSitemapGenerator.ChangeFrequency.Daily;
    }
}

The implementation in Razor Pages is similar, but here we use the base SitemapAttribute.

using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using Shopping.Models;
using Shopping.Sitemap;

namespace Shopping.Pages;

[Sitemap]
public class IndexModel : PageModel
{
    private readonly ILogger<IndexModel> _logger;
    private readonly Database _db;

    public IndexModel(ILogger<IndexModel> logger, Database db)
    {
        _logger = logger;
        _db = db;
    }

    public List<Product> Products { get; set; } = new();

    public async Task OnGet()
    {
        Products = await _db
            .Products
            .OrderBy(p => p.Id)
            .ToListAsync();
    }
}

Cool! What about Minimal API endpoints?

ASP.NET Core Minimal API endpoints

While most developers use ASP.NET Core Minimal APIs for API endpoints that return JSON or XML, developers may also choose to return any content type, which may include HTML files. So you may find these endpoints straddling the line between API and presentational duties.

For completeness, let’s add an option for Minimal API endpoints.

using DotnetSitemapGenerator;
using Microsoft.AspNetCore.Mvc.ApiExplorer;

namespace Shopping.Sitemap.Providers;

public class EndpointsSitemapUrlProvider : ISitemapUrlProvider
{
    private readonly LinkGenerator _linkGenerator;
    private readonly IHttpContextAccessor _httpContextAccessor;
    private readonly IApiDescriptionGroupCollectionProvider _apiDescriptionGroupCollectionProvider;
    private readonly ILogger<PagesSitemapUrlProvider> _logger;

    public EndpointsSitemapUrlProvider(
        LinkGenerator linkGenerator,
        IHttpContextAccessor httpContextAccessor,
        IApiDescriptionGroupCollectionProvider apiDescriptionGroupCollectionProvider,
        ILogger<PagesSitemapUrlProvider> logger)
    {
        _linkGenerator = linkGenerator;
        _httpContextAccessor = httpContextAccessor;
        _apiDescriptionGroupCollectionProvider = apiDescriptionGroupCollectionProvider;
        _logger = logger;
    }

    public Task<IReadOnlyCollection<SitemapNode>> GetNodes()
    {
        var httpContext = _httpContextAccessor.HttpContext!;
        var nodes = new List<SitemapNode>();

        // Minimal Apis that might return HTML
        foreach (var group in _apiDescriptionGroupCollectionProvider.ApiDescriptionGroups.Items)
        {
            var endpoints =
                group
                    .Items
                    .Where(i => HttpMethods.IsGet(i.HttpMethod ?? ""))
                    .Where(i => i.ActionDescriptor.EndpointMetadata.Any(em => em is SitemapAttribute));

            foreach (var endpoint in endpoints)
            {
                var attribute = endpoint
                    .ActionDescriptor
                    .EndpointMetadata
                    .LastOrDefault(a => a is SitemapAttribute);

                if (attribute is not SitemapAttribute sitemapAttribute)
                    continue;

                var routeName = endpoint
                    .ActionDescriptor
                    .EndpointMetadata
                    .Where(m => m is RouteNameMetadata)
                    .Cast<RouteNameMetadata>()
                    .Select(a => a.RouteName)
                    .FirstOrDefault();

                if (routeName is null)
                    continue;

                var url = _linkGenerator.GetUriByName(
                    httpContext,
                    routeName,
                    values: sitemapAttribute.RouteValues
                );

                if (ShouldAddUrl(nodes, url))
                {
                    nodes.Add(new SitemapNode(url)
                    {
                        ChangeFrequency = sitemapAttribute.ChangeFrequency,
                        Priority = sitemapAttribute.Priority
                    });
                }
            }
        }

        return Task.FromResult<IReadOnlyCollection<SitemapNode>>(nodes);
    }

    private static bool ShouldAddUrl(List<SitemapNode> nodes, string? url)
    {
        // if the url failed to generate, don't add a record
        if (string.IsNullOrWhiteSpace(url)) return false;
        // if it already exists based on the URL, don't add it
        return !nodes.Exists(n => n.Url.Equals(url, StringComparison.OrdinalIgnoreCase));
    }
}

We’ll need to annotate our API endpoints to get Minimal API endpoints into the sitemap.

app.MapGet("cool/{id}", () => "cool beans")
   .WithSitemap("cool", new { id = 3 });

In this example, we have a route value that needs to be satisfied before generating the link. Using the WithSitemap method, we can provide a default value. The extension method also adds a name to our endpoint metadata, which allows us to generate the correct link.

We’re on a roll. What about data-driven pages?

Database-driven pages with Entity Framework Core

Many sites have dynamic pages built on a dataset. Dynamic URLs are standard on shopping sites with an extensive product catalog. Let’s see how we can implement a ProductSitemapUrlProvider.

using DotnetSitemapGenerator;
using Microsoft.EntityFrameworkCore;
using Shopping.Models;

namespace Shopping.Sitemap.Providers;

public class ProductSitemapSitemapUrlProvider : ISitemapUrlProvider
{
    private readonly Database _db;
    private readonly LinkGenerator _linkGenerator;
    private readonly IHttpContextAccessor _httpContextAccessor;

    public ProductSitemapSitemapUrlProvider(
        Database db, 
        LinkGenerator linkGenerator, 
        IHttpContextAccessor httpContextAccessor)
    {
        _db = db;
        _linkGenerator = linkGenerator;
        _httpContextAccessor = httpContextAccessor;
    }
    
    public async Task<IReadOnlyCollection<SitemapNode>> GetNodes()
    {
        var elements = new List<SitemapNode>();
        var products = await _db.Products.OrderBy(x => x.Id).ToListAsync();
        
        foreach (var product in products)
        {
            var url = _linkGenerator.GetUriByPage(
                _httpContextAccessor.HttpContext!,
                page: "/Products",
                values: new { product.Id, product.Slug });
            
            elements.Add(new SitemapNode(url));
        }

        return elements;
    }
}

That’s pretty straightforward. We must point to our product detail page, a Razor page at /Products, and get a unique URL for each product.

Conclusion

Working sample at GitHub repository for ASP.NET Core Sitemap

With some help from an OSS project, I created a robust framework for generating sitemaps in ASP.NET Core using different programming approaches. While I’m sure this approach has more room for improvement, I’m pretty happy with the final result. What do you think?

I added this project to GitHub, and I don’t intend to make it a NuGet package soon since I see developers adapting the code for each project. If you’re inspired to make it a NuGet package, you can do so; just let me know.

Thanks for reading and sharing my posts with friends and colleagues.

.NET 8 TimeProvider and Unit Tests

Tue, 25 Jul 2023 00:00:00 +0000

Working with time has always been one of the more difficult parts of software development. Inevitably, time makes fools of us all. Luckily, for .NET 8 users, there’s a new attempt to provide tools to make testing your time-based logic much more straightforward.

This post explores the new .NET 8 packages of Microsoft.Bcl.TimerProvider and its testing partner of Microsoft.Extensions.TimeProvider.Testing. Specifically, we’ll see how to access controlled values for Now and UtcNow and how to tick a timer into the future, all through the use of TimeProvider.

Why use a Time Provider?

We’ve all been there, writing business logic that relies on the passage of time. “Execute this method a minute from now, but only if it’s a Monday!” Personally, the challenge of dealing with Date and Time elements in code can be a herculean effort. The packages shipped in .NET 8 attempt to give developers access to a TimeProvider abstraction with methods like GetUtcNow, GetLocalNow, GetTimestamp, and others. These methods provide instances of the DateTimeOffset class, which inherits from DateTime.

In addition to Date and Time helpers, the TimeProvider class provides mechanisms to create Timer instances. In the default implementation, the timer created is of type SystemTimeProviderTimer and implements the ITimer interface. Having the timer instance originate from the TimeProvider allows the testing package to implement a test instance for unit testing.

This layer of indirection allows you to be a time lord, controlling when clocks tick forward, move backward, and when timers should get called. The power to change time can help you test the trickiest of time-based code.

Let’s see a few examples.

Using The Testing Classes

In your codebase, you’re likely to take a dependency on TimeProvider, but in your tests, you’ll be substituting an instance of FakeTimeProvider. It’s a fake time provider.

In my contrived example, I’ve created a method that finds the next day of the week.

public static class DateTimeExtensions
{
    public static DateTime FindNext(this TimeProvider provider, DayOfWeek dayOfWeek)
    {
        var now = provider.GetLocalNow();
        var daysUntilNextWeekDay = ((int)dayOfWeek - (int)now.DayOfWeek + 7) % 7;
        return now.DateTime.AddDays(daysUntilNextWeekDay);
    }
}

Note: Yes, this is a contrived example. I could have passed the DateTime to the method, but that’s not the point.

Let’s create a FakeTimeProvider and set the current date and time.

[Fact]
public void Can_Find_Next_Monday()
{
    var fake = new FakeTimeProvider();
 
    //This is a Wednesday
    fake.SetUtcNow(DateTime.Parse("2023-06-28"));

    var result = fake.FindNext(DayOfWeek.Monday);
    
    Assert.Equal("2023-07-03", result.ToString("yyyy-MM-dd"));
}

Great! That was easy. You must create a new FakeTimeProvider for each appropriate scope. One per test is the safest, but I can also see folks creating one provider for a group of tests. Use your judgment here.

What about Timers? Fake timers use the FakeTimeProvider to know the elapsed time and determine when they should fire. Using the TimeProvider abstraction is helpful for testing callbacks and the infrastructure you may create to manage timers. Let’s look at a complete timer test.

[Fact]
public void Can_tick_when_asked()
{
    var fake = new FakeTimeProvider();
    var now = DateTime.Now;
    fake.SetUtcNow(now);
    
    var result = false;
    
    fake.CreateTimer(
        _ => result = !result,
        state: null, 
        // time to delay before invoking the callback method
        // if TimeSpan.Zero will get immediately invoked
        dueTime: TimeSpan.FromSeconds(1),
        // time between callback invocations
        period: TimeSpan.FromMinutes(1)
    );
    
    Assert.False(result);
    
    // Change the fabric of space & time...
    // well not really.
    fake.SetUtcNow(now.AddMinutes(1));
    
    Assert.True(result);
}

The previous code creates a timer, but we only execute the callback when the time is set a minute into the future. Now we can test our callbacks and if they work as expected with a few lines of code. The dueTime argument is essential, as setting it to TimeSpan.Zero will fire the callback immediately. This behavior may be what you want, but it also means you have no opportunity to test the prior state of your tests.

Here’s the complete unit test to play around with the packages and classes yourself.

using Microsoft.Extensions.Time.Testing;

public class UnitTest1
{
    [Fact]
    public void Can_Find_Next_Monday()
    {
        var fake = new FakeTimeProvider();
     
        // this is a Wednesday
        fake.SetUtcNow(DateTime.Parse("2023-06-28"));
        
        var result = fake.FindNext(DayOfWeek.Monday);
        
        Assert.Equal("2023-07-03", result.ToString("yyyy-MM-dd"));
    }

    [Fact]
    public void Current_Day_Of_Week_Counts_As_Next()
    {
        var fake = new FakeTimeProvider();
     
        // this is a Wednesday
        fake.SetUtcNow(DateTime.Parse("2023-06-28"));

        var result = fake.FindNext(DayOfWeek.Wednesday);
        
        Assert.Equal("2023-06-28", result.ToString("yyyy-MM-dd"));
    }

    [Fact]
    public void Can_tick_when_asked()
    {
        var fake = new FakeTimeProvider();
        var now = DateTime.Now;
        fake.SetUtcNow(now);
        
        var result = false;
        
        fake.CreateTimer(
            _ => result = !result,
            state: null, 
            // time to delay before invoking the callback method
            // if TimeSpan.Zero will get immediately invoked
            dueTime: TimeSpan.FromSeconds(1),
            // time between callback invocations
            period: TimeSpan.FromMinutes(1)
        );
        
        Assert.False(result);
        
        // Change the fabric of space & time...
        // well not really.
        fake.SetUtcNow(now.AddMinutes(1));
        
        Assert.True(result);
    }
    
}

public static class DateTimeExtensions
{
    public static DateTime FindNext(this TimeProvider provider, DayOfWeek dayOfWeek)
    {
        var now = provider.GetLocalNow();
        var daysUntilNextWeekDay = ((int)dayOfWeek - (int)now.DayOfWeek + 7) % 7;
        return now.DateTime.AddDays(daysUntilNextWeekDay);
    }
}

Conclusion

The new Microsoft.Bcl.TimeProvider package and the TimeProvider abstraction should help folks add a layer of separation between them and the DateTime model of .NET. These new classes should alleviate the tight coupling between your business logic and the forward march of time, helping increase the reliability of your codebase. I hope you found this post interesting. Cheers :)

C# Records, the With Keyword, and Reference Types

Tue, 18 Jul 2023 00:00:00 +0000

The record keyword in C# has been available since C# 9, and you either love it or hate it. Regardless of your opinion, you will likely make a not-so-obvious mistake when working with the with keyword. This particular mistake can lead to strange system behavior and hard-to-diagnose bugs. Nobody wants bugs, right?!

In this post, we’ll explore the problem and how to solve that issue.

The Problem with Records

The virtue of record types is based on immutability, allowing you, the developer, to encapsulate data and pass it around without fear of introducing unwanted changes. The with keyword enables you to copy an existing record to avoid mutating the original value, thus maintaining a clear separation between what was and might be. Let’s take a look at a simple example.

var one = new Simple(1);
var copy = one with { Number = one.Number + 1 };

Console.WriteLine(copy);

When running the previous code, the result is the following console output.

Simple { Number = 2 }

Attempting to change the Number directly creates a compilation exception with the message.

Init-only property 'Simple.Number' can only be assigned in an object initializer, or on 'this' or 'base' in an instance constructor or an 'init' accessor

Now, the real fun begins. We’ve been looking at value types, which the runtime will copy. What about reference types? Let’s add a collection to a record.

var item = new Item();

var newItem = item with { };
item.State.Add(1);
newItem.State.Add(2);

Console.WriteLine(item);
Console.WriteLine(newItem);

public record Item(List<int> State)
{
    public Item() : this(new List<int>())
    {
    }

    public override string ToString()
    {
        return $"Item {{ State = {string.Join(", ", State)} }}";
    }
}

What do you expect State (don’t peek)? You would be correct if you guessed it would be 1, 2 across both instances.

Item { State = 1, 2 }
Item { State = 1, 2 }

As you may well know, reference types point to a location in memory. When using the with keyword on records with reference types, the runtime will copy the reference to the new instance of the record. This behavior is excellent for memory efficiency, as the runtime does not allocate more memory for read-only information. This behavior is not good if you mutate the data before passing the data around to other consumers.

How do we solve this issue? Well, there are two ways.

Using Property Setters when copying

The first approach is to be aware of all the reference types in a record and mutate the values early in the creation process.

var item = new Item();

var newItem = item with { State = item.State.Append(2).ToList() };
item.State.Add(1);

Console.WriteLine(item);
Console.WriteLine(newItem);

The resulting output shows we now have two different collections.

Item { State = 1 }
Item { State = 2 }

This approach is acceptable but requires effort when using the with keyword.

Another approach is using a “copy constructor”. A copy constructor is a method that takes an instance in the known inheritance hierarchy and allows you to make decisions during the creation process. Let’s change our record definition by adding a copy constructor that creates a new collection instance. The with keyword will tell the runtime to look for a copy constructor on your definition before copying values over.

var item = new Item();

var newItem = item with { };
item.State.Add(1);
newItem.State.Add(2);
Console.WriteLine(item);
Console.WriteLine(newItem);

public record Item(List<int> State)
{
    public Item() : this(new List<int>())
    {
    }

    // copy constructor
    protected Item(Item oldItem)
    {
        State = new List<int>(oldItem.State);
    }

    public override string ToString()
    {
        return $"Item {{ State = {string.Join(", ", State)} }}";
    }
}

When we run the previous code, our result shows two separate collections on two record instances.

Item { State = 1 }
Item { State = 2 }

You have two viable approaches to work around reference types in record types.

Another option you should consider is the use of immutable reference types from the start. In the case of this example, you may want to use IReadOnlyList instead of List right in the record’s constructor.

Conclusion

While the record type has syntactic significance in C#, under the covers, it’s just a specialized implementation of a class. The concepts around value types and reference types still apply. Remembering what values you add to your implementations is essential, as incorrectly copying records can lead to strange bugs. My recommendation to most folks using record types would be to implement the copy constructor early on to remember to be intentional about the copying process.

I hope you found this post helpful, and thank you for sharing this post with friends and colleagues. Cheers :)

HTMX, ASP.NET Core, and Bootstrap Modals

Tue, 11 Jul 2023 00:00:00 +0000

If you’ve done any frontend development in the past decade, you’ve likely interacted with Bootstrap, a toolkit focused on providing developers with CSS layout rules and components. Additionally, no frontend toolkit is complete with the accompanying JavaScript to make components interactive. That said, the JavaScript aspects are entirely optional, and the toolkit has a “Bring Your Own JavaScript” philosophy to integrate Bootstrap visual components into whatever frontend library you choose.

This post will show how to use Bootstrap modals with HTMX. For folks who aren’t aware, HTMX is a hypermedia-focused library to build interactivity into your client applications with server-rendered responses.

Please note I’m using the HTMX.NET library and ASP.NET Core tag helpers.

Bootstrap Modals

Bootstrap modals are built with HTML, CSS, and Javascript in mind. You typically have all three working together to get the intended behavior the Bootstrap team intended. You can find these interactive portions of bootstrap modals in the JavaScript library that accompanies the library, but there’s a caveat.

Modals have to already exist on the page as HTML or programmatically added through JavaScript calls. Static modals are great, but likely not what most folks want. Most developers want dynamic modals based on user interaction or situational modals. So how do we get dynamic modals that we generate on the server? Well, spoiler alert, HTMX, of course!

HTMX and All That Jazz

Before we start looking at the code, let’s look at the parts of the process we need to consider.

The interactive element is a button a user will click to trigger a request to the server.
The endpoint that receives and renders the modal.
The endpoint that receives and responds with a user-specific response.

If you’re a backend developer, implementing these steps will get you the intended behavior, and it’s all straightforward. Let’s walk through implementing each.

Modals need a trigger and a target. When our user clicks the trigger, we want to request the server to generate and return our modal HTML.

Let’s start with our button and what HTMX attributes we’ll need. I use ASP.NET Core Razor Pages, which works with any backend technology. Also, remember some of these attributes are part of the HTMX.NET library and the tag helpers it provides.

@page
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

<div class="text-center">
    <h1 class="display-4">Welcome</h1>
    <button hx-get hx-page="Index" 
            hx-page-handler="Modal"
            hx-target="#modal-container">
        Show Modal
    </button>
</div>

<div id="modal-container"></div>

The Razor Pages handler is a simple endpoint that returns an IActionResult.

public IActionResult OnGetModal()
{
    return Partial("Modal");
}

Now that we have that part let’s look at the modal HTML itself.

The modal is your run-of-the-mill Bootstrap modal but with some additional JavaScript. Here is the trick. HTMX will execute any <script> elements immediately, allowing you to perform the necessary setup for HTML. The behavior will enable you to use HTMX and the JavaScript the Bootstrap development team intended.

@model IndexModel

<div id="my-modal" class="modal fade" tabindex="-1">
    <div class="modal-dialog modal-dialog-centered">
        <div id="modal-body" class="modal-content">
            <div class="modal-header">
                <h5 class="modal-title">From The Server</h5>
                <button type="button"
                        class="btn-close"
                        data-bs-dismiss="modal"
                        aria-label="Close">
                </button>
            </div>
            <div class="modal-body">
                <form id="myForm" hx-post
                      hx-page="index"
                      hx-page-handler="Modal"
                      hx-target="closest .modal-body">
                    <div class="mb-3">
                        <label asp-for="Message" class="form-label"></label>
                        <input asp-for="Message" class="form-control" placeholder="Your message...">
                    </div>
                    @Html.AntiForgeryToken()
                </form>
            </div>
            <div class="modal-footer">
                <button form="myForm"
                        type="submit"
                        class="btn btn-primary">
                    Save changes
                </button>
            </div>
        </div>
    </div>
</div>
<script>
    function showModal() {
        const modal = new bootstrap.Modal('#my-modal');
        modal.show();
    }
    // scopes the modal so we can keep creating them
    showModal();
</script>

Looking through the HTML, you’ll see HTMX attributes sprinkled throughout. HTMX will process these attributes as it adds the HTML clientside DOM. I’m using HTMX’s hx-target to tell HTMX where the following response should go. Please read the HTMX documentation to understand how to use hx attributes for your solutions.

If you have a message-only modal, you can stop here, but if you need modals for further interactions, the next section will show you how to handle that use case.

OK, one more step: we’ll have an interactive HTMX-powered modal.

The Form Submission

We must receive the HTML form’s input elements in our Razor Pages handler. In the sample above, that is a single Message text box. Our Razor Page implementation has an endpoint and a string property.

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

public IActionResult OnPostModal()
{
    return Partial("Success", this);
}

Along with the C# code, we have a corresponding view of Success.

@model IndexModel

<strong>You Said: "@Model.Message"</strong>

Wow, that’s it.

If you’d like to see a complete working version of this solution, you can get the working HTMX Bootstrap modal sample on my GitHub Repository here.

Conclusion

Bootstrap is a popular frontend library designed to allow you to bring any client-side libraries to the party. In my case, I enjoy using HTMX to enhance an otherwise static experience. As you can see in the sample, it only takes some basic problem-solving skills to bring the two together.

I hope you found this blog post helpful, and thank you for reading.

Adding a Readme to NuGet Package Landing Pages

Tue, 04 Jul 2023 00:00:00 +0000

An essential part of working on open-source libraries is conveying the value and useability of said library—a well-written “readme” file, while not a substitute for complete documentation, can help onboard new users and increase the joy of using your code.

Regarding NuGet packages, you can now add a Readme.md asset to your NuGet packages, which NuGet.org will display on your package’s landing page, thus giving you another medium to attract new users and inform the curious developer. For example, check out my library HTMX.NET landing page, which now has the read me prominently displayed.

Let’s see what steps you must take to accomplish the same in your libraries.

The Readme File

Typically, at the root of every open-source repository should be a readme.md file. The inclusion of the file has become a convention across GitHub, GitLab, and most distributed source control offerings. Your source control’s user interface will display the readme to repository visitors, allowing them to read your perspective and introductory notes.

As an aside, a good readme should answer three essential questions:

What is this project? A statement of intent and what the ultimate goal of the repository is trying to accomplish goes a long way.
How do I get started? This includes where to get the library, possibly building the source, or acessing the library through a package manager.
What are some common use cases? While you can’t account for all scenarios, there are likely common use cases your users will encounter. Spell them out. If there are known edge cases, spell those out too.

When adding the Readme.md to your .NET repository, you’ll want to link it to each project that is packagable. Checkout out my NuGet guide here if you’re unfamiliar with setting up .NET projects for NuGet.

Updating The Package Project

The way I accomplish this is by using the Link functionality in a csproj file. Let’s take a look at what that might look like.

<ItemGroup>
    <None Remove="antiforgerySnippet.js" />
    <None Include="..\..\icon.png" Pack="true" PackagePath="">
        <Link>Properties\icon.png</Link>
    </None>
    <!-- IMPORTANT: adding the Readme as a link -->
    <None Include="..\..\README.md" Pack="true" PackagePath="">
        <Link>Properties\README.md</Link>
    </None>
</ItemGroup>

The link can point to anywhere in your project, but I place most of my linked resources inside of the Properties folder to keep the visual clutter to a minnimum. You’ll also need to have the Pack attribute set to true and the PackagePath is set to the NuGet package root. I also have a package icon in this item group, which I also recommend adding.

Next, you’ll need to add some additional elements to your project’s PropertyGroup element, with the important tags for this tutorial being PackageReadmeFile. I’ve included a complete PropertyGroup section to see how it fits in with all the other Package* elements.

The PackageReadmeFile requires the path to the Readme.md file within the NuGet package. Do not confuse this with where you place the file in your project.

<PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <OutputType>Library</OutputType>
    <Nullable>enable</Nullable>
    <LangVersion>Latest</LangVersion>
    <IsPackable>true</IsPackable>
    <PackageId>Htmx.TagHelpers</PackageId>
    <Authors>Khalid Abuhakmeh</Authors>
    <PackageIcon>icon.png</PackageIcon>
    <RepositoryUrl>https://github.com/khalidabuhakmeh/Htmx.Net</RepositoryUrl>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
    <PackageTags>web,javascript</PackageTags>
    <!-- IMPORTANT Do not forget this -->
    <PackageReadmeFile>README.md</PackageReadmeFile>
    <Description>
        Adds ASP.NET Core tag helpers to make generating urls for Htmx (https://htmx.org) easier. Mimics the ASP.NET Core url tag helpers.
    </Description>
</PropertyGroup>

If you’ve followed these steps correctly, then you should have a visible Readme on your NuGet packages home page. Congratulations! 🎉

Side Note: NuGet.org will not respective relatively-linked resources such as images. If your file uses image references, be sure to have absolute paths to the images or else you’ll have an incomplete readme on NuGet.org.

Conclusion

There you have it! With the use of a Readme file, a Link element, and PackageReadmeFile element you too can have a better looking NuGet package page. It can give you and your package a greater chance of being picked and it can help grow your little corner of the .NET community.

As always, thanks for reading and sharing my posts with friends and colleagues.

HTMX Boosts and ASP.NET Core Anti-Forgery Tokens

Tue, 27 Jun 2023 00:00:00 +0000

I maintain an ASP.NET Core enhancement library focused on integrating HTMX naturally into your web development workflow. It works great, but I must admit that HTMX is doing much of the heavy lifting regarding developer experience; it’s incredible! That said, my library (HTMX.NET) helps smooth out some of the edges that come with integrating the two parts of the experience: ASP.NET Core and the HTML UI.

In this post, I’ll discuss how to work with anti-forgery tokens and some techniques I’ve taken to help mitigate the issues you might run into when working with HTMX boosts and ASP.NET Core security measures.

What is HTMX and What’s a Boost?

HTMX is a client-side library that takes a hypermedia approach to manage user interaction between the client and the server. In simpler terms, HTMX works with HTML fragments and replaces DOM elements based on an HTML server response. While seemingly simple, this approach is robust and used by organizations like GitHub and the Ruby on Rails community.

HTMX also supports the concept of Boost. In practice, boosting requires no changes to the server-side implementation but can increase perceived user performance on the client. HTMX can intercept any anchor-based web request and then process the response, replacing the page’s existing <body> element with the response’s version. Boosting can limit client-side parsing to the elements in the <body> tag while eliminating the need for requesting and reprocessing the <head> element and all its resources, such as scripts and cascading stylesheets.

While boosting has benefits, there are drawbacks you should be aware of:

Any changes in the head are not automatically processed, except for the page’s title.
Additional scripts in the body will be reprocessed, leading to rerunning scripts (and potential re-registration of event handlers).

Following the previous best practices of placing scripts just before the <body> tag ends, these drawbacks become apparent. Also, when working with ASP.NET Core anti-forgery tokens, as currently, the HTMX.NET library adds a global token to the <head> tag to be used generally by POST requests. Finally, for your information, it’s best practice to use <form> elements, as ASP.NET Core gives forms a new anti-forgery token to use on submissions.

The goal is to update anti-forgery tokens and stop event handlers from being re-registered. So how did I accomplish that?

Scripts Within The Body Tag

Since HTMX boosts only replace the contents of the <body> tag, not the <body> tag itself, I can add additional metadata to the DOM element that survives while the page session is still active. For example, if the script executes at the end of the <body> tag, we can wrap all scripts with the following check.

if (!document.body.attributes.__htmx_antiforgery) {
    // register HTMX event handlers here
    document.body.attributes.__htmx_antiforgery = true;
}

That solves the multiple registrations of event handlers issue, and now we can handle boosts. In the latest release of HTMX (1.9.2), we have more metadata to determine if a response resulted from a boosted request. So after a response is loaded but yet to be processed, we can glean the latest anti-forgery token from the <head> element of the response.

document.addEventListener("htmx:afterOnLoad", evt => {
    if (evt.detail.boosted) {
        const parser = new DOMParser();
        const html = parser.parseFromString(evt.detail.xhr.responseText, 'text/html');
        const selector = 'meta[name=htmx-config]';
        const config = html.querySelector(selector);
        if (config) {
            const current = document.querySelector(selector);
            // only change the anti-forgery token
            const key = 'antiForgery';
            htmx.config[key] = JSON.parse(config.attributes['content'].value)[key];
            // update DOM, probably not necessary, but for sanity's sake
            current.replaceWith(config);
        }
    }
});

This JavaScript event handler will keep our anti-forgery tokens up to date on each full-page boost. Neat!

While this approach works in the <body> tag, I think there’s a better way.

Add Script to Head and Defer

The JavaScript I’ve written for HTMX.NET works excellently, but we can use the registration differently to avoid some of the abovementioned issues.

By changing how the client can access the script, we can take advantage of some newer concepts in resource management. The first step is to register an endpoint that can serve our initial script.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Routing;

namespace Htmx.TagHelpers;

public static class HtmxAntiforgeryScriptEndpoints
{
    /// <summary>
    /// The path to the anti-forgery script that is used from HTML
    /// </summary>
    public static string Path { get; private set; } = "_htmx/antiforgery.js";
    
    /// <summary>
    /// Register an endpoint that responds with the HTMX anti-forgery script.<br/>
    /// IMPORTANT: Remember to add the following script tag to your _Layout.cshtml or Razor view:
    /// <![CDATA[
    /// <script src="@HtmxAntiforgeryScriptEndpoints.Path" defer></script>
    /// ]]>
    /// </summary>
    /// <param name="builder">Endpoint builder</param>
    /// <param name="path">The path to the anti-forgery script</param>
    /// <returns>The registered endpoint (Use <seealso cref="Path"/> to reference endpoint)</returns>
    public static IEndpointConventionBuilder MapHtmxAntiforgeryScript(
        this IEndpointRouteBuilder builder,
        string? path = null)
    {
        // set Path globally for access
        Path = path ?? Path;
        
        return builder.MapGet(Path, async ctx =>
        {
            ctx.Response.ContentType = "text/javascript";
            await ctx.Response.WriteAsync(HtmxSnippets.AntiforgeryJavaScript);
        });
    }
}

Now we can register our endpoint with our ASP.NET Core application.

app.MapHtmxAntiforgeryScript();

The added benefit here is we can now add response caching and other endpoint filters to alter how this script is delivered.

Finally, with the keyword’ defer’, we can add the script to our _Layout.cshtml file in the <head> element.

<head>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <meta
        name="htmx-config"
        historyCacheSize="20"
        indicatorClass="htmx-indicator"
        includeAspNetAntiforgeryToken="true"/>
    <title>@ViewData["Title"] - Htmx.Sample</title>
    <link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.min.css"/>
    <link rel="stylesheet" href="~/css/site.css" asp-append-version="true"/>
    <script src="~/lib/jquery/dist/jquery.min.js" defer></script>
    <script src="~/lib/bootstrap/dist/js/bootstrap.bundle.min.js" defer></script>
    <script src="https://unpkg.com/htmx.org@@1.9.2" defer></script>
    <script src="@HtmxAntiforgeryScriptEndpoints.Path" defer></script>
</head>

The defer keyword will download the script parallel to parsing the page and only execute it after the client has finished parsing. The keyword keeps our scripts from blocking the critical rendering path.

While our script contains the if block, it is unnecessary now since HTMX boosts will not reload any of the <head> elements. Neat!

Conclusion

HTMX has many great features out-of-the-box, but it’s still necessary to fuse the elements of HTMX to your technology stack of choice. In my case, and likely yours, that’s ASP.NET Core. So you should expect this update in the current feature set of HTMX.NET. If you use HTMX.NET, please let me know what you think and where I can improve it.

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

Using StringBuilder To Replace Values

Tue, 20 Jun 2023 00:00:00 +0000

Have you ever had to clean up your users’ input, only to realize the pain and aggravation it can lead to with all the unnecessary memory overhead? I recently had an “aha!” moment and thought I would share this tip with you.

This article will be short, but I’ll try to give you some context as we go along. Let’s get started.

Calculators and User Input

I recently looked at a sample calculator project from MAUI developer Naweed Akram. He has some fantastic MAUI samples, and his Scientific Calculator is impressive. Check it out, seriously. He uses the NCalc library to parse string expressions and evaluate the result. It’s a very cool library but has a caveat. Functions are case-sensitive, so user input must be constrained or normalized. Naweed chose the normalization path, and his implementation is similar to the approach I would have taken myself. Let’s take a look at it.

private string NormalizeInputString()
{
    Dictionary<string, string> _opMapper = new()
    {
        {"×", "*"},
        {"÷", "/"},
        {"SIN", "Sin"},
        {"COS", "Cos"},
        {"TAN", "Tan"},
        {"ASIN", "Asin"},
        {"ACOS", "Acos"},
        {"ATAN", "Atan"},
        {"LOG", "Log"},
        {"EXP", "Exp"},
        {"LOG10", "Log10"},
        {"POW", "Pow"},
        {"SQRT", "Sqrt"},
        {"ABS", "Abs"},
    };
    
    var retString = InputText;
    foreach (var key in _opMapper.Keys)
    {
        retString = retString.Replace(key, _opMapper[key]);
    }

    return retString;
}

The method uses a Dictionary of keys and values to force specific casing to match what NCalc expects from the user. While functional, there is room to optimize performance.

In the previous code, the method call to Replace creates a new string in memory for each replacement. So, in a worst-case scenario, we could have 15 new strings allocated as we clean the user’s equation, one for each key and the original value. Yikes!

What should we do?!

Using StringBuilder To Replace

We commonly think of StringBuilder as a class to build up new string values, but it didn’t occur to me that StringBuilder could also be used to alter an existing string efficiently. So, let’s update the code sample.

private string NormalizeInputString()
{
    Dictionary<string, string> _opMapper = new()
    {
        {"×", "*"},
        {"÷", "/"},
        {"SIN", "Sin"},
        {"COS", "Cos"},
        {"TAN", "Tan"},
        {"ASIN", "Asin"},
        {"ACOS", "Acos"},
        {"ATAN", "Atan"},
        {"LOG", "Log"},
        {"EXP", "Exp"},
        {"LOG10", "Log10"},
        {"POW", "Pow"},
        {"SQRT", "Sqrt"},
        {"ABS", "Abs"},
    };
    
    var retString = new StringBuilder(InputText);
    foreach (var key in _opMapper.Keys)
    {
        retString.Replace(key, _opMapper[key]);
    }

    return retString.ToString();
}

Now we only generate two strings: the original input and the final result. You might be asking, “how much of a difference can this make, really?”. Well, every optimization is contextual and will depend on your use case. But, we can reduce some unnecessary memory pressure for a relatively simple change.

Let’s use Benchmarkdotnet to compare the previous implementation and the StringBuilder approach.

using System.Text;
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;

BenchmarkRunner.Run<StringReplace>();

[MemoryDiagnoser]
[ShortRunJob]
public class StringReplace
{
    readonly Dictionary<string, string> map = new()
    {
        { "×", "*" },
        { "÷", "/" },
        { "SIN", "Sin" },
        { "COS", "Cos" },
        { "TAN", "Tan" },
        { "ASIN", "Asin" },
        { "ACOS", "Acos" },
        { "ATAN", "Atan" },
        { "LOG", "Log" },
        { "EXP", "Exp" },
        { "LOG10", "Log10" },
        { "POW", "Pow" },
        { "SQRT", "Sqrt" },
        { "ABS", "Abs" },
    };

    private const string target = "1 x 1 ÷ 1 * SIN(COS(TAN(LOG(ASIN(ATAN(EXP(POW(SQRT(ABS(1))))))))))  |" +
                                  "1 x 1 ÷ 1 * SIN(COS(TAN(LOG(ASIN(ATAN(EXP(POW(SQRT(ABS(1))))))))))  |" +
                                  "1 x 1 ÷ 1 * SIN(COS(TAN(LOG(ASIN(ATAN(EXP(POW(SQRT(ABS(1))))))))))  |" +
                                  "1 x 1 ÷ 1 * SIN(COS(TAN(LOG(ASIN(ATAN(EXP(POW(SQRT(ABS(1))))))))))  |" +
                                  "1 x 1 ÷ 1 * SIN(COS(TAN(LOG(ASIN(ATAN(EXP(POW(SQRT(ABS(1))))))))))  |" +
                                  "1 x 1 ÷ 1 * SIN(COS(TAN(LOG(ASIN(ATAN(EXP(POW(SQRT(ABS(1))))))))))  |" +
                                  "1 x 1 ÷ 1 * SIN(COS(TAN(LOG(ASIN(ATAN(EXP(POW(SQRT(ABS(1))))))))))  |" +
                                  "1 x 1 ÷ 1 * SIN(COS(TAN(LOG(ASIN(ATAN(EXP(POW(SQRT(ABS(1))))))))))  |" +
                                  "1 x 1 ÷ 1 * SIN(COS(TAN(LOG(ASIN(ATAN(EXP(POW(SQRT(ABS(1))))))))))  |";

    [Benchmark]
    public string String()
    {
        var result = target;
        foreach (var key in map.Keys)
        {
            result = result.Replace(key, map[key]);
        }

        return result;
    }

    [Benchmark]
    public string StringBuilder()
    {
        var result = new StringBuilder(target);
        foreach (var key in map.Keys)
        {
            result.Replace(key, map[key]);
        }

        return result.ToString();
    }
}

Let’s see the results of the Benchmarkdotnet run.

|        Method |     Mean |    Error |    StdDev |   Gen0 | Allocated |
|-------------- |---------:|---------:|----------:|-------:|----------:|
|        String | 3.967 us | 1.673 us | 0.0917 us | 1.8082 |  11.11 KB |
| StringBuilder | 3.480 us | 2.472 us | 0.1355 us | 0.4082 |   2.52 KB |

Wow! The StringBuilder implementation allocates about 20% of what the String implementation does. That’s a pretty significant performance optimization for code that looks almost identical. These increases can become more effective as the target string grows or the dictionary of keys/values expands.

Conclusion

While you may think of StringBuilder as a means to build strings over several iterations, you can also think of StringBuilder as an alteration tool. Utilizing the Replace method could reduce memory overhead while keeping the code almost the same. Given the benchmark comparison, you can also see reduced Gen0 sizes, which should minimize garbage collection pauses over time. It’s a win-win.

I hope you enjoyed this blog post, and please feel free to share it with colleagues and friends. As always, thanks for reading.

The Privilege of .NET Tooling Choices

Tue, 13 Jun 2023 00:00:00 +0000

Regarding the .NET ecosystem, we’ve become spoiled with great tooling choices from Visual Studio, JetBrains Rider, VS Code, and NeoVIM, not to mention the extension ecosystem like ReSharper, CodeRush, and OzCode. As a result, the ability to define your development workflow and your team’s workflow has never been more varied. What a time to be a .NET developer!

With choice comes the burden of improving your productivity while not hampering the preferences of your team members. After all, all of us have years of different experiences and skill sets that no single tool can satisfy. A development tool that tries to please everyone is doomed to please no one.

So I wanted to use this time to describe my philosophy when picking development tools and why I think it’s vital for personal and team happiness and completing development projects.

Let’s get started.

Picking Personal Tools

When it comes to defining my development environment, I believe it is a deeply personal choice. I prefer the operating system I like (macOS) and IDE I work with (JetBrains Rider). Over 15 years, I’ve found the combination of tooling that works for me, but I’m also willing to consider other options as the technology landscape changes. I also understand my personal choices will not be another individual’s. So instead of arguing about personal preferences, finding ways to be a better development neighbor is more important.

In the pursuit of being a good development partner, I have a “must follow” rule:

My tooling choices should not burden other developers with my preferences.

Therefore, if I choose a tool, it must abide by at least one of two criteria:

The tool is transparent to other team members. It doesn’t pollute the shared spaces with my preference and put my team members at the disadvantage of dealing with my “junk”.
If my tool produces artifacts, other team members must be able to utilize those artifacts regardless of all of our preferences. (we’ll talk more about this later).

What does “polluting” constitute? If a codebase is a communal shared space by team members, my tools shouldn’t leave artifacts that team members didn’t agree to use. These artifacts include tool-specific configuration files, assets, or dependencies. These artifacts are one more burden a team must manage, which would constitute selfish behavior on my part.

In my attempt to stay on the good side of karma, a tool needs to provide at least two options:

Assets are optional; tooling can work with or without the extra configuration.
Assets can exist locally in my development environment without me checking the files in source control.

These characteristics allow me to make my choice and still be a good team member. Everyone wins.

Picking Team Tools

Given the promise of .NET being a cross-platform technology stack, the shared tools a team picks should reflect that value. So, for example, tools might include test runners, HTTP clients, static analysis tooling, and build pipeline enhancements. This brings me to my subsequent “must follow” rule:

Any tool a team adopts must account for running locally on any developer’s preferred environment and provide value to all team members.

So what do I look for in team tooling choices?

A tool must provide value to a majority of team members. Therefore, a consensus on what constitutes value is essential to adopting tools. Adding dependencies is a burden, after all.
A team tool must be cross-platform. A Windows or Unix-only tool doesn’t benefit everyone and should be crossed off the list immediately. It’s time we expect better from our team tools.
Any tool that processes files should provide a CLI version of itself. A CLI tool allows team members to get value from shared assets even if they might not have a comparable experience an IDE plugin might provide. A CLI tool also means you can get similar results in CI/CD pipelines and locally. At the very least, the tool should be accessible to everyone via a web interface if it is a subscription service-style tool.

In a team setting, a team tool should not penalize my macOS choice, favoring a team member’s Windows experience, and vice versa. Likewise, a team member’s use of a Visual Studio extension should not hamper my JetBrains Rider experience. And ultimately, a tool that I can run in a CI/CD environment must also run locally. Adopting a tool that favors one group over another creates unnecessary friction and fragmentation. That friction leads to resentment and conflict, lowering team productivity.

Team-focused tools should also be accessible to all team members in the same capacity, as everyone should be able to manage and maintain them. After all, the team agreed on the value of adopting the tool, right? With the complexity of the modern software development lifecycle, teams should limit their risk exposure. A team tool that only works in specific circumstances and is only accessible to certain team members is a liability.

Conclusion

As .NET developers, we have a glut of choices in front of us, and while we each have our particular favorites, we also need to understand the team-based nature of software development. When we take those choices away from team members, we create an environment devoid of diversity and creativity, which I try to avoid as much as possible. The .NET ecosystem and the folks working in it should champion team productivity and create a base experience everyone can rely on, regardless of anyone’s personal tooling choices. I hope you leave being mindful of how individual choices can affect a team’s productivity and, ultimately, the vibrancy of the .NET ecosystem.

Entity Framework Core 7: Filtering on JSON Arrays

Tue, 06 Jun 2023 00:00:00 +0000

Entity Framework Core 7 introduced developers to JSON column support. I even wrote about it on the JetBrains .NET blog, and it has been generally well-received. However, recently a user tried my sample project, only to find that they could not filter on a collection of JSON values. Given the current Microsoft SQL Server provider, the following LINQ statement does not work.

var results = await db.Posts
    .Where(x => x.Tags.Any(t => t.Value == "CSharp"))
    .ToListAsync();

Entity Framework Core will throw the following exception.

The LINQ expression 'DbSet<Post>()
    .Where(p => EF.Property<List<Tag>>(p, "Tags")
        .AsQueryable()
        .Any(o => o.Value == "CSharp"))' 
could not be translated.
Either rewrite the query in a form that can be translated, 
or switch to client evaluation explicitly by inserting a 
call to 'AsEnumerable', 'AsAsyncEnumerable', 'ToList', 
or 'ToListAsync'. See https://go.microsoft.com/fwlink/?linkid=2101038 
for more information.

If you’re experiencing this issue and need to filter on a JSON array, I have several SQL queries to help you work around this issue. Let’s get started.

SQL to the Rescue

Luckily, in later versions of Entity Framework, we have access to the FromSql methods that can allow us to seed the From clause with a sub-query. The advantage of this approach is we can still use many of the features of LINQ from a starting result set. But before we get to the C# code, let’s look at some queries against our data model.

var blogPost = new Post
{
    Title = "Writing about .NET",
    Author =
    {
        Name = "Khalid Abuhakmeh",
        ImageUrl = "/khalidabuhakmeh.jpg",
        SocialMediaUrl = "@khalidabuhakmeh@mastodon.social"
    },
    Tags =
    {
        new Tag { Value = "dotnet" },
        new Tag { Value = "drop" }, 
        new Tag { Value = "dot" }
    }
};

Tags are stored as a JSON Column in the following form.

[{"Value":"dotnet"},{"Value":"drop"},{"Value":"dot"}]

So how do you filter a row based on whether a tag exists in your collection of tag values? Well, there are a few ways. I’ve included them below with the Total Cost according to running them on a dataset of 500 rows. Of course, a lower value is better, but check it against your dataset and consult your local DBA.

-- Total Cost: 0.00527086
SELECT *
FROM Posts p
CROSS APPLY OPENJSON(p.Tags)
WITH (Tag VARCHAR(300) '$.Value') as Tag
Where Tag = 'dotnet'

-- Total Cost: 0.0651177
SELECT *
From Posts posts
WHERE (SELECT Tag as tag
       FROM OPENJSON(Tags) WITH (Tag VARCHAR(300) '$.Value') AS Tag
       WHERE Tag = 'dotnet') = 'dotnet'

-- Total Cost: 0.0304298
SELECT *
From Posts posts
WHERE EXISTS 
  (SELECT Tag as tag
   FROM OPENJSON(Tags) WITH (Tag VARCHAR(300) '$.Value') AS Tag
   WHERE Tag = 'dotnet')

-- Total Cost: 0.0297937
SELECT *
From Posts posts
WHERE EXISTS 
 (SELECT Value
  FROM OPENJSON(Tags) WITH (Value VARCHAR(300) '$.Value') AS Value
  WHERE Value in ('dotnet', 'drop'))

I’ve included variants that support multiple tag filtering or several values. Use the one for your use case.

Now that we have a SQL query, how do we use it in Entity Framework Core?

Well, I had mentioned the use of FromSql, and we can do just that.

var values = new object[] { "drop", "dot" };
var placeholders = string.Join(",", values.Select((_, i) => $"{{{i}}}").ToArray());

var list = await db.Posts.FromSqlRaw(
        $"SELECT * From Posts posts WHERE EXISTS (SELECT Value FROM OPENJSON(Tags) WITH (Value VARCHAR(300) '$.Value') AS Value WHERE Value in ({placeholders}))", values)
    .ToListAsync();

I decided to use the Exists versions of my SQL queries, as they are the most straightforward to reason about, and it supports multiple tags. I also needed to parameterize the user input, which should keep the query safe against SQL injection attacks.

You can add additional filters to the base query, like the following.

var list = await db.Posts.FromSqlRaw("<SQL>")
    .Where(p => p.Id == 2)
    .ToListAsync();

The generated SQL query will appear in the console’s output.

info: 5/8/2023 14:21:20.802 RelationalEventId.CommandExecuted[20101] (Microsoft.EntityFrameworkCore.Database.Command) 
      Executed DbCommand (91ms) [Parameters=[p0='drop' (Size = 4000), p1='dot' (Size = 4000)], CommandType='Text', CommandTimeout='30']
      SELECT [c].[Id], [c].[CreateAt], [c].[Permalink], [c].[Title], [c].[UpdatedAt], JSON_QUERY([c].[Author],'$'), JSON_QUERY([c].[Tags],'$')
      FROM (
          SELECT * From Posts posts WHERE EXISTS (SELECT Value FROM OPENJSON(Tags) WITH (Value VARCHAR(300) '$.Value') AS Value WHERE Value in (@p0,@p1))
      ) AS [c]
      WHERE [c].[Id] = 1

Awesome! Well, I have one more option for you, but I do think it’s the inferior option. That said, for the sake of completeness, here it is.

Using Likes To Filter Rows

The solution presented above will use the JSON features of Microsoft SQL Server to accurately filter rows based on the values in a JSON object. If you’re dealing with simpler data, as I am in this post, a LIKE query might be good enough.

var value = "%\"dotnet\"%";
var one = await db.Posts
     .FromSqlRaw("SELECT * FROM Posts WHERE Tags LIKE {0}", value)
     .FirstOrDefaultAsync();

This approach certainly works, but has the disadvantage of using double-sided wildcards, which is known for being less-than optimal when it comes to performance. You also have to deal with creating the filter value with the use of % and " characters.

It’s an option if you need it, but I really do recommend the previous approach.

Conclusion

While Entity Framework Core introduced JSON support, as I wrote about in my JetBrains blog post, it sadly is missing collection filtering. However, using the FromSql variant methods, you can get it working while retaining the strengths of LINQ and query filtering. In addition, you can take the extra step to add much of the functionality mentioned here into an extension method. The one drawback to using FromSql is that it becomes the foundation for all future filtering, which may make it challenging to optimize your LINQ queries without adding more to the original SQL statement. In conclusion, I’m pretty happy with this approach, but looking forward to the day that Entity Framework Core supports this functionality out of the box.

I hope you enjoyed this post, and thank you for reading and sharing my content with others.

JavaScript Import Maps For ASP.NET Core Developers

Tue, 30 May 2023 00:00:00 +0000

If you’re building web applications, you’ll likely have to write some JavaScript, so why not write the best JavaScript you can? The JavaScript ecosystem has evolved with an emphasis on performance and user experience, and if you’ve avoided writing JavaScript for a while now, you’ll be pleasantly surprised.

Import Maps is the latest advancement, a technique to make managing and consuming EcmaScript modules (ESM) much more straightforward for client-side developers. Ultimately, it brings the same style of development Node developers have enjoyed on the server side of the ecosystem to the browser.

In this post, we’ll compare traditional script referencing to ESM, how to write a simple ESM file, how to use it in your Razor-powered ASP.NET Core applications, and some good-to-know facts.

What is ESM and Why Should I Care?

JavaScript implementations have transitioned from unstructured code living in a global context to codebases depending on easy-to-follow structures. Let’s look at a simple module and how you can consume it.

// file name: simple.js
export default function () {
    console.log('hello world!');
}

Now, let’s use our module that exports a function.

import Simple from "./simple.js";
Simple();

You can see that authoring and consuming a module has intention behind it. You can tell where a module is coming from and what parts of the module you use. There’s no surprise global variables or opportunities for unresolvable conflicts. So why is this better?

If you’ve spent any time doing web development, you’re likely familiar with JQuery and how it’s referenced and used in a web application. The breakdown is not to pick on JQuery but to demonstrate some issues with traditionally-written libraries.

The foremost trait of a traditional script is that you reference it on a web page like so.

<script src="/libs/jquery/3.6.4/jquery.min.js"></script>

While perfectly fine, there are a few drawbacks to referencing scripts this way.

Scripts are blocking and will stop the page from processing until all content is loaded.
Script variables and functions are global and may conflict with other scripts.
Selectively loading dependencies requires server-side templating to toggle elements or client-side code that dynamically injects script tags.

In our ESM example, you can reference scripts using the type of module in your Razor pages.

<script src="~/js/site.js" type="module" asp-append-version="true"></script>

The presence of type=module tells the browser to load the file with the knowledge that it is using ESM and to respect import statements. Only dependencies that are part of the import graph will be loaded, and additionally, all modules are deferred by default, meaning they won’t block the page rendering.

So how do import maps factor into all of this?

Import Maps and Why They’re Important

Import maps allow you to define aliases for internal and external dependencies used in your JavaScript. For example, look at the import map from my sample ASP.NET Core Razor Pages project.

<script type="importmap">
{
    "imports" : {
        "vue": "https://unpkg.com/vue@3/dist/vue.esm-browser.js",
        "hello-world": "@Url.Content("~/js/hello-world.js")",
        "simple": "@Url.Content("~/js/simple.js")"
    }
}
</script>

Once you’ve defined an import map, you can use the aliases anywhere in your client-side environment. For example, here is the implementation for hello-world.js.

import { createApp } from "vue";

export default function helloWorld(target, message) {
    createApp({
        data() {
            return {
                message: message
            }
        }
    }).mount(target)
}

You can see that I’m importing the vue dependency, which points to an ESM version of the Vue library. It’s important that any library imported also be written in the ESM style. All without immediately knowing what vue is used during my usage. The flexibility allows for more centralized dependencies updates without affecting large swaths of my codebase.

We can also import a module within our HTML pages using a’ script’ tag element.

<div id="app"></div>

<script type="module">
import helloWorld from 'hello-world';
helloWorld('#app', 'Hello From ASP.NET Core');
</script>

Awesome right?!

Now our ASP.NET Core pages can selectively use dependencies from our JavaScript modules, with the added benefit of only loading the libraries we need. What a fantastic feature.

You might be thinking, how can ASP.NET Core do more in this situation? How about importing JSON files into your clientside apps? That would be cool, right? Well, you can!

Let’s first define a JSON endpoint using Minimal APIs.

app.MapGet("/config", 
    () => new { name = "Khalid" });

Next, we’ll modify our import map to point to this new endpoint.

<script type="importmap">
{
    "imports" : {
        "vue": "https://unpkg.com/vue@3/dist/vue.esm-browser.js",
        "hello-world": "@Url.Content("~/js/hello-world.js")",
        "simple": "@Url.Content("~/js/simple.js")",
        "config": "@Url.Content("~/config")"
    }
}
</script>

Finally, we can import and use our JSON response in our client-side script. You must assert that the module import is of type json for it to work correctly.

<script type="module">
import config from 'config' assert { type: 'json' };
import helloWorld from 'hello-world';
helloWorld('#app', `Hello ${config.name} From ASP.NET Core`);
</script>

Note that there might still be compatibility issues with assert statements across browser vendors. Please consult the Mozilla documentation to see if your browser supports particular features with modules.

General Thoughts on Import Maps

I have some thoughts I’d love to share with you about some advantages of this approach.

Modules and import statements are very natural for C# developers, so the move to this style of development should be easier for most folks.
The deferment of these scripts by default means you get an added performance boost to your user experience. Who doesn’t want that?!
The combination of JavaScript code using ASP.NET Core server-rendered content is powerful.
Import maps make it easy to manage dependencies, regardless if you’re using a build tool or want to use prebuilt dependencies. It’s great!
All your dependencies must be ESM compatible, so trying to import commonJS files will not work.
Don’t forget to add type=module to your script tags. It’s easy to forget and can leave you scratching your head.

Conclusion

All major browsers now support import maps, and ESM is the future of writing JavaScript. It’s also a great way to update your existing clientside development workflow without taking on large build toolchains. You’ll need to seek out ESM-compatible libraries, but many of the most popular ones have already started the shift. In combination with ASP.NET Core, you can use the dynamic server-side generation tools to interact and enhance your client-side experience. It’s a win-win for everyone.

I hope you enjoyed this post, and as always, thanks for reading and sharing my content.

XUnit Tests, JetBrains Rider, and Counting Until Failure

Tue, 23 May 2023 00:00:00 +0000

JetBrains Rider is a fantastic tool, and full disclosure, as of writing this post, I am a developer advocate for JetBrains. XUnit is also an excellent unit testing framework, and their combined powers create an out-of-this-world testing experience.

One feature JetBrains Rider users have fallen in love with is Run Selected Tests Until Failure, which is what it sounds like. JetBrains Rider will continue executing your unit test until the test fails. The test runner feature can help diagnose finicky unit tests that work intermittently. Nothing is worse than an inconsistent bug, am I right?!

When performing an investigation, you want as much information as possible. For example, a common question might be, “How many times did my test run before failing?”.

In this post, we’ll build an XUnit fixture you can use in your tests to determine the number of iterations before a failure. Let’s get started.

XUnit Unit Tests and Fixtures

XUnit is a unit testing library that provides a framework for building a test suite. It’s a popular tool for many developers and is supported by all .NET IDE vendors. A technique to share functionality across unit tests is building a fixture. A fixture is a shared context between tests. This feature can help reduce the cost of expensive dependencies such as databases, Docker containers, and more.

I prefer fixtures, but admittedly this approach could forgo fixtures in favor of a static class and static methods. If you like that approach, please modify the code accordingly.

I’ll be using SQLite to store the count for each test execution. You’ll need to install the NuGet package of Microsoft.Data.Sqlite. Let’s take a look at the fixture.

using System.Runtime.CompilerServices;
using Microsoft.Data.Sqlite;

namespace FailCounter;

public class TestRunsCounter
{
    private const string ConnectionString = "Data Source=tests.db";

    public TestRunsCounter()
    {
        using var connection = new SqliteConnection(ConnectionString);
        connection.Open();
        using var command = connection.CreateCommand();
        command.CommandText =
            """
            CREATE TABLE IF NOT EXISTS Counts
            (
                Name  TEXT not null
                    constraint Name primary key,
                Count integer
            );
            """;
        command.ExecuteNonQuery();
    }

    public long Increment([CallerMemberName] string? testName = null)
    {
        if (testName is null)
            return 0;

        using var connection = new SqliteConnection(ConnectionString);
        connection.Open();
        var command = connection.CreateCommand();
        command.CommandText =
            """
            INSERT Into Counts (Name, Count) Values($name, 1)      
            On CONFLICT(Name) Do Update Set
                Count = Count + 1
                Where Name = $name;
            Select Count from Counts Where Name = $name;
            """;
        command.Parameters.AddWithValue("$name", testName);
        var count = (long)command.ExecuteScalar()!;

        return count;
    }

    public void Reset([CallerMemberName] string? testName = null)
    {
        if (testName is null)
            return;

        using var connection = new SqliteConnection(ConnectionString);
        connection.Open();
        var command = connection.CreateCommand();
        command.CommandText =
            """
            INSERT Into Counts (Name, Count) Values($name, 0)      
            On CONFLICT(Name) Do Update Set
                Count = 0
                Where Name = $name;
            """;
        command.Parameters.AddWithValue("$name", testName);
        command.ExecuteNonQuery();
    }
}

The calls to Increment will either increment an existing row’s count or insert a new row with a count of 1. I also included a Reset method for resetting counters during investigations. The Reset method must be called manually by you.

Using The Test Runs Counter Fixture

Utilizing the TestRunsCounter fixture is as straightforward as implementing the IClassFixture interface. Let’s look at an example of using the counter.

using Xunit.Abstractions;

namespace FailCounter;

public class UnitTest1 : IClassFixture<TestRunsCounter>
{
    private readonly TestRunsCounter _fixture;
    private readonly ITestOutputHelper _output;

    public UnitTest1(TestRunsCounter fixture, ITestOutputHelper output)
    {
        _fixture = fixture;
        _output = output;
    }

    [Fact]
    public void Test1()
    {
        var count = _fixture.Increment();
        _output.WriteLine($"Current count is \"{count}\".");

        if (count > 10)
        {
            throw new Exception();
        }

        Assert.True(count < 10);
    }

    [Theory]
    [InlineData(nameof(Test1))]
    public void Reset(string testName)
        => _fixture.Reset(testName);
}

Now we can let JetBrains Rider run our test until failure. We can also use the unit test of Reset to reset our failing test. Great!

Conclusion

Intermittently failing tests are frustrating, but with JetBrains Riders “Run Selected Tests Until Failure”, you can diagnose those pesky situations. By using SQLite, we can track the iterations it took to fail. You can also use this as a starting to serialize other stateful information from a unit test and store them in SQLite.

I hope you enjoyed this post, and let me know how you end up using this code in your code bases. As always, thank you.

Override Razor Pages Routes From Razor Class Libraries

Tue, 16 May 2023 00:00:00 +0000

Sharing is caring, and what’s more affectionate than sharing Razor Pages functionality with the .NET community? Well, a lot of other things, but sharing Razor Pages can help you deliver functionality to the other developers that would otherwise be difficult to integrate into existing applications.

Some examples of practical Razor Page implementations might include a route debugger, an administrative panel, a terminal emulator, and a documentation renderer. All of these could be something you take on and ship to users to help accelerate their development and help them focus more on their problem domain.

To accomplish this goal, you may use the Razor Class Library, which allows you to bundle Razor Pages, Razor Components, and other static assets. That said, there are bound to be conflicts with routes and users’ aesthetic senses of what routes should look like.

In this post, we’ll see how you can override Razor Pages routes delivered from a Razor Class Library.

What Is A Razor Class Library?

Razor Class Libraries (RCL) allow developers to share Razor components, C# code, and static assets to projects referencing the library. The approach is helpful for situations where you have standard functionality worth sharing in other projects but not necessarily repeating. Projects that can use an RCL include ASP.NET Core MVC, Blazor Server app, and Blazor WASM. You can distribute RCLs in multiple ways, but the most effective approach is through a NuGet package.

You can create an RCL project using the .NET template razorclasslib or the “New Project” facilities of your favorite .NET IDE.

Creating A Razor Class Library For Razor Pages

To create an RCL, begin a new project within your solution using the .NET SDK-provided template. You’ll need two additional elements in your .csproj file to support Razor Pages.

First, let’s add the AddRazorSupportForMvc element. In the csrpoj file, you should add the following element to your project file’s first PropertyGroup tag. This addition allows the RCL to support Razor Pages and the structure required to embed the files in the project.

<AddRazorSupportForMvc>true</AddRazorSupportForMvc>

The following essential element is a FrameworkReference in the same project file. The reference imports the ASP.NET Core primitives required by Razor pages.

<FrameworkReference Include="Microsoft.AspNetCore.App" />

Without this additional reference, you won’t be able to use classes like PageModel.

Adding A Razor Page

In the RCL project, we will use Areas to isolate our Razor Pages from a consuming project’s pages. The approach keeps conflicts at a minimum. We’ll add a custom “Privacy” Razor Page in an “Extra” area. The directory structure will look like.

|- wwwroot
|- Areas
   |- Extra
      |- Pages    
         |- Privacy.cshtml 
         |- Privacy.cshtml.cs

The contents of the Razor Page are not very important in this case. I reworked the namespaces and copied the default Privacy page from an existing Razor Pages project.

Here’s the important part! Don’t skip this.

When defining your Razor Pages, do not set the route in your pages. Instead, each page should only have the @page attribute.

// correct
@page
// incorrect
@page "/privacy"

This decision will be necessary for letting users override their applications’ routes.

In a referencing project, you should now be able to navigate to the page using /Extra/Privacy, but what if you don’t do that? Well, let’s look at the crux of this post, overriding the route.

Overriding RCL Razor Pages Routes

ASP.NET Core registers Razor Pages by their “page name”. The page name is typically a version of the physical path combined with an area, if applicable.

In our case, the route to our RCL Razor Page has a page name of /Privacy and an area name of Extra. We can use this information by adding a new convention to our Razor Pages options. The code is straightforward; you can add the following code in your Program.cs or Startup class.

builder.Services.Configure<RazorPagesOptions>(opt =>
{
    // Override an imported Razor Class Library
    // Razor Pages Route
    opt.Conventions.AddAreaPageRoute(
        areaName: "Extra",
        pageName: "/Privacy",
        route: "/Privacy");
});

Instead of navigating to /Extra/Privacy, you can get to the RCL Razor page using /Privacy. Hooray!

It’s imperative that the author of the RCL did not set the @page route, or else you will run into issues.

Now, you can generate routes using the link generation found in ASP.NET Core using the original page name and area name from the RCL library.

<a asp-area="Extra" asp-page="/Privacy">Privacy</a>

And the resulting link will be the override route set in your RazorPagesOptions instance. Great!

An additional step you could take in your RCL implementation is providing an extension method on IServiceCollection that sets the route in a more user-friendly manner.

using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.Extensions.DependencyInjection;

namespace RazorPagesExtra.Extra;

public static class RoutesExtensions
{
    public static IServiceCollection SetPrivacyUrl(this IServiceCollection services, string route)
    {
        services.Configure<RazorPagesOptions>(opt =>
        {
            // Override an imported Razor Class Library
            // Razor Pages Route
            opt.Conventions.AddAreaPageRoute(
                areaName: "Extra",
                pageName: "/Privacy",
                route: route);
        });
        
        return services;
    }
}

With a call in the referencing app, looking like the following:

builder.Services.SetPrivacyUrl("/Privacy");

And this could be expanded to a configuration object instead. So you have unlimited options for how you’d like to approach this from here on out.

Note: If you’re noticing your RCL page has no layout, you can always add a new Areas folder in your referencing project with a _ViewStart.cshtml file.

@{
   /*
    *  |- wwwroot
    *  |- Areas
    *     |- _ViewStart.cshtml 
    */
   Layout = "_Layout";
}

This additional file will set the Layout for all RCL libraries and let you use your project’s layout file.

Conclusion

Delivering value to other developers using RCLs is an excellent feature of ASP.NET Core, but sometimes users want control over their routes. Using Razor Pages conventions and excluding a default route, you can give your users the ability to override any route you provide via an RCL.

I hope you found this post helpful, and as always, thank you for reading and sharing my work.

If you’d like to see a complete sample of this repository, you can see it on my GitHub repository.

Manage Vite Assets Like A Pro

Tue, 09 May 2023 00:00:00 +0000

I’ve recently been doing a lot of work with TypeScript and Vite, and one of the issues I’ve run into is my vite.config.ts file can become a mess almost too quickly. Unfortunately, Vite’s strength of configurability is also its most significant barrier: so many options exist!

In this post, we’ll see how you can set up your Vite asset management to predictably place assets where you want them while taking advantage of Vite’s build pipeline to hash and chunk files. I’ll also introduce you to a Vite plugin that I think should be part of Vite out of the box.

Let’s get started!

A Vite Project and Goals

When starting a Vite-powered project, you’ll likely pick your frontend framework, possibly set up TypeScript, install external dependencies, and add assets like images, videos, and other static files. However, it’s important to note that Vite operates in what I refer to as a split-mind approach. As a result, what happens in development mode differs from what you expect during the build process. Your development folder can have one organizational strategy, while your distribution folder takes an entirely different direction.

Understanding and configuring where your final build artifacts end up is an optional feature of Vite, but taking the time to think through the process can set you up for success when deploying your app.

For example, having images in a dedicated folder means you can more easily manage your static assets in a hosting environment. Additionally, some files, like RSS feeds, might not benefit from the hash and be counterproductive. Finally, having folders allows for CDN and syncing strategies at a higher level than a single folder or file.

So, how do you manage your Vite assets? Let me show you.

Vite Assets Configuration

Vite options have a lot of methods and values you can override to create the particular behavior you seek. In short, you need to override the following Vite option values:

build.rollupOptions.output.entryFileNames
build.rollupOptions.output.assetFileNames
build.rollupOptions.output.chunkFileNames

While you could certainly set these values inline, you’ll find your vite.config.ts file quickly becomes unruly. So what I did was create a file at config/assets.ts. Let’s take a look at it.

import {PreRenderedAsset} from "rollup";

type AssetOutputEntry = {
    output: string,
    regex: RegExp
}

export const assetDir = "assets";
export const entryFileNames = `${assetDir}/js/[name]-[hash].js`;
export const chunkFileNames = `${assetDir}/js/[name]-[hash]-chunk.js`
const assets: AssetOutputEntry[] = [
    {
        output: `${assetDir}/img/[name]-[hash][extname]`,
        regex: /\.(png|jpe?g|gif|svg|webp|avif)$/
    },
    {
        regex: /\.css$/,
        output: `${assetDir}/css/[name]-[hash][extname]`
    },
    {
        output: `${assetDir}/js/[name]-[hash][extname]`,
        regex: /\.js$/
    },
    {
        output: `[name][extname]`,
        regex: /\.xml$/
    }
];

export function processAssetFileNames(info: PreRenderedAsset): string {
    if (info && info.name) {
        const name = info.name as string;
        const result = assets.find(a => a.regex.test(name));
        if (result) {
            return result.output;
        }
    }
    // default since we don't have an entry
    return `${assetDir}/[name]-[hash][extname]`
}

The file allows anyone to manage assets by setting a new AssetOutputEntry item with a corresponding output and regex value. As Vite finds new assets to process, the method processAssetFileNames will be passed the information, at which point you can route the file to its final destination. Let’s see how you use this new file in your vite.config.ts file.

import {defineConfig} from "vite";
import {processAssetFileNames, entryFileNames, chunkFileNames, assetDir} from "./config/assets";
import {resolve} from "path";
import viteHtmlResolveAlias from 'vite-plugin-html-resolve-alias'

export default defineConfig({

    resolve: {
        alias: {
            '@img': resolve(__dirname, 'src/img/'),
            '@rss': resolve(__dirname, 'src/rss.xml')
        }
    },

    plugins: [
      viteHtmlResolveAlias()
    ],

    build: {
        minify: true,
        assetsDir: assetDir,
        // don't inline anything for demo
        assetsInlineLimit: 0,
        emptyOutDir: true,
        rollupOptions: {
            output: {
                entryFileNames: entryFileNames,
                assetFileNames: processAssetFileNames,
                chunkFileNames: chunkFileNames
            }
        }
    }
});

Now you can manage all your assets from your assets.ts file using regular expressions. Neat!

Now let’s look at how we can use the assets in our HTML files.

HTML Resolve Alias Vite Assets

You will want to use some assets in HTML and JavaScript files. For example, I’m using an image of vite.svg in the main.ts file and index.html in this sample.

Note: The following package says it’s incompatible with the latest Vite version, but it’s not. So you may need to perform an npm install --force to get the package installed.

Using the package vite-plugin-html-resolve-alias, I can create resolution aliases that the plugin will process in my HTML files. But first, let’s see what setting up aliases looks like. You may have noticed the resolve section in my previous configuration file.

resolve: {
    alias: {
        '@img': resolve(__dirname, 'src/img/'),
        '@rss': resolve(__dirname, 'src/rss.xml')
    }
},

These are aliases to files found in my src directory that I want to run through the Vite asset pipeline and use in TypeScript and HTML. To use these files in HTML, we can use our new aliases.

<link rel="icon" type="image/svg+xml" href="@img/vite.svg"/>
<link rel="alternate" type="application/rss+xml" title="RSS Feed" href="@rss"/>

When we call to build, these assets are processed similarly to any other asset imported in our TypeScript. Neat! Here’s a snippet from the final build output.

<link rel="icon" type="image/svg+xml" href="/assets/img/vite-4a748afd.svg">
<link rel="alternate" type="application/rss+xml" title="RSS Feed" href="/rss.xml">

Depending on the use case, I’m no longer hampered by duplicate assets in public or src. I can use the same asset in both static HTML and dynamic JavaScript. That’s a win-win!

Conclusion

Vite’s asset pipeline is robust, especially for folks building web applications. With some care and thought, you can decide how assets are processed and where they end up in the final distribution folder.

If you’d like to see a working sample of this blog post, I’ve uploaded it to my GitHub repository, where you can see the build in action.

I hope you found this post helpful, and let me know what you think. As always, thanks for reading and sharing my posts. Cheers.

Running Vite with ASP.NET Core Web Applications

Tue, 02 May 2023 00:00:00 +0000

The web ecosystem constantly ebbs and flows between simplicity and complexity. The nature of an ever-evolving development model makes it essential to keep your tooling updated, or else you find yourself stranded on a “maintenance island”. The current tool du jour is Vite, and I find the decisions made with it a refreshing net positive for the frontend development toolkit. It’s one of the more straightforward tooling options in the ecosystem with sane defaults but ultimate reconfigurability.

While the frontend ecosystem is handily winning the UI/UX development conversation, there’s also a lot that ASP.NET Core’s Razor can offer application developers, and it’s arguably a better option to rely on both when building user-facing applications.

In this post, we’ll see how to integrate Vite’s development server with ASP.NET Core, and you’ll be surprised it’s much simpler than you may think. Let’s get started.

What’s Vite?

Before jumping into ASP.NET code, let’s talk about Vite and how it can help your development workflow. Vite is a development environment for developers using various frameworks, such as React, Angular, Vue, and other libraries. Vite also is “smart” and can recognize common development dependencies, such as TypeScript and Sass, giving developers a low-ceremony approach to adding the dependencies to their projects. Finally, Vite is compatible with Rollup plugins to process other assets, such as images, styles, and HTML.

For developers, Vite operates in two modes: development and build. Vite’s development mode utilizes hot-module reload capabilities to provide developers with immediate feedback when assets change on disk. This mode increases the feedback-loop time, increasing developer productivity. It also allows developers to see unprocessed assets to improve the ability to debug issues.

During the build mode, assets are processed through plugins and ultimately readied for deployment. The build includes all referenced JavaScript, Stylesheets, and HTML files. Additionally, Vite copies all static assets to the final build directory.

In summary, Vite is a development tool that simplifies an increasingly complex frontend ecosystem, and I believe it works. Check out the official site to learn more. https://vitejs.dev/

Adding Vite To ASP.NET Core

The first step to adding Vite to your ASP.NET Core applications is getting all your files and folders in the right place. The two most essential elements will be where you place your package.json and your frontend development folder. I named my development folder Client, but feel free to call it whatever you’d like.

Project
|- wwwroot
|- /Client
  |- /public
  |- /src
  |- main.ts
|- package.json

In your packages.json, you’ll add all your development dependencies, with the most critical being vite and typescript (if you want to use TypeScript). Here’s my package.json file for my sample project, including my scripts.

{
  "name": "my-webcomponents",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview"
  },
  "devDependencies": {
    "ts-node": "^10.9.1",
    "typescript": "^5.0.2",
    "vite": "^4.2.0",
    "bootstrap": "^5.2.3",
    "jquery": "^3.6.4",
    "jquery-validation": "^1.19.5",
    "jquery-validation-unobtrusive": "^4.0.0",
    "sass": "^1.61.0"
  }
}

Next, we need both the tsconfig.json and vite.config.ts files at the root of our project. Here are mine, respectively.

{
  "compilerOptions": {
    "composite": true,
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "declaration": true,
    "emitDeclarationOnly": true,
    "outDir": "./Client/types",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "moduleResolution": "Node",
    "isolatedModules": true,
    "allowSyntheticDefaultImports": true,
    "experimentalDecorators": true,
    "forceConsistentCasingInFileNames": true,
    "useDefineForClassFields": false,
    "skipLibCheck": true,
    "types": [
      "vite/client"
    ]
  },
  "include": [
    "vite.config.ts",
    "Client"
  ]
}

The vite.config.ts file is a bit of a doozy, but it’s written to support the same HTTPS certificate your ASP.NET Core application will use by loading settings from your appSettings files.

/**
 * Name: vite.config.ts
 * Description: Vite configuration file
 */

import { UserConfig, defineConfig } from 'vite';
import { spawn } from "child_process";
import fs from "fs";
import path from "path";

// @ts-ignore
import appsettings from "./appsettings.json";
// @ts-ignore
import appsettingsDev from "./appsettings.Development.json";

import * as process from "process";

// Get base folder for certificates.
const baseFolder =
    process.env.APPDATA !== undefined && process.env.APPDATA !== ''
        ? `${process.env.APPDATA}/ASP.NET/https`
        : `${process.env.HOME}/.aspnet/https`;

// Generate the certificate name using the NPM package name
const certificateName = process.env.npm_package_name;

// Define certificate filepath
const certFilePath = path.join(baseFolder, `${certificateName}.pem`);
// Define key filepath
const keyFilePath = path.join(baseFolder, `${certificateName}.key`);

// Pattern for CSS files
const cssPattern = /\.css$/;
// Pattern for image files
const imagePattern = /\.(png|jpe?g|gif|svg|webp|avif)$/;

// Export Vite configuration
export default defineConfig(async () => {
  // Ensure the certificate and key exist
  if (!fs.existsSync(certFilePath) || !fs.existsSync(keyFilePath)) {
    // Wait for the certificate to be generated
    await new Promise<void>((resolve) => {
      spawn('dotnet', [
        'dev-certs',
        'https',
        '--export-path',
        certFilePath,
        '--format',
        'Pem',
        '--no-password',
      ], { stdio: 'inherit', })
          .on('exit', (code: any) => {
            resolve();
            if (code) {
              process.exit(code);
            }
          });
    });
  };

  // Define Vite configuration
  const config: UserConfig = {
    clearScreen: true,
    appType: 'mpa',
    root: 'Client',
    publicDir: 'public',
    build: {
      manifest: appsettings.Vite.Manifest,
      emptyOutDir: true,
      outDir: '../wwwroot',
      assetsDir: '',
      rollupOptions: {
        input: ['Client/main.ts', "Client/scss/site.scss" ],
        // remove hashing, but I could add it back in
        output: {
          // Save entry files to the appropriate folder
          entryFileNames: 'js/[name].js',
          // Save chunk files to the js folder
          chunkFileNames: 'js/[name]-chunk.js',
          // Save asset files to the appropriate folder
          assetFileNames: (info) => {
            if (info.name) {
              // If the file is a CSS file, save it to the css folder
              if (cssPattern.test(info.name)) {
                return 'css/[name][extname]';
              }
              // If the file is an image file, save it to the images folder
              if (imagePattern.test(info.name)) {
                return 'images/[name][extname]';
              }

              // If the file is any other type of file, save it to the assets folder 
              return 'assets/[name][extname]';
            } else {
              // If the file name is not specified, save it to the output directory
              return '[name][extname]';
            }
          },
        }
      },
    },
    server: {
      port: appsettingsDev.Vite.Server.Port,
      strictPort: true,
      https: {
        cert: certFilePath,
        key: keyFilePath
      },
      hmr: {
        host: "localhost",
        clientPort: appsettingsDev.Vite.Server.Port
      }
    }
  }

  return config;
});

Feel free to modify the vite.config.ts to match your use case. For example, I removed the hash from all build artifacts, but you may want to add them back.

You’ll also want to modify the input array to produce the required files on the build. In my case, I want to build both my site’s CSS and JavaScript as separate assets.

If you get stuck configuring your Vite configuration, I suggest you read the Vite documentation to see all available options.

Important note: The build assets should end up in wwwroot so ASP.NET Core can bundle and publish them correctly. Also, modify your csproj to include any files on publish. As this is project specific, you’ll need to figure this out independently.

Next, we must modify our appsettings.json and appsettings.Development.json files. So here they are, respectively.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Vite": {
    "Manifest": "assets.manifest.json"
  }
}

And The development settings, which includes a Vite section. Here we will tell the Middleware what port the Vite dev server will be listening on. You can also set the script name here, but by default, the Vite middleware will look for a script named dev.

{
  "DetailedErrors": true,
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "Vite": {
    "Server": {
      "Port": 5173,
      "Https": true
    }
  }
}

Let’s install the NuGet package of Vite.AspNetCore by adding it to our project’s csproj file.

<ItemGroup>
  <PackageReference Include="Vite.AspNetCore" Version="1.4.0" />
</ItemGroup>

Once you’ve installed the package, register the services and Middleware in your ASP.NET Core application.

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsDevelopment())
{
    builder.Services.AddViteDevMiddleware();
}
// Add the Vite Manifest Service.
builder.Services.AddViteManifest();

And here’s the registration for Middleware.

if (app.Environment.IsDevelopment())
{
    app.UseViteDevMiddleware();
}

Here is my complete Program.cs file, so you can see where to place each code block.

using Vite.AspNetCore.Extensions;

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsDevelopment())
{
    builder.Services.AddViteDevMiddleware();
}
// Add the Vite Manifest Service.
builder.Services.AddViteManifest();

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.MapControllers();

if (app.Environment.IsDevelopment())
{
    app.UseViteDevMiddleware();
}

app.Run();

There’s one more step, which is to connect the client to our Vite development server. We must modify the _Layout.cshtml page with additional environment tags to do that.

<environment include="Development">
    <!-- Vite development server script -->
    <script type="module" src="~/@@vite/client"></script>
    <script defer type="module" src="~/main.ts"></script>
</environment>
<environment include="Production">
    <link rel="stylesheet" href="~/@Manifest["scss/site.scss"]!.File" asp-append-version="true"/>
    <script defer type="module" src="~/@Manifest["main.ts"]!.File" asp-append-version="true"></script>
</environment>

This code block in your layout will depend on your vite.config.ts file and the resulting assets in your manifest. The Vite.AspNetCore package comes with a helpful manifest helper, so you don’t have to know what the artifact name will be on the build, you use the source name instead, and it finds the correct name for you.

If you’ve followed my steps correctly, you should now have an ASP.NET Core application talking to the Vite development server. You can also change any asset and see Vite’s HMR update your page immediately. Very cool!

Caveats

The Vite.AspNetCore project isn’t waiting for the Vite server to start, so initial page loads may not immediately connect to the server. I’ll be attempting to submit a pull request to fix this issue. If you don’t see your assets on the page, try reloading your page.

A Vite caveat, you must import Sass assets in your JavaScript or TypeScript files to take advantage of hot module reloads.

Vite configuration is a dense topic. While the defaults work in most situations, reading more about the topic, precisely things like Rollup plugins, doesn’t hurt.

You may want to exclude your wwwroot from source control, as running the build locally will create and change those files every time. In addition, churn can add a lot of noise to your pull requests and make code reviews a headache.

Conclusion

Vite is a powerful development tool for folks building frontend experiences. The Vite.AspNetCore Middleware is an excellent option for folks who want to merge their front and back end into a single process. I want to thank the author Quetzal Rivera for taking the time to create the package so the community can benefit from their work.

I’ve created a working solution at my GitHub repository if you want to see a functioning sample.

As always, thanks for reading.

Unit Test 11ty Pages With Vitest and Typescript

Tue, 25 Apr 2023 00:00:00 +0000

11ty (pronounced eleventy) is the most incredible static site generator available to the JavaScript community. It’s powerful, flexible, and has just enough opinions to make you immediately productive while letting you and your team build the development workflow of your dreams.

In this post, we’ll explore unit testing your 11ty views if you’ve decided to use a combination of Typescript/JavaScript templates mixed with string literals. Of course, this approach also works with JSX, which I’ll use in the code below. Let’s get started.

JavaScript Template Language

While 11ty offers a multitude of template languages, folks who are comfortable writing JavaScript and appreciate tooling help should consider using TypeScript and the JavaScript template language features of 11ty.

While I adore templating languages like Liquid, Nunjucks, and Mustache, tooling can sometimes fall short in these contexts, providing you with little information about your data model and what fields are accessible. On the other hand, when working with JavaScript templates, tooling can effectively introspect types, function parameters, and much more. The JavaScript template approach can help you identify issues before they spiral out of control. You can take it further and create all your templates using TypeScript.

Let’s see what a JavaScript template declaration might look like.

class Test {
  // or `async data() {`
  // or `get data() {`
  data() {
    return {
      name: "Ted",
      layout: "teds-rad-layout",
      // … other front matter keys
    };
  }

  render({name}) {
    // will always be "Ted"
    return `<p>${name}</p>`;
  }
}

module.exports = Test;

As you can see, a few things are happening in the previous code.

There is a data getter that returns the template’s “frontmatter”.
There is a render method that returns HTML.
All methods are in a class definition.
All methods support sync and async implementations.
data() has access to this, an EleventyPage instance; the render method also has access to this along with the page’s frontmatter.

Awesome! So how do you write a test for this class?

Writing Tests For 11ty JavaScript Templates

First of all, you need to pick a unit testing environment. For simplicity’s sake, I used a combination of Vite and Vitest. I will also be using TypeScript to get an enhanced tooling experience.

Let’s look at the template we’ll be unit testing. I’ve created an Example.tsx file to use JSX.

import h, {JSX} from "vhtml";

export class Example {
    data(): Context {
        return {
            // @ts-ignore, 11ty shortcode
            greeting: this.lower("Hi")
        }
    }

    render(this: MyThis, context: Context) : JSX.Element {
        // VIP over here
        return this.name === 'Khalid'
            ? (<h1>{context.greeting} {this.name}</h1>)
            : (<h6>{context.greeting} {this.name}</h6>)
    }
}

export type MyThis = { name: string; lower: Function; }
export type Context = { greeting : string }

module.exports = Example;

I’m also defining expected types for this, which you can get from the parameters list of each method, or you can use this implicitly.

Knowing that we’re looking for specific data, we can now use our types for better tooling support and a better idea of how to stub out functionality and required data. So now, let’s take a look at the test.

// @ts-ignore
import h, {JSX} from "vhtml";
import {expect, it} from "vitest";
import { Example } from "./Example";

it('can set this on render method', () => {
    const example = new Example();
    const myThis = {
        name: "Khalid",
        lower: (i: string) => i.toLowerCase()
    };

    const data = example.data.apply(myThis);
    const result = example.render.apply(myThis, [ data ]);

    expect(result).to.equal("<h1>hi Khalid</h1>")
});

The vital part of the test is taking the methods of our template, in this case, it’s data and render, and using the apply method to change the this on each method call.

The advantage to this approach is that you can now stub and replace any functionality within your templates. In addition, using types makes it relatively straightforward to test different data scenarios, such as no elements in a collection instead of some elements.

Conclusion

There are a lot of template language choices in the 11ty toolbox, and I think you should try them all. They each have strengths and weaknesses, but it’s great that they’re all built on top of a core set of 11ty data objects. If you need to unit test your templates for complex visual logic, consider the JavaScript template language, as it’s easy to verify and fix bugs using this approach. I should note that unit tests should be an addition to your testing strategy and that you should always confirm your work by running it through 11ty itself.

Well, I hope you enjoyed this post, and as always, thank you for reading.

Writing a Cross-Platform Clock App With Avalonia UI and NXUI

Tue, 18 Apr 2023 00:00:00 +0000

Avalonia UI has been a refreshing reprieve from my typical web development workflows. Of course, the web will always be my first love, but I’m enjoying the ease and intuitiveness of desktop app development. Additionally, the Avalonia team has put extraordinary work into making a truly cross-platform development experience. So if you want to build your first Avalonia-powered application, this post might be just for you.

I’ll be using the NXUI library written by Wiesław Šoltés. If you’re allergic to XAML, this library might be your detour to desktop development, as it relies on a fluent interface to define views while retaining the APIs that make XAML so expressive.

So, let’s get started!

What is NXUI?

NXUI is an attempt to bring the trend of minimalism to desktop application development built around the Avalonia UI API. As author, Wiesław Šoltés states in the NXUI readme:

Creating minimal Avalonia next generation (NXUI, next-gen UI) application using C# 10 and .NET 6 and 7

So what does the code of a next-generation Avalonia application look like?

Window Build() => Window().Content(Label().Content("NXUI"));

AppBuilder.Configure<Application>()
  .UsePlatformDetect()
  .UseFluentTheme()
  .StartWithClassicDesktopLifetime(Build, args);

Wow! That’s relatively minimal, but let’s write something more useful. How about a clock? It’s time to write some code (pun intended).

To start building your first NXUI application, you’ll need to add the following to a .NET console app’s .csproj.

<PackageReference Include="NXUI" Version="11.0.0-preview5" />

Note: the version might differ when searching on NuGet. Be sure to use the latest version of the package.

An Avalonia UI Clock App

NXUI relies heavily on Observable elements to hydrate dynamic values in a view. In the case of our demo, we’ll be using the System.Timers.Timer class to create a new string value using the current DateTime.Now result. Let’s see how you create an Observable<string> that returns values on a specified interval.

var currentTime = Observable.Create<string>(
    observer =>
    {
        var timer = new System.Timers.Timer {
            Interval = 250,
        };
        timer.Elapsed += (_, _) => observer.OnNext($"{DateTime.Now:hh:mm:ss tt}");
        timer.Start();
        return Disposable.Empty;
    });

When working with NXUI, you’ll often use the Observable.Create method for dynamic values. You can also refactor many calls into separate classes and helper methods.

Next, let’s Build our view, which will hold our time string.

Window Build() =>
    Window()
        .Width(400).Height(200).CanResize(false)
        .WindowStartupLocation(WindowStartupLocation.CenterScreen)
        .Content(
            Border()
                .Margin(25, 0, 25, 0)
                .Height(100)
                .CornerRadius(10)
                .BoxShadow(BoxShadows.Parse("5 5 10 2 Black"))
                .Background(Brushes.White)
                .Child(
                    TextBlock()
                        .Foreground(Brushes.Black)
                        .TextAlignmentCenter()
                        .ZIndex(1)
                        .FontSize(40)
                        .FontStretch(FontStretch.Expanded)
                        .VerticalAlignment(VerticalAlignment.Center)
                        // Set The Observable<string> to Text
                        .Text(currentTime)
                )
        );

We have a window with a single Border element, which wraps our TextBlock. The most important aspect of our code is that the call to TextBlock.Text takes our currentTime argument. As the timer ticks, the UI will update with our latest value.

The code for this demo is a tight 40 lines of code.

var currentTime = Observable.Create<string>(
    observer =>
    {
        var timer = new System.Timers.Timer {
            Interval = 250,
        };
        timer.Elapsed += (_, _) => observer.OnNext($"{DateTime.Now:hh:mm:ss tt}");
        timer.Start();
        return Disposable.Empty;
    });

Window Build() =>
    Window()
        .Width(400).Height(200).CanResize(false)
        .WindowStartupLocation(WindowStartupLocation.CenterScreen)
        .Content(
            Border()
                .Margin(25, 0, 25, 0)
                .Height(100)
                .CornerRadius(10)
                .BoxShadow(BoxShadows.Parse("5 5 10 2 Black"))
                .Background(Brushes.White)
                .Child(
                    TextBlock()
                        .Foreground(Brushes.Black)
                        .TextAlignmentCenter()
                        .ZIndex(1)
                        .FontSize(40)
                        .FontStretch(FontStretch.Expanded)
                        .VerticalAlignment(VerticalAlignment.Center)
                        // Set The Observable<string> to Text
                        .Text(currentTime)
                )
        );

AppBuilder
    .Configure<Application>()
    .UsePlatformDetect()
    .UseFluentTheme()
    .StartWithClassicDesktopLifetime(Build, args);

Running our code, we see a functioning clock application. Pretty cool! (The image reflects the clock from the final sample).

Conclusion

The most fantastic part of Avalonia has been the rich ecosystem of folks building different ways to make the technology accessible. If you like XAML, then that’s great. If you want C#, there are also ways to access Avalonia. If you’re an F# person, there are also folks working on F# implementations of Avalonia. NXUI is one of many approaches in the Avalonia ecosystem. The fluent interface made it a little more accessible to discover the properties of components and how they might tie together.

If you’d like to play around with the code found in this post, I’ve pushed up a complete working Avalonia Clock sample at my GitHub repository.

Dependency Injection with Avalonia UI Apps

Tue, 11 Apr 2023 00:00:00 +0000

I’ve recently been experimenting with Avalonia UI, a development framework for desktop and mobile platforms, and I’ve been enjoying the experience. While Avalonia has much to offer out of the box, it is more than happy to let you make many decisions. One of those decisions is whether to use dependency injection as a part of your application.

In this experimental post, we’ll see how I added dependency injection into an ongoing Avalonia application and discuss the pros and cons of the approach.

Let’s get started.

Registering Your Dependencies

Since no infrastructure exists for user-defined dependency injection in Avalonia (or at least non that I am aware of), we must create our own. The first step to any dependency injection approach is finding and registering all our dependencies.

For the post, I’m using Lamar, the spiritual successor of StructureMap. Of course, you can substitute your own, but I like Lamar’s interface for scanning and registering types.

I added the following code in Program.cs of my Avalonia app.

public static IContainer Container { get; }

static Program()
{
    Container = new Container(cfg =>
    {
        cfg.Scan(scan =>
        {
            scan.AssemblyContainingType<Program>();
            scan.AddAllTypesOf<ViewModelBase>();
            scan.AddAllTypesOf<IControl>();
            scan.WithDefaultConventions();
        });
    });
}

This code scans my application for all types of ViewModelBase and IControl along with the default conventions of Lamar. A sane default is registering concrete types against their first interface. Now that we set up our dependency graph let’s start changing our view models and views.

WindowBase and ViewModelBase

Using the Model-View-ViewModel approach, I must create base classes for my views and viewmodels. Let’s look at both now, starting with my WindowBase class.

using Avalonia.Controls;
using HelloAvalonia.ViewModels;
using Lamar;

namespace HelloAvalonia.Views;

public abstract class WindowBase<T> : Window
    where T: ViewModelBase
{
    [SetterProperty]
    public T ViewModel
    {
        get => (T)DataContext!;
        set => DataContext = value;
    }
}

You’ll notice I’m using an attribute called SetterProperty on a new ViewModel property. As Lamar builds our Window, it will also resolve the ViewModel and set the DataContext. I opted to use property injection to allow the Avalonia preview tool to continue working in JetBrains Rider.

Now, let’s look at our ViewModelBase implementation.

using CommunityToolkit.Mvvm.ComponentModel;

namespace HelloAvalonia.ViewModels;

public abstract class ViewModelBase : ObservableObject
{
}

I’m using the CommunityToolkit.Mvvm package, so my ViewModels inherit from ObservableObject. Now, let’s implement a view model instance.

MainWindow, MainWindowViewModel, and Dependencies

Like our ViewModel property in our WindowBase class, we’ll resolve all dependencies using the SetterProperty attribute. First, let’s change our main view to inherit from WindowBase. The change will ensure our DataContext is set as our container creates the instance.

using System;
using HelloAvalonia.ViewModels;
using Lamar;

namespace HelloAvalonia.Views;

public partial class MainWindow : WindowBase<MainWindowViewModel>
{
    public MainWindow()
    {
        InitializeComponent();
    }
        
    [SetterProperty]
    public DialogWindow? Dialog { get; set; }

    public Action ShowDialogInteraction => 
        () => Dialog?.ShowDialog(this);
}

I will also need another dialog window to show some other information. For example, I can ask for any control registered in my container.

In this example, I’m using the dialog instance to create an interaction and pass it to my view model to keep controls out of my business logic.

<Button
    Content="Show Dialog"
    Command="{Binding ShowDialogCommand}"
    CommandParameter="{Binding #Main.ShowDialogInteraction}"
    HorizontalAlignment="Center">

Now let’s see the MainWindowViewModel implementation.

using System;
using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;

namespace HelloAvalonia.ViewModels;

public partial class MainWindowViewModel : ViewModelBase
{
    [ObservableProperty, NotifyPropertyChangedFor(nameof(PlayAnimation))]
    private int _count;

    [ObservableProperty]
    private bool _isEnabled = true;

    [ObservableProperty] private string _text = "Click Me";
    public bool PlayAnimation => Count > 0 && Count % 2 == 0;

    [RelayCommand]
    private void Click()
    {
        Count++;
        Text = Count == 1
            ? $"Clicked {Count} time"
            : $"Clicked {Count} times";
    } 

    [RelayCommand]
    private void ShowDialog(Action? showDialogInteraction)
    {
        showDialogInteraction?.Invoke();
    }
}

There are no dependencies here, but we pass our interaction to our ShowDialog method. So what’s the dialog implementation look like?

using System;
using HelloAvalonia.ViewModels;

namespace HelloAvalonia.Views;

public partial class DialogWindow : WindowBase<DialogWindowViewModel>
{
    public DialogWindow()
    {
        InitializeComponent();
    }
    
    public Action HideInteraction => Hide;
}

And the View Model is even simpler.

using System;
using System.Threading.Tasks;
using Avalonia.Media.Imaging;
using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;
using HelloAvalonia.Models;
using Lamar;

namespace HelloAvalonia.ViewModels;

public partial class DialogWindowViewModel : ViewModelBase
{
    [SetterProperty] 
    public ICatsImageService? Cats { get; set; }

    [ObservableProperty] private Bitmap? _catImage;

    [RelayCommand]
    private async Task Opened()
    {
        if (Cats is { })
        {
            var bitmap = await Cats.GetRandomImage();
            CatImage = bitmap;
        }
    }

    [RelayCommand]
    private void Hide(Action? interaction)
    {
        CatImage = null;
        interaction?.Invoke();
    }
}

We are injecting an instance of ICatsImageService using Lamar’s SetterProperty attribute.

So now that we have our views and viewmodels, where is our entry point?

The Entrypoint

The entry point of an Avalonia app occurs in the App implementation. Therefore, I modify the OnFrameworkInitializationCompleted method to use the container I define in Program.

using Avalonia;
using Avalonia.Controls.ApplicationLifetimes;
using Avalonia.Markup.Xaml;
using HelloAvalonia.Views;

namespace HelloAvalonia;

public partial class App : Application
{
    public override void Initialize()
    {
        AvaloniaXamlLoader.Load(this);
    }

    public override void OnFrameworkInitializationCompleted()
    {
        if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
        {
            desktop.MainWindow = 
                Program
                .Container
                .GetInstance<MainWindow>();
        }

        base.OnFrameworkInitializationCompleted();
    }
}

That’s it! We now have a working application.

Conclusion

Some folks hate dependency injection, and some folks love it. I think it has value in complex applications where you want to define “how” things are set up in one place and forget about it. With Avalonia, it takes a bit of work to get started with dependency injection, but not too much.

It’s essential to be mindful of the lifetimes of your controls and their dependencies. As you’re dealing with a desktop application, I don’t see a need to create multiple instances of objects, so Singleton registrations should work fine in most cases.

Well, I hope you liked this post. I’ve included the code to this Avalonia UI sample on my GitHub repository for you to try.

Load YouTube Embed Videos When Needed With JavaScript

Tue, 04 Apr 2023 00:00:00 +0000

If you’re a content creator or work on a site that heavily relies on YouTube embeds, you’ll quickly realize that they can dramatically impact the load time of a page. Load times can also grow depending on the number of YouTube embeds on a page.

In this post, we’ll see a technique to reduce page load times by using newer HTML and JavaScript techniques to load videos when the user needs them.

Let’s get started.

Why Are YouTube Embeds Slowing My Page Load Times

YouTube videos typically have a thumbnail image displayed to the user before the video starts. YouTube may serve up to four thumbnails, all varying in quality. Unfortunately for performance, most browsers treat images as blocking elements on a page. Regarding performance, this means the page cannot complete loading unless the element is also loaded.

There have been recent techniques to mitigate this issue, including adding a width and height to images so the client can calculate the layout in advance of the image loading and the use of the lazy attribute to signify that you’re willing to load the asset outside of the critical rendering path. That’s great, right?!

Well, YouTube embeds utilize an iframe where you don’t have control over the markup or attributes. So how do you get around this issue? You cheat… sort of.

Using Plyr For YouTube Embeds

In my use case, I had over 42 YouTube images on a page, with only one visible at a time. That’s a lot of image requests to YouTube’s thumbnail service, making my page understandably slow to load.

My first step was to use a video player other than that of YouTube’s iframe embed. In my case, I used Plyr. It’s pretty straightforward to use the library with existing YouTube content.

<div class="video-player" 
     data-plyr-provider="vimeo" 
     data-plyr-embed-id="76979871"></div>

With the HTML in place, you must create an instance of the Plyr JavaScript class for each occurrence of an embedded video.

const players = Array
    .from(document.querySelectorAll('.video-player'))
    .map((p) => new Plyr(p));

Note that this suffers from the same issue as before, so we need to be smarter here. You’ll see how to solve this same issue in the next section.

Using IntersectionObserver To Create Plyr Instances

Our goal is only to instantiate Plyr instances that the user sees. We can accomplish this using the IntersectionObserver type.

The Intersection Observer API provides a way to asynchronously observe changes in the intersection of a target element with an ancestor element or with a top-level document’s viewport. –Mozilla

For our use case, we’ll monitor our video elements’ visibility and call new Plyr once.

// import Plyr dependency
import Plyr from "plyr";

// simplified onVisible method
const onVisible = function (element, callback) {
  const  options = {
    root: document,
  };
  const observer = new IntersectionObserver((entries, observer) => {
    entries.forEach((entry) => {
      callback(entry, observer);
    });
  }, options);
  observer.observe(element);
};

// create an array of video player HTML elements
const videos = Array.from(document.querySelectorAll(".video-player"));
// apply onVisible callback
videos.forEach((video) => {
  onVisible(video, (entry, observer) => {
    if (entry.intersectionRatio > 0) {
      new Plyr(entry.target);
      observer.unobserve(entry.target);
    }
  });
});

The vital part of this code is the implementation of the callback for each element.

 if (entry.intersectionRatio > 0) {
      new Plyr(entry.target);
      observer.unobserve(entry.target);
}

Once we create the video player, we no longer need to observe its changes, as we’ve loaded all assets, and the video is ready for the user. Now videos are created when the user needs them, not on the initial page load.

Using the IntersectionObserver technique, my page load times went from several seconds to milliseconds. In addition, I improved performance and kept users happy with just a few lines of JavaScript.

Conclusion

Web development is easy to get into but takes a lifetime to master, especially as the APIs and features of HTML, JavaScript, and CSS improve. Also, when working with third parties, finding solutions around their implementations can be challenging. Luckily, you can always load things when needed rather than all at once. This technique can also be used for other network-heavy and blocking resources.

I hope you found this post interesting and helpful. As always, thank you for reading.

.NET MAUI App Stopped Working -- HELP!

Tue, 28 Mar 2023 00:00:00 +0000

So you’ve spent several weeks successfully developing a Multi-Application UI app. Then, suddenly, your IDE shows that your application has hundreds of errors, and you cannot build. What’s going on?!

This post is an ongoing list of issues you might encounter while developing MAUI apps that seem to break your app for inexplicable “reasons”. Finally, I’ll suggest potential fixes to get you back into the development flow.

Let’s Get Started!

Everything Is Screaming Red and Broken!

If you were successfully developing your application and suddenly your solution failed to load, you likely have changed your environment. Failed MAUI solutions indicate a change in the .NET SDK.

For example, you may have been developing successfully using the .NET 7 SDK and wanted to try the latest .NET 8 preview SDK. Unfortunately, after installing the SDK, everything is broken! Ahhh!

The problem is the easiest fix among the issues I’ve seen with MAUI. To fix the issue, add a global.json file at the root of your solution to tie your project back to the correct SDK band and to access the SDK band’s workloads.

{
  "sdk": {
    "version": "7.0.0",
    "rollForward": "latestMinor",
    "allowPrerelease": false
  }
}

You may need to restart your editor, but you should be back in business upon restart.

Build Fails with One or More Invalid Files Were Detected

So you decided to import some new resources to pretty up your MAUI application. Unfortunately, you’ll get this error message after importing, and you’re confused. Is it my new files?

Microsoft.Maui.Resizetizer.targets(525, 9): One or more invalid file names were detected. File names must be lowercase, start and end with a letter character, and contain only alphanumeric characters or underscores:

Deleting the new assets doesn’t fix your issue, and now your app is perpetually broken. Aaaaaah!

Well, have no fear. The error is another straightforward problem with a clear solution. MacOS users may have touched the files in the asset folder, creating a .DS_Store file that’s typically invisible in the solution explorer and Finder. However, you’ll see the file if you look at the Images folder using something like JetBrains Rider File Explorer.

Delete this file, and you’ll be back in business.

You can also resolve this issue by changing your MAUI project’s MauiImage wildcard in the .csproj only to include file extensions for known image types.

<!-- Images -->
<MauiImage Include="Resources\Images\*.{png,svg}" />

You can recreate the .DS_Store issue by running touch from the command line, which creates the offending file.

Pass SelectItem to My View Model Command

While not an issue, this one left me scratching my head for a bit, and I thought I’d save you the trouble of scratching your head. How do you bind a SelectItem from a CollectionView to a CommandParameter?

If you’re using an MVVM framework, like CommunityToolkit.Mvvm, you likely have a command on your view model that needs information from a user event like SelectionChanged.

The trick to this solution is to add a name to your component, then use the Source attribute to reference the item. It will make more sense when you look at the XAML.

<CollectionView
    x:Name="TodosCollectionView"
    VerticalOptions="Fill"
    ItemsSource="{Binding Items}"
    SelectionMode="Single"
    SelectionChangedCommand="{Binding SelectionChangedCommand}"
    SelectionChangedCommandParameter="{Binding SelectedItem, Source={x:Reference TodosCollectionView}}">
...
</CollectionView>

CommunityToolkit.Mvvm Can’t Find My Properties or Commands

CommunityToolkit.Mvvm uses source generators and requires an environment to read and generate the additional source code of your view models. The generated code includes properties and IAsyncRelayCommand implementations. If you cannot find these elements in your code, you likely have one of the following issues in your code base.

You forgot the partial keyword on your view model. The name of your view model is not the same name as the generated command. For example, an OnAddItem method with RelayCommandAttribute will create an AddItemCommand command. Try cleaning your obj and bin folders, which might fix the current state of your project. By clean, I mean delete them from your disk. Restart your IDE.

My MAUI App Never Starts! What Gives?!

If you’re using the dependency injection facility of MAUI, you must register all dependencies as part of your MauiProgram file. Check your development environments console output for mentions of the following error.

System.InvalidOperationException: Unable to resolve service for type...

The solution is to register the missing type in MauiProgram.

builder.Services.AddSingleton<AppShell>();
builder.Services.AddSingleton<MainPage>();
builder.Services.AddSingleton<MainPageModel>();
builder.Services.AddSingleton<TodoItemPage>();
builder.Services.AddSingleton<TodoItemPageModel>();

As a suggestion, you may want to create a convention to register pages and their corresponding view models automatically.

My MAUI Build is Slow!

If you’re running a build for every target framework in your TargetFrameworks tag, you’ll get some slow builds.

<TargetFrameworks>net7.0-ios;net7.0-maccatalyst;net7.0-android;</TargetFrameworks>

In my case, iOS is the fastest build, so I remove a few target frameworks until I’m ready to work on Android.

<TargetFrameworks>net7.0-ios<TargetFrameworks>

If you want to put in the additional effort, you can use environment variables and MSBuild flags to create different builds for different situations.

The downside to this approach is you can inadvertently build something that works in iOS that is completely broken on other platforms before you realize it.

Conclusion

Developing with MAUI can be fun, but opaque errors are inevitable. I hope some of the problems and solutions outlined in this post can get you back on track.

.NET MAUI Development Environment Set Up Walkthrough

Tue, 21 Mar 2023 00:00:00 +0000

Last year I wrote macOS Environment Setup for MAUI Development for the JetBrains .NET blog, and while many folks have told me they still find it helpful, it is, admittedly, out of date. So in this post, I’ll give you a shorter and more manageable guide to setting up your development environment for Multi-platform App UI (MAUI) in 2023.

I’ve helped several folks set up their macOS environment with this updated guide, and it should mostly apply to a Windows environment (outside of the OS-specific SDKs).

Installing the .NET SDK

The first and most obvious step is you’ll need to install the latest .NET SDK. Head over to https://dot.net and download the latest MAUI-supported SDK. As of writing this article, that is .NET 7.

The SDK is necessary as dotnet will install and manage MAUI workloads according to SDK version bands.

Once you’ve installed the .NET SDK, we’ll focus on the next important step.

Installing XCode for MAUI

You’ll need to install XCode, ensuring that MAUI supports the version of XCode you are installing. For .NET 7, the current version of XCode is 14.2.

I recommend installing XCode using the Apple AppStore, as it’s the more straightforward method. You’ll want to pick Apple SDKs for iOS and macOS when installed. Other SDKs for Apple Watch and Apple TV are optional.

Start up XCode and open the application’s settings. Next, you’ll need to navigate to Locations and ensure that Xcode is the correct value in the Command Line Tools select dropdown. If the dropdown has no value, be sure to select one. These tools help compile native assemblies for Apple device targets.

While you’re here, check your Platforms tab to ensure you have all the SDKs installed correctly.

You’re good to go with XCode.

Installing Xamarin.iOS and Xamarin.macOS

You’ll also want to install the latest Xamarin SDKs since MAUI still uses these. Visual Studio for Mac and Visual Studio ship these with each release, but you can install them without those apps. These SDKs also ship with JetBrains Rider’s plugins but can be outdated for MAUI development.

You can download the latest Xamarin.iOS and Xamarin.mac packages here.

You’ll only need the package for the environments you are targeting, but you’re already installing gigabytes of dependencies, so what’s a few more?

Installing MAUI Workloads

Important! Add a global.json file with the correct SDK band you’ll be building MAUI apps. For example, in the case of this guide, you’re working with .NET 7. So your global.json file should look like the following:

{
  "sdk": {
    "version": "7.0.0",
    "rollForward": "latestMajor",
    "allowPrerelease": false
  }
}

If you only have one SDK installed, you can skip this file. However, remember that you’ll need this file if you install any other SDKs.

Workloads include all the necessary assemblies and MSBuild targets that make building a mobile application possible for a given platform. For example, most developers will want to target iOS, Android, and Mac Catalyst.

Run the following commands in a new terminal. Note you’ll need elevated administrator permissions to complete this step.

sudo dotnet workload install maui
sudo dotnet workload install maui-android maui-ios maui-maccatalyst
sudo dotnet workload install ios android maccatalyst
sudo dotnet workload install wasm-tools

Once you install all these workloads, you can double-check that everything went accordingly using the command dotnet workload list. You can also find other workloads using the dotnet workload search command.

Installing Microsoft OpenJDK

You’ll need an OpenJDK installation to build and work with Android. I’ve found that Microsoft’s OpenJDK 11.0.18 LTS works best with MAUI. You can find the download here.

You might need to set the JAVA_HOME environment variable on your environment to point to the location of the newly installed OpenJDK. This step is optional if you use an IDE like JetBrains Rider.

This next step is to get Android SDKs configured.

Installing Android SDKs

This next step requires Android Studio, or if you’re a JetBrains Rider user, these same features also exist in that product. We’ll be using JetBrains products to install Android SDKs.

Note to JetBrains Rider users, you’ll need to install the Rider Xamarin Android Support plugin.

As a JetBrains Rider user, you’ll want to check your environments tab to ensure all environments are installed or recognized.

Next, under the Android section in JetBrains Rider (or Android Studio), you’ll want to install the SDK that matches your MAUI install. As of writing this post, that version is 33. Find the Install new button and walk through the installation.

Once completed, go back to the Android section and choose SDK Components. Here, you’ll select the following:

Android 13.0 (Tiramasu) under SDK Platforms
NDK (Side-by-side) under SDK Tools

When downloads and installation are complete, finish this process by ensuring the paths are set correctly on your Android settings page. This dialog is also where you’ll set the path to the OpenJDK 11 install from earlier.

Simulators and Emulators

For iOS, you’ll want to start your simulator at least once before trying any MAUI development. I recommend this step because the first time you boot an iOS simulator, it takes a minute to prepare everything. Start XCode, use the settings menu XCode > Open Developer Tool, and select “Simulator”.

In JetBrains Rider, this is the time to set up a new Android device emulator. Search for Device Manager and set up a new device. You can also choose to attach a physical Android device. That’s up to you.

You’ll need these virtual devices for testing your MAUI applications.

Your First MAUI App

Phew! We’re at the finish line! Yay! Hopefully, you followed every step meticulously, and I didn’t miss anything obvious. But, honestly, this is a lot to take in, especially if it’s your first attempt at mobile app development.

Now you can create a new MAUI app and run it in the environment of your choice.

If you get build errors, don’t panic. Remember, you need a global.json file to tie your new solution to the correct SDK version band. Scroll back up and use the same global.json file from the previous section.

Conclusion

Hopefully, I covered every step necessary to build iOS and Android MAUI apps in your development environment. Of course, if you’re on Windows, you might have different challenges, but most of this guide still applies to you for Android development. Of course, you’ll still need Windows workloads to target MAUI for Windows. Use the dotnet workload search to find the appropriate packages.

Anyways, if you found this post helpful, I’m happy for you. You got a working MAUI environment, and that’s no tiny feet. So take this time to bask in your success. You deserve it.

If you need help, you can find me on Mastodon or contact me through the form on this site. Cheers :)

Solving .NET JSON Deserialization Issues

Tue, 14 Mar 2023 00:00:00 +0000

What is more frustrating than a sem-working solution, am I right? Unfortunately, when it comes to JSON serialization, that can mean getting some of the data sometimes. You’re left scratching your head and asking, “Why is my data not coming through correctly?”

In this post, we’ll explore the different JsonSerializerOptions you might run into with .NET and how you can predict the behavior of your serialization. Let’s get started.

Starting With Plain-old JSON

When working with JSON, two parties are typically involved: The producer and the consumer. Unfortunately, more often than not, when running into JSON deserialization issues, we often find that we misunderstood the producer’s JSON format and likely misconfigured something on our end. Let’s look at an example response from a hypothetical JSON API.

[
   {
      "name": "Khalid Abuhakmeh",
      "hobby" : "Video Games"
   },
   {
      "name": "Maarten Balliauw",
      "hobby" : "Gardening" 
   }
]

There are a few characteristics to note about this response.

The top-level element is an array.
There are multiple elements in the array. Two, to be exact.
All fields are quoted.
All field names are camel-cased.

To process this JSON response, we need to set up our serialization options to match the JSON serialization choices of our producer. In the next section, let’s look at ways to fail and succeed at deserialization.

Attempting to Deserialize JSON

The first likely step folks will take to use the JsonSerializer class as is, with a straight call to Deserialize<T>.

var @default = JsonSerializer.Deserialize<Person[]>(json);
Console.WriteLine($"default: {@default?[0]}");

I’m sad to say this is incorrect, as the default serializer options work from “PascalCase”. So the result of this deserialization will produce entities, but their values will be null or empty.

default: Person { Name = , Hobby =  }

Oops! Where are the Name and the Hobby? Well, it turns out that we have a naming mismatch. So how do we fix this issue? There are a few options.

The first way to fix this issue is to use a different set of options for the JsonSerializer. For example, we can use the JsonSerializerDefaults class to choose the Web option.

// camelCase
var web = JsonSerializer.Deserialize<Person[]>(json,
    new JsonSerializerOptions(JsonSerializerDefaults.Web));
Console.WriteLine($"web: {web?[0]}");

Choosing the JsonSerializerDefaults.Web value for JsonSerializerOptions defaults to the camel case for all JSON field names. Running the code above, we have corrected our initial issues.

web: Person { Name = Khalid Abuhakmeh, Hobby = Video Games }

What if we have an unreliable producer, and they may inadvertently change their mind about casing? Well, there’s one more option.

// any Case
var any = JsonSerializer.Deserialize<Person[]>(json,
    new JsonSerializerOptions
    {
        PropertyNameCaseInsensitive = true
    });
Console.WriteLine($"case insensitive: {any?[0]}");

This option will ignore casing on field names and map accordingly but be warned. Ignoring the case sensitivity of names will cause issues if the producer uses the same name for different fields. Running the code sample, we get the following result.

case insensitive: Person { Name = Khalid Abuhakmeh, Hobby = Video Games }

Cool! The solution still works, but there’s still one more solution to look over.

You’ll likely use the HttpClient class when working with JSON APIs. The HttpClient uses the JsonSerializerDefaults.Web options internally, so you don’t need any additional changes if you’re calling a camel-cased API.

// stubbing the web request to return the JSON
var httpClient = new HttpClient(new StubHandler(json));

// uses JsonSerializerOptions(JsonSerializerDefaults.Web) by default
var response = await httpClient.GetFromJsonAsync<Person[]>("https://example.com");
Console.WriteLine($"http client: {response?[0]}");

Running this code, we see the results we expect.

http client: Person { Name = Khalid Abuhakmeh, Hobby = Video Games }

You can also pass in any options to override the default behavior of the GetFromJsonAsync method.

var otherResponse = await httpClient.GetFromJsonAsync<Person[]>(
    "https://example.com",
    new JsonSerializerOptions
    {
        PropertyNameCaseInsensitive = true
    });
Console.WriteLine($"http client w/ options: {otherResponse?[0]}");

Running this sample, we still see the correct results.

http client w/ options: Person { Name = Khalid Abuhakmeh, Hobby = Video Games }

So, there we have it—a run-down of solving your serialization/deserialization issues when working with existing JSON APIs. I’ve included the complete solution below if you’d like to work with this sample.

As always, thanks for reading and sharing my posts.

using System.Net;
using System.Net.Http.Json;
using System.Text.Json;

// language=json
var json = """
[
   {
      "name": "Khalid Abuhakmeh",
      "hobby" : "Video Games"
   },
   {
      "name": "Maarten Balliauw",
      "hobby" : "Gardening" 
   }
]
""";

// PascalCase
var @default = JsonSerializer.Deserialize<Person[]>(json);
Console.WriteLine($"default: {@default?[0]}");

// CamelCase
var web = JsonSerializer.Deserialize<Person[]>(json,
    new JsonSerializerOptions(JsonSerializerDefaults.Web));
Console.WriteLine($"web: {web?[0]}");

// any Case
var any = JsonSerializer.Deserialize<Person[]>(json,
    new JsonSerializerOptions
    {
        PropertyNameCaseInsensitive = true
    });
Console.WriteLine($"case insensitive: {any?[0]}");

// stubbing the web request to return the JSON
var httpClient = new HttpClient(new StubHandler(json));

// uses JsonSerializerOptions(JsonSerializerDefaults.Web) by default
var response = await httpClient.GetFromJsonAsync<Person[]>("https://example.com");
Console.WriteLine($"http client: {response?[0]}");

var otherResponse = await httpClient.GetFromJsonAsync<Person[]>(
    "https://example.com",
    new JsonSerializerOptions
    {
        PropertyNameCaseInsensitive = true
    });
Console.WriteLine($"http client w/ options: {otherResponse?[0]}");

// ReSharper disable once ClassNeverInstantiated.Global
public record Person(string Name, string Hobby);

public class StubHandler : DelegatingHandler
{
    private readonly string _response;

    public StubHandler(string response)
    {
        _response = response;
    }

    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        return Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)
        {
            Content = new StringContent(_response),
            RequestMessage = request
        });
    }
}

Validating Connection Strings on .NET Startup

Tue, 07 Mar 2023 00:00:00 +0000

There exist extension points in .NET that allow you to verify the starting state of your application. Validating configuration can be helpful when you know that without certain elements, there’s no reason to start the application. One of those configuration values is connection strings, but there’s a catch. You may have set the value in the configuration, but the value either is to a non-existent resource or the resource is inaccessible.

In this short post, we’ll write an extension method and a class that will allow you to test your database connection on startup and fail the application if you can’t connect.

The Initial Host Configuration

Let’s look at the final solution and work our way backward. We have our application host, and we register a connection string validator. Our validation will get the connection string, determine the provider, and attempt a connection. If successful, the app starts. If unsuccessful, the app exits.

using System.Data.Common;
using Microsoft.Data.SqlClient;
using Microsoft.Data.Sqlite;
using Microsoft.Extensions.Options;
using Microsoft.IdentityModel.Tokens;
using WorkerServiceDatabase;

IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services
            .ValidateConnectionStrings()
            .ValidateOnStart();
        
        services.AddHostedService<Worker>();
    })
    .Build();

host.Run();

Neat, let’s see what challenges we have to overcome.

The ConnectionString Configuration

.NET allows you to bind a configuration to a strongly-typed object, but in the case of ConnectionStrings, that’s a well-known JSON section. So how do we accomplish that? Well, let’s have a look at our working configuration.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "ConnectionStrings": {
      "Sqlite": "Data Source=database.db",
      "SqlServer": "Data Source=localhost,11433;Initial Catalog=Northwind;User Id=sa;Password=Pass123!;Encrypt=false"
    }
}

ConnectionStrings looks like a JSON Dictionary, so we can bind to a class that inherits from Dictionary<string,string>.

public class ConnectionStrings
    : Dictionary<string,string>
{}

Awesome, but there’s a problem. None of our connection strings declare the database provider. So here’s the first decision you’ll want to make for your use case: “How do you map connection string names to their database providers?”

My approach to this issue was explicitly mapping the keys to a database provider in my ConnectionStrings constructor.

public class ConnectionStrings
    : Dictionary<string,string>
{
    public ConnectionStrings()
    {
        // these are the key names
        DbProviderFactories.RegisterFactory("Sqlite", SqliteFactory.Instance);
        DbProviderFactories.RegisterFactory("SqlServer", SqlClientFactory.Instance);
    }
}

These database factories come from the NuGet packages of Microsoft.Data.SqlClient and Microsoft.Data.Sqlite. You’ll need to add other database factories for providers like PostgreSQL, MySQL, or Oracle.

Next, let’s write our Validate method. This method will create a new connection using our connection strings and then attempt to open a connection to the database.

public class ConnectionStrings
    : Dictionary<string,string>
{
    public ConnectionStrings()
    {
        // these are the key names
        DbProviderFactories.RegisterFactory("Sqlite", SqliteFactory.Instance);
        DbProviderFactories.RegisterFactory("SqlServer", SqlClientFactory.Instance);
    }
    
    public bool Validate()
    {
        // can't inject logger :(
        var logger = LoggerFactory
            .Create(cfg => cfg.AddConsole().AddDebug())
            .CreateLogger("ConnectionStrings");
        
        List<Exception> errors = new();
        foreach (var (key, connectionString) in this)
        {
            try
            {
                var factory = DbProviderFactories.GetFactory(key);
                using var connection = factory.CreateConnection();
                if (connection is null) {
                    throw new Exception($"\"{key}\" did not have a valid database provider registered");
                }

                connection.ConnectionString = connectionString;
                connection.Open();
            }
            catch (Exception e)
            {
                var message = $"Could not connect to \"{key}\".";
                logger.LogError(message);
                errors.Add(new Exception(message, e));
            }
        }

        return errors.IsNullOrEmpty();
    }
}

The validate method loops over the values in our ConnectionString section, finding the DbProviderFactory and creating a connection.

I had to create a new logger factory so you could see the failed connection, but you could remove that if you want an all-or-nothing approach.

We have our class; now let’s wire it up.

The ConnectionString Validation Method

This section is pretty straightforward, we’ll write an extension method to bind our ConnectionStrings configuration section to our ConnectionStrings class and call the validate method.

public static class ConnectionStringExtensions
{
    public static OptionsBuilder<ConnectionStrings> 
        ValidateConnectionStrings(this IServiceCollection services)
    {
        return services
            .AddOptions<ConnectionStrings>()
            .BindConfiguration("ConnectionStrings")
            .Validate(c => c.Validate(), "Could not connect to 1 or more databases.");
    }
}

Easy peasy.

The Complete Solution

So how does this all look in one file? Where here it is.

using System.Data.Common;
using Microsoft.Data.SqlClient;
using Microsoft.Data.Sqlite;
using Microsoft.Extensions.Options;
using Microsoft.IdentityModel.Tokens;
using WorkerServiceDatabase;

IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services 
            // validate connection strings
            .ValidateConnectionStrings()
            .ValidateOnStart();
        
        services.AddHostedService<Worker>();
    })
    .Build();

host.Run();

public static class ConnectionStringExtensions
{
    public static OptionsBuilder<ConnectionStrings> 
        ValidateConnectionStrings(this IServiceCollection services)
    {
        return services
            .AddOptions<ConnectionStrings>()
            .BindConfiguration("ConnectionStrings")
            .Validate(c => c.Validate(), "Could not connect to 1 or more databases.");
    }
}

public class ConnectionStrings
    : Dictionary<string,string>
{
    public ConnectionStrings()
    {
        // these are the key names
        DbProviderFactories.RegisterFactory("Sqlite", SqliteFactory.Instance);
        DbProviderFactories.RegisterFactory("SqlServer", SqlClientFactory.Instance);
    }
    
    public bool Validate()
    {
        // can't inject logger :(
        var logger = LoggerFactory
            .Create(cfg => cfg.AddConsole().AddDebug())
            .CreateLogger("ConnectionStrings");
        
        List<Exception> errors = new();
        foreach (var (key, connectionString) in this)
        {
            try
            {
                var factory = DbProviderFactories.GetFactory(key);
                using var connection = factory.CreateConnection();
                if (connection is null) {
                    throw new Exception($"\"{key}\" did not have a valid database provider registered");
                }

                connection.ConnectionString = connectionString;
                connection.Open();
            }
            catch (Exception e)
            {
                var message = $"Could not connect to \"{key}\".";
                logger.LogError(message);
                errors.Add(new Exception(message, e));
            }
        }

        return errors.IsNullOrEmpty();
    }
}

There you have it.

Important. The validation process in .NET uses a ValidationHostedService, so it’s important that if you have any hosted service that relies on your configuration, then you should register them after your validation runs. If you don’t you’ll have your hosted service start before validation is completed.

Summary

Using .NET configuration extension points, we can validate the most critical resources. For example, using the DbProviderFactories class, we can register and support many database providers. However, you must make a design choice, as the ConnectionStrings section in the configuration doesn’t allow the provider to be set. Ultimately, my approach wasn’t too bad, but it could be better. Also, I found that the ConnectionStrings class instance must have a parameterless constructor and could not inject an instance of ILogger, which is why I created my own. If you are fine with a “pass/fail” approach, feel free to exclude the logger, which might lead to frustrating debugging to determine which connection string failed.

Thanks for reading, and I hope you enjoyed this post.

Speed Up ASP.NET Core JSON APIs with Source Generators

Tue, 28 Feb 2023 00:00:00 +0000

Building applications is a virtuous circle of learning about problems, finding solutions, and optimizing. I find optimizing an application the most fun, as it can help you squeeze performance out from surprising places.

In this post, we’ll see how you can use the latest JSON source generators shipped in .NET 6 to improve your JSON API performance and increase your response throughput.

Like many source generators in .NET, the System.Text.Json source generator enhances an existing partial class with essential elements required for serialization. Those elements include:

A JsonTypeInfo<T> for each serializable entity in your object graph.
A default instance of a JsonSerializerContext.
JsonSerialiazerOptions for formatting JSON on serialization.

Don’t worry; it’s not as complex as it sounds. Let’s first start with our entity.

public record Person(
    string Name,
    bool IsCool = true,
    Person? Friend = null
);

We want to optimize the serialization of this record. Since we know structurally what this entity looks like, we can create a rigid and streamlined serializer, which should improve overall performance. Therefore, we first define a PersonSerializationContext derived from JsonSerialzerContext.

[JsonSourceGenerationOptions(
    WriteIndented = true,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
[JsonSerializable(typeof(Person))]
public partial class PersonSerializationContext 
    : JsonSerializerContext {}

Essential elements of this definition include:

The partial keyword. The source generator will create the implementation of our class for us. The JsonSourceGenerationOptions attribute allows us to customize serialization with the correct casing, null handling, and much more. Don’t forget this if you have specific serialization needs. The JsonSerializable attribute for non-standard types during serialization. Each attribute of this kind will produce a JsonTypeInfo property on our context class.

Cool, let’s see how we can use our new PersonSerializationContext.

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

var person = new Person("Khalid", Friend: new("Maarten"));

var json =
    JsonSerializer.Serialize(
        person,
        PersonSerializationContext.Default.Person);

Console.WriteLine(json);

Running our application, we see the desired output. You’ll note that the result uses camel casing and that serialization did not output null values.

{
  "name": "Khalid",
  "isCool": true,
  "friend": {
    "name": "Maarten",
    "isCool": true
  }
}

So, how do you take advantage of your new PersonSerializationContext in an ASP.NET Core application? Well, it’s pretty straightforward.

Inside of an existing Minimal APIs endpoint, you’ll need to use the Results.Json method and pass it your generated Options found on the Default property.

using System.Text.Json.Serialization;

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

app.MapGet("/", () => "Hello World!");

app.MapGet("person", () => 
    Results.Json(
        new Person("Khalid", Friend: new("Maarten")), 
        PersonSerializationContext.Default.Options));

app.Run();

[JsonSourceGenerationOptions(
    WriteIndented = true,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
[JsonSerializable(typeof(Person))]
public partial class PersonSerializationContext 
    : JsonSerializerContext {}

public record Person(
    string Name,
    bool IsCool = true,
    Person? Friend = null
);

Running the ASP.NET Core application and hitting the endpoint produces the expected results, the same as we saw before in our console application.

// 20230210114342
// http://localhost:5115/person

{
  "name": "Khalid",
  "isCool": true,
  "friend": {
    "name": "Maarten",
    "isCool": true
  }
}

Conclusion

While hearing the phrase “source generators” might be scary at first, this optimization can improve your APIs’ performance with minimal effort. A few lines of code and some refactoring, and you’re off to the races.

If you’re going to use this technique, I recommend finding your application’s hottest paths and starting there. Then measure to see what kind of serialization overhead you’ve reduced.

As always, thanks for reading and sharing my posts with your colleagues. If you have any questions, please feel free to reach out.

Combining 11ty Static Site Generator with ASP.NET Core

Tue, 21 Feb 2023 00:00:00 +0000

I love many things about static site generators, but I mainly enjoy the challenge of building a fast user experience, given development time constraints. The constraints force me to be mindful of every new feature I add, the content I want to present, and the resources I use to accomplish all my goals. I believe that most, if not all, experiences on the web could benefit from some element of static site generation. While that may or may not be true, I believe in the inverse statement. Some static sites could benefit from a dynamic backend to provide unique and personalized experiences.

This post will explore adding 11ty, one of my favorite static site generator tools, to an ASP.NET Core application. We’ll see how this approach will allow us to build out static content while taking advantage of a dynamic and programmable hosting platform. Let’s get started.

Setting up an ASP.NET Core Web Project for 11ty

Let’s start with an ASP.NET Core Empty template, a barebones solution. We’ll be adding a few files and folders. First, let’s create a new site folder. This directory will hold all our static content that 11ty will process into static files.

The next step is creating a package.json file to manage our NPM packages. Finally, we’ll create a build script to process our static content. Here are the contents of /site/package.json.

{
  "name": "site",
  "private": true,
  "scripts": {
    "build": "node node_modules/.bin/eleventy"
  },
  "devDependencies": {
    "@11ty/eleventy": "^2.0.0-beta.3"
  }
}

From here, we can run npm install to install all the development dependencies. Feel free to add any other NPM packages for your static site. 11ty has a lot of great options too, so I imagine many folks will.

The next step is to add an eleventy.config.js file, which will help the 11ty process copy assets to our destination of wwwroot.

module.exports = function (eleventyConfig) {
    // copy images, css, and js from /assets
    eleventyConfig.addPassthroughCopy("./assets")
    return {
        dir: {
            passthroughFileCopy: true,
            // write to aspnet.core output directory
            output: "../wwwroot"
        }
    }
}

If you’re checking this project into source control, as you should, you may want to ignore the contents of wwwroot as they are artifacts of the build process and will likely be changing regularly.

Next, let’s add some content and templates for 11ty to process. First, create a new folder under site called _includes. Once you’ve made the folder, add the following layout.html file.


<!DOCTYPE html>
<html lang="en">
<head>
    <title>{{ title }}</title>
    <meta name="Description" content="{{ description }}" />
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <link rel="stylesheet" type="text/css" href="/assets/styles.css" />
</head>
<body>
<div class="content">{{ content }}</div>
<script src="/assets/script.js"></script>
</body>
</html>

Next, create an assets folder under site and add two files, script.js and styles.css. We’ve referenced these files in the layout, but we need some content. Here is the content for our JavaScript file. The stylesheet content can be empty for now.

;(function () {
    console.log("Hello there!")

    fetch('/api/current-time')
        .then((response) => response.json())
        .then((data) => {
            const el =document.getElementById('target');
            el.innerText =`the current date time is ${data.datetime}`; 
        });
})()

Spoiler, we’ll be implementing an ASP.NET Core API endpoint and calling it from our static files.

Finally, let’s add an index.md file. 11ty allows you to write your content in multiple templating languages, with my favorite being plain-old markdown.


---
title: "Hello 11ty"
layout: layout.html
description: Hosting 11ty on ASP.NET Core
---

# This Is Eleventy Served from ASP.NET Core

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

<h1 id="target">Loading...</h1>

Let’s get back to the world of .NET. The following section will set up our build process and the ASP.NET Core pipeline.

Setting Up ASP.NET Core to build 11ty

First, we need MSBuild to execute our NPM build script. That’s as straightforward as adding a Target to the .csrpoj file.

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

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

    <ItemGroup>
      <Folder Include="wwwroot" />
    </ItemGroup>

    <Target Name="11ty" BeforeTargets="Build">
        <Exec Command="npm install &amp;&amp; npm run build" WorkingDirectory="site" />
    </Target>

</Project>

It’s important to set the WorkingDirectory attribute to site, or else NPM will not find the script.

The next phase in our process is to configure our ASP.NET Core pipeline. We only need two pieces of middleware: DefaultFilesMiddleware and StaticFilesMiddleware. We’ll also take this opportunity to add our ASP.NET Core Minimal API endpoint.

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

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

app.MapGet("/api/current-time", () => new
{
    datetime = DateTime.Now
});

app.Run();

And that’s it! You now have a working 11ty and ASP.NET Core web project. I’ve uploaded it to my GitHub repository if you’d like a quicker starting point.**

As always, thanks for reading, and I hope this helps you. If you enjoyed this post, please share it with friends and colleagues.

Generating Bogus HTTP Endpoints with ASP.NET Core Minimal APIs

Tue, 14 Feb 2023 00:00:00 +0000

As a developer advocate, I find myself writing a lot of demos for folks around .NET and, specifically, the ASP.NET Core parts of the stack. Unfortunately, writing repetitive boilerplate can make me feel like Jack Torrence from The Shining movie: “All work and no play makes Khalid a dull boy.” Nobody likes the drudgery of repeating yourself, nobody! So, given my situation, I thought I’d chase this problem down in a maze with a metaphorical axe. So, what am I trying to accomplish?

What if I could take an existing C# model and build a low-ceremony set of test endpoints that follow standard HTTP semantics, and how would I accomplish that?

In this article, you’ll see how I built a single registration for test endpoints that you can use to prototype UIs quickly for frameworks like React, Blazor, Angular, or vanilla JavaScript. Let’s get started.

The Basics of an HTTP API

For folks unfamiliar with building an HTTP API, the HTTP semantics are essential to the implementation on the server. Elements of an HTTP request include the method, headers, path, query-string values, and the optional payload. Without all these elements, your HTTP API limits how and what your user can send to your endpoint.

On the flip side, you have the HTTP Request, which has headers, payload, and status code elements. The server uses these values to tell a client what occurred on the server via a status code and what the client can expect regarding the type of payload.

In addition to HTTP semantics, I typically center the creation of HTTP APIs around a “resource”. A resource is a logical entity that a user reads and writes through requests and receives in response payloads. In my experience, an API resource can be something like a Person, Quotes, and so on.

I’ve found that building my HTTP APIs around HTTP semantics and resources makes the process of reasoning and maintaining a project simpler in the long run.

The ASP.NET Core Registration

We’ll start with the user experience I’m aiming for and then look at how to implement the code behind the endpoint registration. I aim to have a low-ceremony registration to add essential create, read, update, and delete endpoints. The endpoints will also adhere to standard HTTP semantics. Additionally, I want persistence between requests, so the user can create or update a new resource and then retrieve it using the identity. First, let’s look at the Program.cs.

using BogusEndpoints;

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.MapAutoBogusEndpoint<Person>("/people", rules =>
{
    rules.RuleFor(p => p.Id, f => f.IndexGlobal + 1);
    rules.RuleFor(p => p.FullName, f => f.Name.FullName());
});

app.Run();

public record Person(int Id, string FullName)
{
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
    public Dog Dog { get; set; }
}

public record Dog(string Name);

You’ll notice the call to MapAutoBogusEndpoint allows the user to set a root path and the ability to configure the kind of data for the resource. Any property the user does not set will get random data based on the property type. For example, let’s make an HTTP call to the Index endpoint to retrieve a list of Person resources, limiting the result to

GET http://localhost:5208/people?pageSize=1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Thu, 02 Feb 2023 16:20:23 GMT
Server: Kestrel
Transfer-Encoding: chunked

{
  "results": [
    {
      "id": 1,
      "fullName": "Ofelia Vandervort",
      "createdAt": "2023-02-02T01:32:03.1170216-05:00",
      "dog": {
        "name": "Toys & Health"
      }
    }
  ],
  "page": 1,
  "pageSize": 1,
  "totalItemCount": 1000
}

That’s pretty cool, right?! Other calls like creating, updating, and deleting also work.

PUT http://localhost:5208/people/1
Content-Type: application/json

{
  "id": 1,
  "fullName": "Khalid Abuhakmeh",
  "createdAt": "2023-02-02T01:32:03.1170216-05:00",
  "dog": {
    "name": "Toys & Health"
  }
}
###

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Thu, 02 Feb 2023 16:28:34 GMT
Server: Kestrel
Transfer-Encoding: chunked

{
  "id": 1,
  "fullName": "Khalid Abuhakmeh",
  "createdAt": "2023-02-02T01:32:03.1170216-05:00",
  "dog": {
    "name": "Toys & Health"
  }
}

I make the best effort to assign the identifiers if an identifier needs to be incremented or generated. That said, in most cases, an HTTP API will expect that the user passes most data representing the state.

So how is this all done?

Generating Boilerplate Prototype Endpoints

I accomplish most of the work using the NuGet library AutoBogus. The configuration action allows you to configure each property accordingly when registering the endpoint. I’ll paste most of the code here.

using AutoBogus;
using Microsoft.AspNetCore.Mvc;
using X.PagedList;

namespace BogusEndpoints;

public static class BogusEndpointsExtensions
{
    public static RouteGroupBuilder MapAutoBogusEndpoint<TResource>(
        this WebApplication app,
        PathString prefix,
        Action<AutoFaker<TResource>>? builder = null
    ) where TResource : class
    {
        var group = app.MapGroup(prefix)
            .WithGroupName($"{typeof(TResource).FullName}_Bogus");

        var faker = new AutoFaker<TResource>();
        builder?.Invoke(faker);

        // generate a working collection
        // will allocate objects in memory
        var db = faker.Generate(1000);

        // INDEX
        group.MapGet("", (int? pageSize, int? page) =>
            {
                var result = db
                    .ToPagedList(
                        page.GetValueOrDefault(1),
                        pageSize.GetValueOrDefault(10));

                return new
                {
                    results = result,
                    page = result.PageNumber,
                    pageSize = result.PageSize,
                    totalItemCount = result.TotalItemCount
                };
            })
        .WithName($"{typeof(TResource).FullName}_Bogus+List");

        // SHOW
        group.MapGet("{id}", (string id) =>
        {
            var result = db.FirstOrDefault(t => FindById(t, id));
            return result != null ? Results.Ok(result) : Results.NotFound();
        })
        .WithName($"{typeof(TResource).FullName}_Bogus+Show");

        // POST
        group.MapPost("", (TResource item) =>
        {
            try
            {
                dynamic generated = faker.Generate(1)[0];
                SetId(item, generated.Id);
                db.Add(item);
                return Results.CreatedAtRoute(
                    $"{typeof(TResource).FullName}_Bogus+Show",
                    new { id = generated.Id },
                    item
                );
            }
            catch
            {
                return Results.Ok(item);
            }
        }).WithName($"{typeof(TResource).FullName}_Bogus+Create");

        // PUT
        group.MapPut("{id}", (string id, [FromBody] TResource item) =>
        {
            var index = db.FindIndex(t => FindById(t, id));
            if (index < 0) return Results.NotFound();
            SetId(id, item);
            db[index] = item;
            return Results.Ok(item);
        }).WithName($"{typeof(TResource).FullName}_Bogus+Update");

        // DELETE
        group.MapDelete("{id}", (string id) =>
        {
            db.RemoveAll(t => FindById(t, id));
            return Results.Accepted();
        })
        .WithName($"{typeof(TResource).FullName}_Bogus+Delete");
        
        return group;
    }

    private static bool FindById<TResource>(TResource target, object? id)
    {
        if (id is null)
            return false;

        var type = typeof(TResource);
        var identifier = type
            .GetProperties()
            .FirstOrDefault(p => p.Name == "Id");

        if (identifier == null)
            return false;

        object? converted = Convert.ChangeType(id, identifier.PropertyType);
        if (converted == null) return false;
        var value = identifier.GetValue(target);
        var result = converted.Equals(value);
        return result;
    }
    
    private static void SetId<TResource>(TResource target, object? id)
    {
        if (id is null)
            return;

        var type = typeof(TResource);
        var identifier = type
            .GetProperties()
            .FirstOrDefault(p => p.Name == "Id");

        if (identifier == null)
            return;

        object? converted = Convert.ChangeType(id, identifier.PropertyType);
        if (converted == null) return;
        identifier.SetValue(target, converted);
    }
}

All you need to do is create your resource types, such as Person, and you’ll get all the necessary machinery for an HTTP API. But there’s still something missing. What about validation results?

Adding Validation to Bogus Endpoints

I made a calculated effort to return the RouteGroupBuilder from each registration call, allowing you to add any endpoint filter to a group. Exposing this object instance makes it trivial to add FluentValidation as an endpoint filter.

using BogusEndpoints;
using FluentValidation;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddValidatorsFromAssemblyContaining<Program>();

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.MapAutoBogusEndpoint<Person>("/people", rules =>
{
    rules.RuleFor(p => p.Id, f => f.IndexGlobal + 1);
    rules.RuleFor(p => p.FullName, f => f.Name.FullName());
})
.AddEndpointFilter<PersonValidationFilter>();

app.Run();

public record Person(int Id, string FullName)
{
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
    public Dog Dog { get; set; }
}

public record Dog(string Name);

We tie the validator specifically to the resource of Person.

using FluentValidation;

public class PersonValidationFilter : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
    {
        var validator = context.HttpContext.RequestServices.GetRequiredService<PersonValidator>();
        foreach (var arg in context.Arguments)
        {
            if (arg is not Person person) continue;
            var result = await validator.ValidateAsync(person);
            if (result.IsValid) continue;
            var errors = result.Errors
                .GroupBy(e => e.PropertyName)
                .ToDictionary(
                    g => g.Key, 
                    g => g.Select(e => e.ErrorMessage).ToArray()
                );

            return Results.ValidationProblem(errors);
        }

        return await next(context);
    }
}

public class PersonValidator : AbstractValidator<Person>
{
    public PersonValidator()
    {
        RuleFor(m => m.FullName).NotEmpty();
    }
}

Any call to an endpoint not meeting your validation criteria will return an appropriate problem details response and status code.

POST http://localhost:5208/people

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Date: Thu, 02 Feb 2023 16:56:57 GMT
Server: Kestrel
Transfer-Encoding: chunked

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "FullName": [
      "'Full Name' must not be empty."
    ]
  }
}

Cool!

Other Ideas around Bogus Endpoints

This current implementation relies on runtime generation, which is ok for testing purposes, but there are a lot of potential pitfalls, primarily around identifiers. Using source code generators, you could make the endpoints rely less on reflection and more on the design-time types of the resource models. In addition, the use of source generators could lead to fewer edge case bugs.

.NET Community member João Antunes has an excellent blog post detailing registering Minimal API endpoints using source code generators. I could see someone adapting both our ideas into something useful for the community at large.

Conclusion

If you’ve ever found yourself in a situation where you needed some test endpoints to match your models but were more focused on the UI/UX rather than the implementation, this solution might be for you. The approach in this post could use some optimizations and edge case handling, but I’ll leave it up to you to work through those.

As always, thanks for reading, and I hope you enjoyed this post. If you did, please feel to share it with friends and colleagues.

How to use Entity Framework Core in ASP.NET Core

Tue, 07 Feb 2023 00:00:00 +0000

Moving from one ecosystem to another can be challenging, especially when unfamiliar with the technology stack and available tools. So I wrote this post for anyone coming to ASP.NET Core from another ecosystem or .NET developers who might be dabbling with web development for the first time. Knowing where all the bits and bobs are in a new environment can be overwhelming, and I’m here to help.

As you read through the post, we’ll create a new ASP.NET Core project, integrate a data access library called Entity Framework Core 7, and discuss the steps you need to take toward a straightforward solution. Like all solutions, I developed this guidance from my first-hand experience.

Please do so if you’d like to experiment with your choices at any point in this tutorial. This guide is a jumping-off point so you can succeed. This blog post assumes you have .NET installed and some kind of editor or tooling. I recommend JetBrains Rider but this tutorial should work with Visual Studio and Visual Studio Code.

Let’s go ahead and get started.

Creating a New ASP.NET Core Web Project

Before we get started, you’ll need to create a new ASP.NET Core solution. Creating a new .NET solution can typically be done in one of two ways: Command-line tooling or through your favorite IDE (I prefer JetBrains Rider).

For this guide, I’ll show you how to create a new Razor Pages web project using the command line. First, in a new terminal, type the following command.

dotnet new webapp -o WebApplication

The command will create a web project ready for development. Note: This template is available in most IDEs and will create an additional solution file with your project in a nested folder when selected. A solution is a typical structure for most .NET applications, as you may have more than one project per solution.

You’re ready to start adding some of our necessary dependencies from here.

Tools and NuGet Dependencies

We’ll start by installing a tool manifest in our solution directory. The tool manifest keeps track of all command-line tooling installed for the current solution, and many of EF Core’s management feature set exists in the dotnet-ef tool.

Type the following command from the root folder of your solution.

dotnet new tool-manifest

The command will create a .config folder with a dotnet-tool.json file. It’s not necessary to look at it. Just know it’s a manifest of all the tools installed for your local development needs.

Next, you’ll need to install the EF Core 7 tooling with the following command.

dotnet tool install dotnet-ef

Now, let’s move on to installing our EF Core 7 dependencies.

You’ll need to install two specific packages in your web application project.

The first package is your EF Core database provider package, and you can choose from Microsoft SQL Server, PostgreSQL, MySQL, or other providers. In this case, I decided to use SQLite because it’s file-based and gets the point across.

The second is EF Core’s Design package, which allows you to generate database migrations. These migrations help keep your database schema compatible with your C# models.

Here’s my .csproj file.

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

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

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

</Project>

NuGet will install all other EF Core packages transitively from these two packages. Our web application is now ready for some code.

Designing a Database with EF Core and C#

EF Core supports multiple design philosophies, but the one I’m fond of is Code-First. Code first lets you design C# models, which EF Core will translate into a database schema. Create a folder at the root of your web application named “Models” and create a new file called “Database.cs”. Add the following content to the file. This code contains our first table and our DbContext implementation.

Adjust the namespace according to your project’s namespace if you’d like.

using Microsoft.EntityFrameworkCore;

namespace WebApplication4.Models;

public class Database : DbContext
{
    public Database(DbContextOptions<Database> options)
        : base(options)
    {}
    
    public DbSet<Person> People => Set<Person>();
}

public class Person
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
}

This code will create a new “People” table with the columns of Id, Name, and CreatedAt. You’ll also notice that our Database class takes a parameter of DbContextOptions<Database>; this is how you configure our database settings. The following section will show you how to set up values like connection strings and database providers.

Services Collection and Configuring Our DbContext

You’ll need to register the type with ASP.NET Core’s services collection to take advantage of your newly created’ Database’ class. The registration process allows you to set up everything just the way you want, with options like database provider, logging, interceptors, and more. For this guide, let’s keep it simple. Add the following lines of code in your Program.cs file.

builder.Services.AddDbContext<Database>(options => {
    var config = builder.Configuration;
    var connectionString = config.GetConnectionString("database");
    
    options.UseSqlite(connectionString);
});

You’ll notice that you’re using the configuration to get a connection string. So what does the configuration file look like? In your appSettings.Development.json file, you’ll have the following.

{
  "DetailedErrors": true,
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "ConnectionStrings": {
    "database": "Data Source=database.db"
  }
}

Here you can add your connection strings and read them in code. I recommend storing connection strings in environment variables or cloud-specific settings providers when running your application in production settings. Do not store sensitive information in source control under any circumstance.

The next step is to create our database instance using database migrations and EF Core tooling.

EF Core Migrations and Databases

We have most of the working parts of our application set in place, but we still haven’t touched a database. That changes now. You’ll be creating your first migration from the command line. From the root directory of your solution, type the following command:

dotnet ef migrations add "Initial" --project WebApplication4

Be sure you change the --project argument to match your project’s name. You can also exclude this argument by executing the command from the web application’s root directory instead of the solution directory.

When executed correctly, you should see a new “Migrations” folder in your web application project and a timestamped migration named “Initial”. Opening the file will show the C# to Database schema translation that EF Core performed on your behalf.

using System;
using Microsoft.EntityFrameworkCore.Migrations;

#nullable disable

namespace WebApplication4.Migrations
{
    /// <inheritdoc />
    public partial class Initial : Migration
    {
        /// <inheritdoc />
        protected override void Up(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.CreateTable(
                name: "People",
                columns: table => new
                {
                    Id = table.Column<int>(type: "INTEGER", nullable: false)
                        .Annotation("Sqlite:Autoincrement", true),
                    Name = table.Column<string>(type: "TEXT", nullable: false),
                    CreatedAt = table.Column<DateTime>(type: "TEXT", nullable: false)
                },
                constraints: table =>
                {
                    table.PrimaryKey("PK_People", x => x.Id);
                });
        }

        /// <inheritdoc />
        protected override void Down(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.DropTable(
                name: "People");
        }
    }
}

Let’s apply this to a database. Running the following command will use the connection string in your app settings. Be sure it is a local developer instance of a database.

dotnet ef database update --project WebApplication4

If you’re using SQLite, you should now see a database.db or file with the same name as is found in your connection string. If you’re using another database provider, you can now see the EF Core-created tables in your database instance.

For production purposes, I recommend you run migrations outside the running application. A lot can go wrong with database migration, and you don’t want a lousy migration to stop your application from running. That said, you can run migrations from your application’s startup for local development purposes. As an optional step, you can add the following migration code to your “Program.cs” file, below the call to var app = builder.Build();.

if (app.Environment.IsDevelopment())
{
    // migrate database, only during development
    using var scope = app.Services.CreateScope();
    var db = scope.ServiceProvider.GetRequiredService<Database>();
    await db.Database.MigrateAsync();
}

Let’s start using our DbContext and database instance.

Using a DbContext in a Razor Page

Our goal in this section is to use our Database class to read and write to our People table. If you’re following along, you should have an Index.cshtml along with an Index.cshtml.cs file under a Pages directory. We’ll be modifying the Index.cshtml.cs type to pass in a Database parameter to the constructor. So let’s start with the most straightforward modification of constructor injection.

using Microsoft.AspNetCore.Mvc.RazorPages;
using WebApplication4.Models;

namespace WebApplication4.Pages;

public class IndexModel : PageModel
{
    private readonly ILogger<IndexModel> _logger;
    private readonly Database _database;

    public Person? Person { get; set; }
    
    public IndexModel(ILogger<IndexModel> logger, Database database)
    {
        _logger = logger;
        _database = database;
    }

    public void OnGet()
    {
        Person = _database
            .People
            .OrderByDescending(p => p.CreatedAt)
            .FirstOrDefault();
    }
}

The above code takes in a Database instance and sets it to a private member. Then, on the page’s response to a GET HTTP request, the OnGet method will query for the latest person in the People table. You can set the result to the Person property. You’ll use this later when building the view.

Let’s also take a look at parameter injection. You’ll need to add an OnPost method and a new bindable property. The new method will also take a Database instance as an argument, but you’ll need a FromServices attribute to tell ASP.NET Core to resolve this value from the services collection. Let’s look at the updated file.

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using WebApplication4.Models;

namespace WebApplication4.Pages;

public class IndexModel : PageModel
{
    private readonly ILogger<IndexModel> _logger;
    private readonly Database _database;

    public Person? Person { get; set; }
    
    public IndexModel(ILogger<IndexModel> logger, Database database)
    {
        _logger = logger;
        _database = database;
    }

    public void OnGet()
    {
        Person = _database
            .People
            .OrderByDescending(p => p.CreatedAt)
            .FirstOrDefault();
    }

    [BindProperty, Required, DisplayName("Person's Name")]
    public string? Name { get; set; }
    
    public async Task<IActionResult> OnPost([FromServices] Database db)
    {
        if (ModelState.IsValid)
        {
            Person person = new() { Name = Name! };
            db.People.Add(person);
            await db.SaveChangesAsync();
            return RedirectToPage();
        }

        // show validation messages
        return Page();
    }
}

Before continuing to the Razor view, let’s discuss the OnPost implementation. It’s a critical practice when developing applications to adhere to a GET-POST-Redirect pattern. The pattern keeps your users from accidentally refreshing the page and submitting multiple requests for the same action. The method uses a return value of IActionResult so you can return numerous interface implementations, including RedirectToPage and Page.

In addition to handling a form post, we need properties to bind to our ASP.NET Core Razor Pages form. In this case, we only have one property of Name. In Razor Pages, the page model is where you add all your form fields, but you can also certainly move them into individual models. If you’re using ASP.NET Core MVC, you might apply a “View Model” approach, which will also work here.

Let’s write some Razor!

Creating an ASP.NET Core Razor Form

The culmination of our work has led you to the Razor view, where you’ll be adding a form to add new Person instances to your database. First, let’s look at the view and break down its parts.

@page
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

@if (Model.Person is {} person)
{
    <div class="alert alert-primary" role="alert">
        Hello <span class="alert-link">@person.Name</span>! 
        Nice to meet you.
    </div>
}

<form asp-page="Index" method="post">
    <div asp-validation-summary="All"></div>
    <div class="input-group">
        <div class="form-group mb-2">
            <label asp-for="Name"></label>
            <input class="form-control" asp-for="Name">
            <span asp-validation-for="Name" class="invalid-feedback"></span>
        </div>
    </div>
    <button class="btn btn-primary" type="submit">Save Person</button>
</form>

The form element uses TagHelpers to use the IndexModel properties to build our form. We are also telling the form to POST the form to our page handler of OnPost using the asp-page attribute. Finally, there’s a submit button.

Above our form, we’ve also added usage of our Person property. If it is not null, we’ll show an alert from the last entry in the database.

Running your application now, you’ll be able to save and read data in an ASP.NET Core application using Entity Framework Core. Congratulations!

Conclusion

Getting a working ASP.NET Core application using EF Core can seem tedious, but in most cases, the “plumbing” work is done once upfront and never touched again.

You’ll spend most of your time adding a C# class to your DbContext, adding new database migrations, and then plumbing that entity to a Razor page. That’s the positive side of this approach; adding new functionality is boring with few surprises. When building and maintaining applications, boring is a good thing.

While I certainly didn’t go into every possible detail, this quick-start guide should have you up in no time. If you have any specific questions or have issues, please contact me at @khalidabuhakmeh@mastodon.social or use the contact form on the blog.

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

Register MAUI Views and ViewModels with Scrutor

Tue, 31 Jan 2023 00:00:00 +0000

As a developer advocate at JetBrains, I find myself exploring technologies in nooks and crannies of the ecosystem previously out of reach. As a lifelong proponent of the web, mobile development has always been on my list to explore, but I rarely found the time to do so. One of the latest technologies I am dabbling with is Multi-platform App UI, more commonly referred to as MAUI.

In this post, I’ll show you how to use the packages CommunityToolkit.Mvvm and Scrutor to quickly register your XAML views and the corresponding ViewModels for a more convenient approach.

CommunityToolkit.Mvvm and the MVVM pattern

The Model-View-View-Model pattern, also referred to as MVVM, is an approach that separates the logic of your views from the language of the View. In the case of MAUI, that view language is typically XAML. Utilizing the pattern leads to a few positive side effects:

Your ViewModels are much more straightforward to test, with the bulk of your logic exposed through properties and commands.
Your Views are simpler, binding to properties and commands rather than directly to members on the specific ContentPage.
In MAUI, both ContentPage and ViewModels can support dependency injection arguments, allowing for the composition of app functionality.

I’m sure there are other benefits to using the MVVM pattern, but these immediately spring to mind when compared to the alternative of dumping all logic in a ContentPage directly.

The CommunityToolkit.Mvvm package includes helpers to make adopting the MVVM pattern more straightforward and performant. CommunityToolkit.Mvvm uses source generators to generate the tedious parts of building MAUI apps, most notably the implementation of INotifyPropertyChanged and ICommand instances.

Let’s start with a simple update of the default MAUI template. Next, we’ll add a new MainPageViewModel and move most of the app’s logic from the MainPage.xaml.cs file to our new class.

Note: This sample is from a blog post by Mark Timmings. Check it out here.

using System.Diagnostics;
using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;

namespace MyFirstMauiApp.ViewModels;

public partial class MainPageViewModel : ObservableObject
{
    [ObservableProperty] int count;
    [ObservableProperty] private string text;
    [ObservableProperty]
    [NotifyCanExecuteChangedFor(nameof(IncrementCountCommand))]
    bool canIncrement;
    
    bool CanExecuteIncrement() => canIncrement;

    [RelayCommand(CanExecute = nameof(CanExecuteIncrement))]
    void IncrementCount()
    {
        Count++;
        Text = Count == 1 
            ? $"Clicked {count} time" 
            : $"Clicked {count} times";
        
        SemanticScreenReader.Announce(Text);
    }
    
    partial void OnCanIncrementChanged(bool value)
    {
        Debug.WriteLine("OnCanIncrementChanged called");
    } 
}

Next, we’ll update our MainPage.xaml.cs code.

using MyFirstMauiApp.ViewModels;

namespace MyFirstMauiApp;

public partial class MainPage : ContentPage
{
    public MainPage(MainPageViewModel model)
    {
        InitializeComponent();
        BindingContext = model;
    }
}

We’ll also need to update the XAML to take advantage of our new MainPageViewModel class.

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:viewModels="clr-namespace:MyFirstMauiApp.ViewModels"
             x:Class="MyFirstMauiApp.MainPage"
             x:DataType="viewModels:MainPageViewModel">

    <ScrollView>
        <VerticalStackLayout
            Spacing="25"
            Padding="30,0"
            VerticalOptions="Center">

            <Image
                Source="dotnet_bot.png"
                SemanticProperties.Description="Cute dot net bot waving hi to you!"
                HeightRequest="200"
                HorizontalOptions="Center" />

            <Label
                Text="Hello, World!"
                SemanticProperties.HeadingLevel="Level1"
                FontSize="32"
                HorizontalOptions="Center" />

            <Label
                Text="{Binding Text}"
                SemanticProperties.HeadingLevel="Level2"
                SemanticProperties.Description="Welcome to dot net Multi platform App U I"
                FontSize="18"
                HorizontalOptions="Center" />
            
            <CheckBox
                IsChecked="{Binding CanIncrement}" />

            <Button
                x:Name="CounterBtn"
                Text="{Binding Count, StringFormat='Click me ({0})'}"
                SemanticProperties.Hint="Counts the number of times you click"
                Command="{Binding IncrementCountCommand}"
                HorizontalOptions="Center" />

        </VerticalStackLayout>
    </ScrollView>

</ContentPage>

If you were to run this application now, you’d get the following MissingMethodException exception.

Unhandled Exception:
System.MissingMethodException: No parameterless constructor defined for type 'MyFirstMauiApp.MainPage'.
   at ObjCRuntime.Runtime.ThrowException(IntPtr gchandle)
   at UIKit.UIApplication.UIApplicationMain(Int32 argc, String[] argv, IntPtr principalClassName, IntPtr delegateClassName)
   at UIKit.UIApplication.Main(String[] args, Type principalClass, Type delegateClass)
   at MyFirstMauiApp.Program.Main(String[] args) in /Users/khalidabuhakmeh/RiderProjects/MyFirstMauiApp/MyFirstMauiApp/Platforms/iOS/Program.cs:line 13
2023-01-17 14:15:13.288973-0500 MyFirstMauiApp[40948:8367336] Unhandled managed exception: No parameterless constructor defined for type 'MyFirstMauiApp.MainPage'. (System.MissingMethodException)

MAUI doesn’t know how to instantiate any classes mentioned in this sample yet. Let’s fix that.

Using Scrutor to Register Views and ViewModels

In the context of an MVVM-powered MAUI app, there are two essential elements: The View and the ViewModel. These concepts are represented by the types ContentPage and ObservableObject.

Scrutor can scan for those types and register the instances as themselves with singleton lifetimes.

using Microsoft.Extensions.Logging;
using CommunityToolkit.Mvvm.ComponentModel;

namespace MyFirstMauiApp;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();

        // The important part
        builder.Services.Scan(s => s
            .FromAssemblyOf<App>()
            .AddClasses(f => f.AssignableToAny(
                    typeof(ContentPage), 
                    typeof(ObservableObject))
                )
                .AsSelf()
                .WithSingletonLifetime()
        );
        // end of important part
        
        builder
            .UseMauiApp<App>().ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            });
        
#if DEBUG
        builder.Logging.AddDebug();
#endif
        return builder.Build();
    }
}

When we start the application, we should see our MVVM-powered MAUI application.

The advantage to using Scrutor in this instance is that we can continue to expand our application’s functionality with Views and ViewModels. They should all be part of the services collection and work with dependency injection.

I’ve chosen to register all elements as singelton since, in most cases, a mobile application is limited to a single user, and having types registered as scoped or transient is a waste of resources.

I hope you enjoyed this blog post, and please let me know what kind of MAUI apps you’re building. As this is still a burgeoning community and technology, there’s still a lot to learn.

As always, thanks for reading and sharing my posts.

Programming SVGs with C#

Tue, 24 Jan 2023 00:00:00 +0000

One of my hobbies to create graphics using my favorite photo editing tool, Pixelmator Pro. It’s a fantastic tool; anyone on macOS should add it to their Applications folder. One of the benefits of using a photo-editing tool is the ability to create Scalable Vector Graphics (SVG). SVGs are an XML-based format that allows you to edit and manipulate the content of an image with a text editor if you choose, but I wouldn’t recommend it. Photo-editing tools are much better at creating graphics, but SVGs provide a way to extend and repurpose existing assets.

In this post, I’ll show you how you can take an existing SVG and create a programmable visual asset with some C# code. Let’s get started.

What’s an SVG?

Scalable Vector Graphics is an XML-based markup language, not too dissimilar to HTML, allowing users to create two-dimensional based vector graphics. A standard format used across multiple image editors to create infinitely scalable assets is widely supported by major browser vendors. First, let’s look at an example SVG, which we’ll program later with C#.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Generated by Pixelmator Pro 3.2.3 -->
<svg width="1000" height="1000" viewBox="0 0 1000 1000" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
    <path id="Color-Fill" fill="#ff6900" stroke="none" d="M 0 0 L 1000 0 L 1000 1000 L 0 1000 Z"/>
    <g>
        <path id="Logo-Shape" fill="#020303" fill-rule="evenodd" stroke="none" d="M 832.5 500 C 832.5 316.365356 683.634644 167.5 500 167.5 C 316.365326 167.5 167.5 316.365356 167.5 500 C 167.5 683.634644 316.365326 832.5 500 832.5 C 683.634644 832.5 832.5 683.634644 832.5 500 Z"/>
        <text id="Beyond-The-Idea" xml:space="preserve" x="50%" y="50%" text-anchor="middle">
            <tspan id="Top" x="50%" y="493" font-family="JetBrains Mono" font-size="111.9625" fill="#ffffff" xml:space="preserve">BEYOND</tspan>
            <tspan id="Bottom" x="50%" y="604.2" font-family="JetBrains Mono" font-size="111.9625" fill="#ffffff" xml:space="preserve">THE IDEA</tspan>
        </text>
    </g>
</svg>

This SVG produces the following visual output.

An added benefit of being markup is you can typically target any element with styling or explicit color fills and strokes. The flexibility makes one asset infinitely configurable.

Neat, right?! So how do you take this XML and create a programmable image?

Hurndles to Programming SVGs

By the end of this section, we’ll have loaded an SVG into a .NET application’s memory, modified text elements of the SVG, and rendered the image to disk as a PNG. We’ll also create a wrapper class to make using your new SVG easier for other developers.

Before we start, let’s talk about caveats you’re likely to encounter. The code I’ll be showing can overcome these issues, while you’ll need to figure others out for your use case.

If you want to follow along, create a new console application and add the Svg NuGet package.

What about the fonts?

The first issue you’ll likely run into is fonts. SVGs are a markup language, and text elements reference fonts. Therefore, if you use a non-standard font (which is likely), you’re bound to run into rendering issues when you deploy your programmable SVG.

The Svg package has a static type called SvgFontManager which will let you load any font into the SVG rendering context.

In the case of this sample, let’s add a font, JetBrains Mono, to our assembly as an embedded resource, then load it into the font manager.

var assembly = Assembly.GetAssembly(typeof(PromotionalImage))!;
using var fontStream = assembly.GetManifestResourceStream("SvgFontEmbed.JetBrainsMono-Regular.ttf")!;
using var ms = new MemoryStream();
fontStream.CopyTo(ms);
// load font into font manager
SvgFontManager.PrivateFontDataList.Add(ms.ToArray());

The font name of JetBrains Mono is used in the SVG, as seen on the tspan elements.

<tspan id="Top" x="50%" y="493" font-family="JetBrains Mono" font-size="111.9625" fill="#ffffff" xml:space="preserve">BEYOND</tspan>

You can add as many or as few fonts as your SVG requires. But, of course, you can also forget to add any fonts you know will be on the destination host.

Text Centering

Another issue you may run into is the centering of text elements. While I mostly created the sample SVG in a photo editor, I manually modified the markup to adapt to variations in input. As a recommendation, you should change any numeric values for x or y to use percentage values, thus keeping the spirit of the original image intact.

Using HTML colors instead of RGB

If you want to use HTML-based colors, you can use the ColorTranslator class in System.Drawing namespace.

ColorTranslator.FromHtml("#840087")

The Hexadecimal color representation is more common among image-editing apps, developers, and designers. Go with the flow.

Back To Programming an SVG

I thought I’d start with some of the issues I ran into before jumping into a programmable SVG because you’ll likely have to tinker with your SVG template to get the results you’re looking to produce.

You’ll first want to add your SVG template and fonts into your console application or class library as embedded resources. Doing so will make sharing these images easier in the long run, as all assets will be part of your compiled artifact.

<ItemGroup>
  <None Remove="JetBrainsMono-Regular.ttf" />
  <EmbeddedResource Include="JetBrainsMono-Regular.ttf" />
  <None Remove="template.svg" />
  <EmbeddedResource Include="template.svg" />
</ItemGroup>

You’ll be able to access these resources using the following code.

static PromotionalImage()
{
    var assembly = Assembly.GetAssembly(typeof(PromotionalImage))!;
    using var fontStream = assembly.GetManifestResourceStream("SvgFontEmbed.JetBrainsMono-Regular.ttf")!;
    using var ms = new MemoryStream();
    fontStream.CopyTo(ms);
    // load font into font manager
    SvgFontManager.PrivateFontDataList.Add(ms.ToArray());

    using var svgStream = assembly.GetManifestResourceStream("SvgFontEmbed.template.svg")!;
    using var textReader = new StreamReader(svgStream);

    SvgXml = textReader.ReadToEnd();
}

Your next step is to look at your SVG and determine all the identifiers you want your users to modify, along with the types of each element. In the case of the example above, we’ll be converting the background color and the two text spans of Top and Bottom.

using System.Drawing;
using System.Reflection;
using Svg;

public static class PromotionalImage
{
    private static string SvgXml;
    
    static PromotionalImage()
    {
        var assembly = Assembly.GetAssembly(typeof(PromotionalImage))!;
        using var fontStream = assembly.GetManifestResourceStream("SvgFontEmbed.JetBrainsMono-Regular.ttf")!;
        using var ms = new MemoryStream();
        fontStream.CopyTo(ms);
        // load font into font manager
        SvgFontManager.PrivateFontDataList.Add(ms.ToArray());

        using var svgStream = assembly.GetManifestResourceStream("SvgFontEmbed.template.svg")!;
        using var textReader = new StreamReader(svgStream);

        SvgXml = textReader.ReadToEnd();
    }

    public static SvgDocument Create(string topText, string bottomText, string? bgColor = null)
    {
        var document = SvgDocument.FromSvg<SvgDocument>(SvgXml);

        var texts = document.Children.FindSvgElementsOf<SvgTextSpan>().ToList();
        texts.First(t => t.ID == "Top").Text = topText;
        texts.First(t => t.ID == "Bottom").Text = bottomText;
        
        if (bgColor is { })
        {
            var bg = document.Children.Where(x => x.ID == "Color-Fill")
                .Where(e => e is SvgPath)
                .Cast<SvgPath>()
                .First();

            bg.Fill = new SvgColourServer(ColorTranslator.FromHtml(bgColor));
        }

        return document;
    }
}

Let’s look at the steps in the Create method.

First, we create a new SVG document in memory. We want to do that to work with a fresh instance every time.
Second, we find the text spans in our SVG by their identifiers and set the new values set by the user.
Finally, we find the background of Color-Fill and set the color to the hexadecimal value passed in.

Let’s see how we can use this new class in code.

using System.Drawing.Imaging;

var image = PromotionalImage.Create("DROP", "THE DOT", "#840087");
image.Draw().Save("result.png", ImageFormat.Png);

The resulting image is a mutation of our original template.

Yes! You did it. You just programmed an SVG using C#.

Conclusion

With SVGs and .NET, you can procedurally generate an infinite amount of assets with minimal effort. The Svg library on NuGet supports many markup elements required to change any starting template dramatically. You could go so far as to add new paths, change colors, modify the text, switch fonts, or do whatever you wish. Embedding the resources into a class library would allow you to ship a generator via a NuGet package to use in various situations. The possibilities are limitless.

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

Khalid Abuhakmeh

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

The Anatomy of a SSE Endpoint

Implementing an IAsyncEnumerable Food Service

Subscribing to SSE using JavaScript

Generic C# Methods with Enum Constraints for .NET

Straight To The Implementation

Conclusion

Strongly-Typed Markdown for ASP.NET Core Content Apps

The Magnificent Markdown

The MarkdownObject and Parsing Files

MarkdownObject in a Razor Page

The Curious Case of .NET ConcurrentDictionary and Closures

What Are Closures?

ConcurrentDictionary.GetOrAdd and Closure Creation

ASP.NET Core and Chunking HTTP Cookies

Why You Would and Wouldn’t Use Cookies

Setting Cookies in ASP.NET Core

Conclusion

Vogen and Value Objects with C# and .NET

What is a Value Object?

What is Vogen?

Conclusion

Initialize ASP.NET Core TagHelpers with Shared Data

The TagHelper In Question

TagHelper Initializers

Conclusion

Writing a String Numeric Comparer with .NET 9

A List of Numbered Things

Writing a NumericOrderer with Spans

Conclusion

Great .NET Documentation with Astro, Starlight, and MarkdownSnippets

Directory Structure and Tools

Our .NET Code Samples

Our Starlight Documentation

Conclusion

Alpine.Js Polling ASP.NET Core APIs For Updates

The Strength of Alpine.js

ASP.NET Core and Alpine.Js

Conclusion

Building a Persistent Counter with Alpine.Js

Installing Alpine.js

Building an inline Counter with Alpine

Making the inline counter persistent

Persisting state in an Alpine Store

Conclusion

Dynamic Htmx Islands with ASP.NET Core

What is an Island?

The Island Plan

Creating an Island TagHelper

Response and Output Caching

Conclusion

Update HTML Elements with Htmx Triggers and ASP.NET Core

The Moving Parts

The User Service

Profile Endpoints

Htmx and Partial Views

Conclusion

Add EF Core Migrations to .NET Aspire Solutions

The Solution Structure

Entity Framework Core Design Time Factory

EF Core CLI Command

Conclusion

Htmx and Playwright Tests in C#

The Htmx Counter Application

Htmx Request Lifecycle Events

Playwright and Htmx Extensions

Intersperse Values for Enumerable Collections

Intersperse implementation in C#

Checked and Unchecked Arithmetic Operations in .NET

The code causing the overflow

Unchecked Arithmetic

The checked keyword

Project Setting for Checked Arithmetic

Conclusion

Confirmation Dialogs with Htmx and SweetAlert

The htmx:confirm event

Add SweetAlert to Htmx Confirmations

Conclusion

How To Pick The Right Constructor When Using ActivatorUtilities In .NET

The `checked` keyword

The `htmx:confirm` event

What is `datalist`?

What is the `range` Input?