RandomDev

Generic Type Construction With Static Virtual Interface Members

2022-12-12T05:00:00+00:00

This blog is one of The December 12th entries on the 2023 C# Advent Calendar. Thanks for having me again!

Typically for C# Advent I write about a new C# feature. And there are a lot of great new features this year in C# 12. My favorite is probably primary constructors because of the massive amount of boilerplate it replaces when writing classes that accept injected dependencies. I’m also super excited by the hidden performance optimizations found in collection expressions.

But, oddly, this year I’m going to talk about a new feature from last year. Generic math support was added in .NET 7 and is a great new feature by itself, but what’s even more interesting to me is how it was implemented. Under the hood, generic math support uses a new feature in C# 11 called static virtual interface members.

Static virtual interface members isn’t a purely C# 11 feature. Utilizing them requires .NET 7 or later because changes were also required in the .NET runtime. Since .NET 7 wasn’t a long-term support release I don’t think it’s gotten as much utilization as it deserves. But now .NET 8 is available and it is an LTS release, so I think it’s worth revisiting.

Today, I’d like to demonstrate a different use case for static virtual interface members: generic type construction.

The Backstory

Since .NET 2.0 we’ve had support for generics in C#. Generics are a great way to write code that can be reused across a variety of types. For example, the List<T> class is a generic type which can be used to store a list of any distinct type while maintaining strong type controls and avoiding boxing of value types (unlike its predecessor ArrayList).

Along with generics came the concept of generic type constraints. These allow you to specify that a generic type must be a particular type or implement a particular interface. Since the compiler then knows that the type will have certain members, it can allow you to use those members from within the generic code.

One such constraint is the new() constraint. This requires that the type have a public parameterless constructor. With this constraint, you can use the new keyword to construct an instance of the type.

Apologies in advance for the contrived example, but I promise scenarios like this do come up in real development.

public abstract class Vehicle
{
    public string Model { get; set; }
}

public class Car : Vehicle
{
}

public class Motorcycle : Vehicle
{
}

// This method may be called with either Car or Motorcycle to create
// a concrete instance of an Vehicle.
public IEnumerable<T> Create<T>(IEnumerable<string> models)
    where T : Vehicle, new()
{
    foreach (var model in models)
    {
        // Constructs T, either a Car or Motorcycle, depending on the
        // generic type parameter used when calling Create<T>
        yield return new T() { Model = model };
    }
}

The Problem

This works great for simple cases, but what if we wanted to accept parameters on the constructor? Perhaps we want to make the Model property read only and require it to be passed during construction.

Note: I’m using C# 12 primary constructors here!

public abstract class Vehicle(string model)
{
    public string Model { get; } = model;
}

public class Car(string model) : Vehicle(model)
{
}

public class Motorcycle(string model) : Vehicle(model)
{
}

// This method may be called with either Car or Motorcycle to create
// a concrete instance of an Vehicle.
public IEnumerable<T> Create<T>(IEnumerable<string> models)
    where T : Vehicle, new(string) // THIS IS NOT ALLOWED, COMPILER ERROR
{
    foreach (var model in models)
    {
        yield return new T(model); // THEREFORE, THIS IS NOT ALLOWED EITHER
    }
}

Enter Static Virtual Interface Members

This is where static virtual interface members come in. With static virtual interface members, we can define a static method on an interface that can be called from within the generic code. And, in many ways, a constructor is really a special kind of static method. The differences between a constructor versus a static factory method that returns a new instance of T are minor. So, let’s see how we can use static virtual interface members to solve our problem.

// This interface defines a static abstract method, meaning that any class which implements
// the interface must include a static method with the same signature. Note that generic TSelf
// allows the Create method to return a strongly-typed instance.
public interface IVehicleFactory<TSelf>
    // Constrain the generic type parameter to types that self-reference using IVehicleFactory<TSelf>.
    // The Vehicle constraint is optional in this example, but I like to include it for clarity.
    where TSelf : Vehicle, IVehicleFactory<TSelf>
{
    static abstract TSelf Create(string model);
}

public abstract class Vehicle(string model)
{
    public string Model { get; } = model;
}

// IVehicleFactory<Car> is included with a self-referencing generic type parameter
public class Car(string model) : Vehicle(model), IVehicleFactory<Car>
{
    // The create method is implemented as a static method on the class,
    // using Car explicitly as the return type.
    public static Car Create(string model) => new Car(model);
}

// Repeat for Motorcycle
public class Motorcycle(string model) : Vehicle(model), IVehicleFactory<Motorcycle>
{
    public static Motorcycle Create(string model) => new Motorcycle(model);
}

// This method may be called with either Car or Motorcycle to create
// a concrete instance of an Vehicle.
public IEnumerable<T> Create<T>(IEnumerable<string> models)
    // Requires that T implement IVehicleFactory<T> to gain access to the static method
    where T : Vehicle, IVehicleFactory<T>
{
    foreach (var model in models)
    {
        // Reference the static method via T
        yield return T.Create(model);
    }
}

Conclusion

The main limitation of this approach is that you must be in control of the types of TSelf. If Car and Motorcycle were implemented in a third-party library then you may not be able to mark them with the IVehicleFactory<TSelf> interface. Even if they implement the required static factory method, if it isn’t marked with the interface then it won’t work. This is unlike the new() constraint which can be used with any type that has a public parameterless constructor.

The other limitation is static virtual interface members can only be used when targeting .NET 7 or later. This makes them unavailable for legacy applications. It also limits their effectiveness for libraries shared via NuGet that include older TFMs like netstandard2.0.

However, when they’re available to use, static virtual interface members can be a powerful tool for generic type construction that I feel is underutilized. I hope this post has helped you understand how to apply them to your code.

Using Roslyn to Power C# SDK Generation from OpenAPI Specifications

2022-12-09T05:00:00+00:00

This blog is one of The December 9th entries on the 2022 C# Advent Calendar. Believe it or not, this is my 6th year participating. Thanks for having me again Matt and Calvin!

The OpenAPI set of standards (formerly known as Swagger) for defining HTTP-based APIs is a great set of tools. At CenterEdge Software we normally use OpenAPI 3 specifications to describe many of our services, both internal and external, making it easy for applications to reach those services. We also typically use SDK generators to create C# SDKs directly from the API specifications.

One day I asked myself “Hey, I wonder if I can use Roslyn to make an even better, faster OpenAPI SDK generator?” A couple years later and Yardarm is a real thing and the go-to choice at CenterEdge for C# SDK generation.

What is Roslyn

For those that don’t know, Roslyn is the modern C# compiler which is itself written in C# (dogfooding at its finest). It powers everything from compilation to C# source generators to the syntax hints in Visual Studio.

There is a lot to Roslyn, it offers an incredible depth of functionality. But when it comes to its primary functionality, compiling a project, you can think of it as having three main components:

A set of types to represent source code as an immutable syntax tree
A parser that can read source code and turn it into a syntax tree
A compiler that takes a syntax tree and produces output DLL files (and other related files like PDB debug files)

For our purposes, we are primarily interested in creating a syntax tree. Here is some example code which builds a part of a syntax tree to define a method in a class:

MethodDeclaration(
    attributeLists: default, // No attributes
    modifiers: SyntaxTokenList.Create(Token(SyntaxKind.PublicKeyword)), // Public keyword
    returnType: PredefinedType(Token(SyntaxKind.StringKeyword)), // Returns a string
    explicitInterfaceSpecifier: null,
    identifier: Identifier("BuildUri"), // Name of the method
    typeParameterList: default, // No type parameters (this isn't a generic method)
    parameterList: ParameterList(), // No parameters so provide an empty list
    constraintClauses: default, // No generic type constraints
    body: Block(
        // List of statements within the block body of the method
        ReturnStatement(LiteralExpression(SyntaxKind.StringLiteralExpression, Literal("uri")))
    ),
    expressionBody: null, // If we're using => expression syntax instead of a { ... } block, this would go here
    semicolonToken: default // No trailing semicolon since we're not using expression syntax
);

This produces the following C# code:

public string BuildUri()
{
    return "uri";
}

This seems very verbose, but there are also plenty of overloads that help with shorter code. I included a more complete example for clarity.

A single syntax tree, from the root node down, covers every detail behind a single C# code file from using statements to class declarations to the statements in a method body. A collection of syntax trees, combined with other information like referenced assemblies and compiler options, make up a CSharpCompilation.

A note for all the VB and F# folks: Roslyn isn’t only for C#, it’s designed to be language agnostic and also powers other languages in the .NET ecosystem.

Oh, and here’s a great online tool for turning C# into Roslyn creation code.

Performance

The Roslyn C# compiler is fast, Microsoft and others have spent an inordinate amount of time optimizing it. The above approach to generating code works to our advantage when we use it during SDK generation.

A typical SDK generator works using this flow:

Apply templates to the OpenAPI specification to generate C# files
Write the C# files and a supporting csproj file to disk
Run the Roslyn compiler as a separate process
Roslyn reads all the files from disk
Roslyn runs the files through a parser to generate a syntax tree
Roslyn generates the compiled output from the syntax tree and writes to disk

Alternatively, Yardarm works using this much shorter flow:

Generate a syntax tree in memory directly from the OpenAPI specification
Roslyn generates the compiled output from the syntax tree and writes to disk

This avoids the expense of launching two separate processes, the expense of parsing/rendering text-based templates, and the expense of writing and then reading the code from disk followed by a C# parse. In exchange, we simply need to build the syntax tree ourselves.

Extensibility

Earlier, I mentioned that a syntax tree, once built, is immutable. This is technically true but practically false. The classes and structures themselves are immutable once created, making the tree immutable, but a new tree can be created based the existing tree. Roslyn provides a variety of helper methods designed to make this easier such as ReplaceNode, ReplaceNodes, Add..., and With....

Yardarm uses this to its advantage, using a combination of the visitor pattern, aggregators, and dependency injection to allow easy customization of the generated code. I call the types “enrichers”, and their purpose is to enrich a particular syntax tree (or subset of a syntax tree) by examining it and either returning the original tree or creating a replacement. This is also a much more powerful tool for extensibility than typical template engine approaches, which often struggle with defining enough extension points or require replacing entire swaths of templates for a simple change.

This approach is used extensively within the Yardarm internals in addition to allowing the injection of custom extensions. This provides better separation of concerns within the Yardarm source code. Here is an example built-in enricher which adds nullable annotations or default initialization to properties which represent request parameters. An IOpenApiSyntaxNodeEnricher<PropertyDeclarationSyntax, OpenApiParameter> is applied to nodes in the tree which are A) property declarations and B) were generated by a parameter definition on an OpenAPI request.

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using Microsoft.OpenApi.Interfaces;
using Microsoft.OpenApi.Models;
using Yardarm.Helpers;
using static Microsoft.CodeAnalysis.CSharp.SyntaxFactory;

namespace Yardarm.Enrichment.Requests;

public class RequiredParameterEnricher : IOpenApiSyntaxNodeEnricher<PropertyDeclarationSyntax, OpenApiParameter>
{
    public PropertyDeclarationSyntax Enrich(PropertyDeclarationSyntax syntax, OpenApiEnrichmentContext<OpenApiParameter> context)
    {
        if (!context.Element.Required || context.Element.Schema.Nullable)
        {
            // If the parameter is optional OR nullable then the property should be nullable
            // This is because .NET does not have a good way to differentiate between missing and null
            syntax = syntax.MakeNullable();
        }
        else
        {
            // The value needs to be initialized to avoid nullable ref type warnings
            syntax = syntax.MakeNullableOrInitializeIfReferenceType(context.Compilation);
        }

        if (context.Element.Required)
        {
            // Explicitly annotate as required if the parameter is required
            syntax = AddRequiredAttribute(syntax);
        }

        return syntax;
    }

    private PropertyDeclarationSyntax AddRequiredAttribute(PropertyDeclarationSyntax syntax) =>
        syntax.AddAttributeLists(
            AttributeList(SingletonSeparatedList(
                    Attribute(WellKnownTypes.System.ComponentModel.DataAnnotations.RequiredAttribute.Name)))
                .WithTrailingTrivia(ElasticCarriageReturnLineFeed));
}

This class also uses several Yardarm-specific extension methods which perform some common actions on a syntax tree. Of particular interest is the MakeNullableOrInitializeIfReferenceType extension method, which makes use of the SemanticModel.

The SemanticModel is an analysis of the syntax trees, referenced assemblies, etc to determine additional information which isn’t apparent from the syntax tree itself. In this example it is used to determine if the type of the property is a value type or a reference type as well as what constructors are available for that type.

/// <summary>
/// If the given property is a reference type and is not initialized, it should *either* be marked as nullable or
/// be initialized to a non-null value. This method will do it's best to initialize the property using a default constructor
/// or empty string, and failing that will mark the type as nullable.
/// </summary>
/// <param name="property">The <see cref="PropertyDeclarationSyntax"/> to update. Must be on a <see cref="SyntaxTree"/>.</param>
/// <param name="semanticModel"><see cref="SemanticModel"/> used to perform type analysis.</param>
/// <returns>The mutated property declaration, or the original if no mutation was required.</returns>
public static PropertyDeclarationSyntax MakeNullableOrInitializeIfReferenceType(this PropertyDeclarationSyntax property,
    SemanticModel semanticModel)
{
    if (property == null)
    {
        throw new ArgumentNullException(nameof(property));
    }
    if (semanticModel == null)
    {
        throw new ArgumentNullException(nameof(semanticModel));
    }

    if (property.Initializer != null || property.ExpressionBody != null)
    {
        // No need if already initialized or expression body only
        return property;
    }

    if (property.Type is NullableTypeSyntax)
    {
        // Already nullable
        return property;
    }

    var typeInfo = semanticModel.GetTypeInfo(property.Type);
    if (typeInfo.Type?.IsReferenceType ?? false)
    {
        if (typeInfo.Type.SpecialType == SpecialType.System_String)
        {
            // Initialize to an empty string

            property = property
                .WithInitializer(EqualsValueClause(SyntaxHelpers.StringLiteral("")))
                .WithSemicolonToken(Token(SyntaxKind.SemicolonToken));
        }
        else if (!typeInfo.Type.IsAbstract && typeInfo.Type.GetMembers()
            .Where(p => p.Kind == SymbolKind.Method && p.Name == ".ctor")
            .Cast<IMethodSymbol>()
            .Any(p => p.Parameters.Length == 0 && p.DeclaredAccessibility == Accessibility.Public))
        {
            // Build a default object using the default constructor

            property = property
                .WithInitializer(EqualsValueClause(ObjectCreationExpression(property.Type)))
                .WithSemicolonToken(Token(SyntaxKind.SemicolonToken));
        }
        else
        {
            // Mark the types as nullable, even if the parameter is required
            // This will encourage SDK consumers to check for nulls and prevent NREs

            property = property.MakeNullable();
        }
    }

    return property;
}

Extensibility and JSON Serialization

There is a lot of upheaval in the JSON space in .NET since the arrival of System.Text.Json. Newtonsoft.Json has been the go-to serializer for years and is very feature rich, but System.Text.Json is maintained by Microsoft and offers some significant performance benefits. As a result, I wanted Yardarm to have robust support for both of these options (or any other option someone may prefer).

Therefore, JSON serialization within Yardarm is provided as an extension to the core Yardarm implementation. When generating an SDK, simply add one of the two extensions and they add all necessary annotation attributes and wire themselves up as the serializer for application/json and other related content types.

This also means that support for other formats, such as XML, could be added via extensions.

Embedded Source Code

Visual Studio also offers a great set of features around debugging third-party DLL files. One such feature is SourceLink, which links the compiled code back to lines in the original source files on GitHub, GitLab, etc. However, since Yardarm generates code directly using Roslyn, how can we provide the source code with the SDK for debugging purposes?

The answer: we directly embed the source in the PDB file (optionally, of course). However, the C# source code generated doesn’t tend to be very legible. We’re generating the syntax tree without all the nice things like, you know, whitespace.

publicstringMyMethod(){returncodethatlookslikethis+isTERRIBLYhardtoread;}

Yardarm addresses this using another enricher, run only if source embedding is enabled, which applies formatting. It uses Formatter.FormatAsync to do the heavy lifting, which is (I believe) the formatter used internally by Visual Studio when you autoformat a file.

public class FormatCompilationEnricher : ICompilationEnricher
{
    private readonly YardarmGenerationSettings _settings;
    private readonly ILogger<FormatCompilationEnricher> _logger;

    public Type[] ExecuteAfter { get; } =
    {
        typeof(VersionAssemblyInfoEnricher),
        typeof(SyntaxTreeCompilationEnricher),
        typeof(DefaultTypeSerializersEnricher),
        typeof(OpenApiCompilationEnricher),
        typeof(ResourceFileCompilationEnricher)
    };

    public FormatCompilationEnricher(YardarmGenerationSettings settings,
        ILogger<FormatCompilationEnricher> logger)
    {
        ArgumentNullException.ThrowIfNull(settings);
        ArgumentNullException.ThrowIfNull(logger);

        _settings = settings;
        _logger = logger;
    }

    public async ValueTask<CSharpCompilation> EnrichAsync(CSharpCompilation target,
        CancellationToken cancellationToken = default)
    {
        if (!_settings.EmbedAllSources)
        {
            // Don't bother formatting if we're not embedding source
            return target;
        }

        var stopwatch = Stopwatch.StartNew();

        using var workspace = new AdhocWorkspace();
        var solution = workspace
            .AddSolution(
                SolutionInfo.Create(
                    SolutionId.CreateNewId(_settings.AssemblyName),
                    VersionStamp.Default));

        Project project =
            solution.AddProject(_settings.AssemblyName, _settings.AssemblyName + ".dll",
                LanguageNames.CSharp);

        workspace.TryApplyChanges(solution);

        // Exclude files with no path (won't be embedded)
        // We still format resource files, which are typically already formatted, because they may have
        // been mutated by other enrichers.
        IEnumerable<SyntaxTree> treesToBeFormatted = target.SyntaxTrees
            .Where(static p => p.FilePath != "" && p.HasCompilationUnitRoot);

        // Process formatting in parallel, this gives a slight perf boost
        object lockObj = new();
        await Parallel.ForEachAsync(treesToBeFormatted, cancellationToken,
            async (syntaxTree, localCt) =>
            {
                SyntaxNode root = await syntaxTree.GetRootAsync(localCt);

                Document document = project.AddDocument(Guid.NewGuid().ToString(), root);

                document = await Formatter.FormatAsync(document, solution.Options, cancellationToken);

                SyntaxNode? newRoot = await document.GetSyntaxRootAsync(localCt);

                if (newRoot is not null && newRoot != root)
                {
                    lock (lockObj)
                    {
                        target = target.ReplaceSyntaxTree(syntaxTree,
                            syntaxTree.WithRootAndOptions(newRoot, syntaxTree.Options));
                    }
                }
            });

        stopwatch.Stop();

        _logger.LogInformation("Sources formatted for embedding in {elapsed}ms", stopwatch.ElapsedMilliseconds);

        return target;
    }
}

Other Functionality

Yardarm has a LOT of other functionality. Too much to cover in this blog post, which focuses on the Roslyn aspects of Yardarm. However, I’ll try to list a few of the key points here.

Allows targeting many variants of .NET, including .NET 6 and 7
- .NET Framework 4.6.1 and later is supported via .NET Standard 2.0
Generates DLLs, PDB debug files, XML documentation files, and reference assemblies
- XML documentation is extracted from the documentation in the OpenAPI specification
Directly generates a NuGet package which includes the above files, including support for multi-targeting
Uses many modern compiler features
- For example, when targeting .NET 6 it will use string interpolation handlers for more efficient string building
Supports many great patterns and practices
- Includes a built-in extension which supports DI registration using HttpClientFactory
- Generated SDKs are asynchronous from top to bottom
- Makes use of polymorphism to handle the complexities of requests, responses, and discriminated schemas in a way that (usually) won’t break over time as the specification changes
- Interfaces are generated to make mocking for unit tests easy
Available as a .NET Global Tool, a Docker image, or an MSBuild SDK
- The MSBuild SDK approach is particularly cool, you can build SDKs as a project in your solution
Automatically uses NuGet to download dependencies for compilation, such as Newtonsoft.Json or any other dependency defined by an extension
- Yardarm even executes any Roslyn 4 source generators included in the dependencies

Future Work

Yardarm is in use in production, but is still a work in progress. Future plans include:

Extensions for serializing/deserializing dates and times using NodaTime
Refactor System.Text.Json polymorphism to use the new built-in support in .NET 7
Support for link-level trimming when used with System.Text.Json

There are also doubtless API specifications in the wild with use cases which don’t work well today. I’d love to hear about them in Issues so Yardarm can continue to improve.

Conclusion

Hopefully Yardarm showcases the power and flexibility of Roslyn, above and beyond basic compilation and cool code refactoring in Visual Studio. Version 0.3.0 is available and ready for use, and I look forward to feedback from the .NET community on the project.

String Interpolation Trickery and Magic with C# 10 and .NET 6

2021-12-17T11:00:00+00:00

This blog is one of The December 17th entries on the 2021 C# Advent Calendar. Thanks for having me again Matt!

For the last few years we’ve gotten a new version of C# paired with a new version of .NET each November. And every year this new version is packed with great new features. For me, one of the coolest features is interpolated string handlers.

Interpolated string handlers are primarily designed to provide a performance boost building strings. But is there more to them than meets the eye? I believe that they lay the groundwork for doing much more than just building strings faster.

Interpolated String Handler Overview

First, let’s start with an overview of how interpolated string handlers work. For a more in-depth look, see the blog post from Stephen Toub.

When using C# 9, interpolating a string is optimized by the compiler in a variety of ways. However, in many cases the optimizations aren’t an option, and a call to string.Format(...) is used. string.Format brings a lot of overhead, such as interpreting the format string every call, potentially allocating an object[] on the heap, boxing value types, and generating temporary intermediate strings.

For projects targeting .NET 6, even upgrading existing projects, string interpolation gets an immediate performance boost because they will use the DefaultInterpolatedStringHandler to build strings. This structure has a much better performance profile overall than string.Format.

// Example code, from Stephen Toub's post
public static string FormatVersion(int major, int minor, int build, int revision) =>
    $"{major}.{minor}.{build}.{revision}";

// Example equivalent code the compiler generates with .NET 6, from Stephen Toub's post
public static string FormatVersion(int major, int minor, int build, int revision)
{
    var handler = new DefaultInterpolatedStringHandler(literalLength: 3, formattedCount: 4);
    handler.AppendFormatted(major);
    handler.AppendLiteral(".");
    handler.AppendFormatted(minor);
    handler.AppendLiteral(".");
    handler.AppendFormatted(build);
    handler.AppendLiteral(".");
    handler.AppendFormatted(revision);
    return handler.ToStringAndClear();
}

Custom Interpolated String Handlers

The DefaultInterpolatedStringHandler is really just the beginning, though. Methods which accept a string may have an overload which accepts a custom interpolated string handler. When present, this causes C# to use the custom handler you define rather than the default, allowing more advanced behaviors.

These behaviors can include stack allocations of scratch space, accepting other parameters to the method call as constructor arguments to change behaviors, returning a boolean from the constructor that skips the AppendXXX steps if we know they’ll be unused, or short-circuiting additional AppendXXX steps if we want to stop early.

A great example is AssertInterpolatedStringHandler which is available on Debug.Assert calls. It can suppress most of the work building the string in the case where the first parameter to the Assert call is true.

public void Example()
{
    var count = 0;

    // The interpolated string below will never be constructed in .NET 6, even when compiled in DEBUG mode
    Debug.Assert(count == 0, $"The count should be 0, but is {count}.");
}

The equivalent code for the above statement is something like:

public void Example()
{
    var count = 0;

    var condition = count == 0;
    var handler = new AssertInterpolatedStringHandler(31, 1, condition, out bool shouldAppend);
    if (shouldAppend)
    {
        handler.AppendLiteral("The count should be 0, but is ");
        handler.AppendFormatted(count);
        handler.AppendLiteral(".");
    }
    Debug.Assert(condition, handler);
}

If the AppendXXX methods return bool the result is checked after each call and can short-circuit part way through the operation. For example, this might occur if the destination buffer runs out of space.

Now Bring On The Magic

Now, I’d like you to take a moment and consider the AssertInterpolatedStringHandler example above. What does the example have to do with strings? At what point are strings involved?

Wait for it…

The answer is “Only the literal segments are strings.” Of course, Debug.Assert ends up making a string out of it by calling handler.ToStringAndClear(); But the AssertInterpolatedStringHandler is what’s passed to Debug.Assert, not a string. It can do whatever it likes with the handler. Additionally, the implication of AppendFormatted is that it will format count as a string and append it. But in reality it may do whatever it likes.

Therefore, if we can imagine a “thing” which is built up of string literals and expressions presented in order, then we can build it using an interpolated string. Even if what we’re creating isn’t a string at all.

An Example: Parameterized SQL Queries

Have you ever needed to build a parameterized SQL query? Or N1QL Query if you’re a Couchbase user? It’s very important to parameterize user input to prevent injection attacks, so the answer for most database users should be yes. Even if you use an ODM or ORM like Entity Framework it’s often necessary to hand-write queries for special cases.

Building a parameterized query can be a pain. Take this relatively simple example for SqlCommand:

public async Task<string> GetOptionValue(int optionSet, string optionName)
{
    await using var cmd = new SqlCommand("SELECT OptionValue FROM Options WHERE OptionSet = @OptionSet AND OptionName = @OptionName", _connection);
    cmd.Parameters.Add("@OptionSet", SqlDbType.Int).Value = optionSet;
    cmd.Parameters.Add("@OptionName", SqlDbType.NVarChar).Value = optionName;

    return (await cmd.ExecuteScalarAsync()).ToString();
}

If you hate the duplication involved in the parameter names, you may even pull those out to constants, which is even more convoluted.

private const string OptionSetParamName = "@OptionSet";
private const string OptionNameParamName = "@OptionName";

public async Task<string> GetOptionValue(int optionSet, string optionName)
{
    await using var cmd = new SqlCommand($"SELECT OptionValue FROM Options WHERE OptionSet = {OptionSetParamName} AND OptionName = {OptionNameParamName}", _connection);
    cmd.Parameters.Add(OptionSetParamName, SqlDbType.Int).Value = optionSet;
    cmd.Parameters.Add(OptionNameParamName, SqlDbType.NVarChar).Value = optionName;

    return (await cmd.ExecuteScalarAsync()).ToString();
}

What if this could be written instead as follows, but still retained all the security of parameterized queries?

public async Task<string> GetOptionValue(int optionSet, string optionName)
{
    await using cmd = _connection.CreateCommand($"SELECT OptionValue FROM Options WHERE OptionSet = {optionSet} AND OptionName = {optionName}");

    return (await cmd.ExecuteScalarAsync()).ToString();
}

Example Implementation

This example gets somewhat complicated, so I’ve tried to annotate it throughout with comments. First, the builder itself.

// This attribute let's C# know we're making an interpolated string handler
[InterpolatedStringHandler]
// The handler should usually be a "ref struct", meaning it only lives on the stack.
// This may be a limitation if you want to allow "await" within the holes in the expression, so "ref" may be removed in that case.
// However, this example requires "ref struct" because it includes a DefaultInterpolatedStringHandler in its fields.
public ref struct SqlCommandInterpolatedStringHandler
{
    // Internally we'll use DefaultInterpolatedStringHandler to build the query string.
    // This be more performant than reinventing the wheel.
    private DefaultInterpolatedStringHandler _innerHandler;

    // This will maintain a list of parameters as we build the query string
    public SqlParameter[] Parameters { get; }

    // The number of parameters added so far
    private int _parameterCount;

    public SqlCommandInterpolatedStringHandler(int literalLength, int formattedCount)
    {
        // Construct the inner handler, forwarding the same hints
        _innerHandler = new DefaultInterpolatedStringHandler(literalLength, formattedCount);

        // Build an empty list of parameters with the capacity we'll need
        Parameters = new SqlParameter[formattedCount];
        _parameterCount = 0;
    }

    public void AppendLiteral(string value) =>
        // Forward literals to the inner handler to be added to the query string
        // In this example, literals represent query text like "SELECT ..."
        _innerHandler.AppendLiteral(value);

    public void AppendFormatted(ReadOnlySpan<char> value) =>
        // SqlParameters need strings not char spans, so forward to that implementation
        // Other backing implementations may be able to optimize this to avoid allocating a string
        AppendFormatted(value.ToString());

    public void AppendFormatted<T>(T value)
    {
        switch (value)
        {
            case int intValue:
                AppendParameter(SqlDbType.Int, intValue);
                break;

            case bool boolValue:
                AppendParameter(SqlDbType.Bit, boolValue);
                break;

            case string stringValue:
                AppendFormatted(stringValue);
                break;

            // Add support for more types here

            default:
                // Fallback for other types, we could make this smarter or throw an exception
                AppendFormatted(value?.ToString());
                break;
        }
    }

    // There are a lot of AppendFormatted overloads we're required to implement
    // We could use alignment and format parameters for our own purposes, here we ignore them

    public void AppendFormatted<T>(T value, string? format) =>
        AppendFormatted(value);

    public void AppendFormatted<T>(T value, int alignment, string? format) =>
        AppendFormatted(value);

    public void AppendFormatted<T>(T value, int alignment) =>
        AppendFormatted(value);

    public void AppendFormatted(string? value) =>
        AppendParameter(SqlDbType.NVarChar, value);

    public void AppendFormatted(string? value, int alignment = 0, string? format = null) =>
        AppendParameter(SqlDbType.NVarChar, value);

    // Main handler for formatted segments
    private void AppendParameter(SqlDbType paramType, object? value)
    {
        // Since this is intended for use from compiler-generated code, we'll leave out typical runtime
        // preconditions like _parameterCount vs array length. We'll use Debug.Assert instead, and assume
        // the compiler used the type correctly for release builds.
        Debug.Assert(_parameterCount < Parameters.Length, "Exceeded formattedCount");

        // Create a unique parameter name, use an interpolated string builder with a stack-allocated buffer
        Span<char> paramNameBuffer = stackalloc char[8];
        var paramName = string.Create(null, paramNameBuffer, $"@Param{_parameterCount}");

        // Add the parameter name reference to the query string
        _innerHandler.AppendFormatted(paramName);

        // Add the parameter to the collection
        Parameters[_parameterCount] = new SqlParameter(paramName, paramType)
        {
            Value = value
        };
        _parameterCount++;
    }

    // Forward to the inner handler
    public readonly override string ToString() => _innerHandler.ToString();

    // Forward to the inner handler
    public string ToStringAndClear() => _innerHandler.ToStringAndClear();
}

This builder can then be invoked using this extension method:

public static class SqlConnectionExtensions
{
    public static SqlCommand CreateCommand(this SqlConnection connection,
        // The handler should be the last argument.
        // Where possible (i.e. non-async methods) it should usually be a by-ref argument.
        ref SqlCommandInterpolatedStringHandler handler)
    {
        // We must use ToStringAndClear(), not ToString(), to ensure we release resources
        var commandText = handler.ToStringAndClear();

        // Create the command and add the parameters stored in the handler
        var cmd = new SqlCommand(commandText, connection);
        cmd.Parameters.AddRange(handler.Parameters);
        return cmd;
    }
}

The generated SQL command text looks like this:

SELECT OptionValue FROM Options WHERE OptionSet = @Param0 AND OptionName = @Param1

It’s that easy! Okay, maybe not quite easy, but still very powerful. Of course, there’s also a lot of room for improvement on this quick example.

The parameter array could come from the array pool, though I’d want to measure that with benchmarks to be sure it’s advantageous
An overload that takes a stack-allocated Span<SqlParameter> (probably overkill given all the other heap allocations and boxing related to SqlParameter)
A pre-built, static set of parameter names for reuse
Support for more parameter types
Using format strings to specify parameter types, i.e. varchar vs nvarchar
Another static method to create and execute the command rather than just create it
And probably much more I haven’t considered

Other Random Ideas

Here are a few random ideas. Some of these ideas are probably be silly in practice. I’m hoping they’ll get everyone’s creative juices flowing.

Please, don’t write back telling me how dumb the ideas are :). If you have any other ideas, I’d love to see them in the comments!

Random Idea #1: JSON Building Without POCOs

This idea is interesting, but the double curly braces get a bit gnarly. Also, in most cases you probably want a POCO, but I can see simple scenarios where POCOs are overkill. This example also assumes that the literals are parsed at runtime to add double quotes around attribute names. This probably doesn’t have great performance, so it’s more of a thought experiment, but who knows.

public string GetPersonJson(string name, int age, IEnumerable<Child> children)
{
    // name will get wrapped in quotes and special characters escaped, age would be a plain number,
    // children gets serialized as an array
    return JsonInterpolatedSerializer.Serialize($"{{name:{name},age:{age},children:{children}}}");
}

Random Idea #2: Safely Building HTML

In most cases, we build HTML in Razor views or pages. However, sometimes we need to build HTML in code. This can be done with a TagBuilder, but that can feel unwieldy. Building a string that just applies appropriate escaping would be nice. It could even use a TagBuilder under the hood. Though it probably wouldn’t be quite as performant given that the literals would need parsing.

public IHtmlContent CreateParagraph(string content, string class)
{
    // name will get wrapped in quotes and special characters escaped, age would be a plain number,
    // children gets serialized as an array
    return HtmlInterpolatedBuilder.Build($"<p class={class}>{content}</p>");
}

Random Other Idea #3: Hash Codes

This is an example that doesn’t involve strings at all. When overriding object.Equals(object other) its generally accepted that you should also override object.GetHashCode(). However, calculating a hash code for your object may be cumbersome, especially if there are a lot of fields. System.HashCode makes this process easier, but still uses a lot of boilerplate.

public override int GetHashCode()
{
    // I know, I know, there's also HashCode.Combine<...>(...)
    // But that method can't override the comparer, and is limited to 8 fields.
    var hash = new HashCode();
    hash.Add(fieldA);
    hash.Add(fieldB);
    hash.Add(fieldC, StringComparer.OrdinalIgnoreCase);
    return hash.ToHashCode();
}

What if we had this syntax:

// In theory, if AppendLiteral is an inlined no-op JIT should optimize away the call
// This would drop any literal segments, such as whitespace, without perf penalty.
// Just a theory, I haven't tested it.
// Also, note the use of "i" as a format string, which in this case indicates case-insensitive comparison.
public override int GetHashCode() => HashCodeInterpolated.Calculate($"{fieldA} {fieldB} {fieldC:i}");

Conclusion

In conclusion, I think the .NET community, especially library developers, should embrace the idea that interpolated string handlers can be valuable for much more than just boosting string building performance. They open up a wide range of exciting new possibilities.

C# 9 Records and Init Only Settings Without .NET 5

2020-12-11T11:00:00+00:00

This blog is one of The December 11th entries on the 2020 C# Advent Calendar. Thanks for having me again Matt!

Some of the biggest new features in C# 9 have got to be Records and Init only setters. But when can you safely use these features? Officially, you can only use them if you are targeting .NET 5. However, many developers may not be ready to move to .NET 5 yet, especially since it isn’t an LTS release. And what about NuGet packages targeting .NET Standard or other versions of .NET?

TL;DR

For internal projects and/or types, you can safely use records and init only setters to target any modern version of .NET. I’ve tested .NET 4.8, .NET Core 2.1, and .NET Core 3.1. However, for any public members exposed via NuGet packages there are lots of caveats.

Note: Most of the other C# 9 features are fine to use, regardless of target frameworks or consumer C# versions:

Top-level statements
Switch expression pattern matching enhancements
Native sized integers (syntactic sugar for IntPtr/UIntPtr)
Target-typed new expression
Static anonymous functions
GetEnumerator extension methods
Lambda discard patterns
Attributes on local functions
New features for partial methods

What are Records?

There are plenty of blog posts out there that describe records and what they do, so I won’t dig in too deep here. In simple terms, they provide a lot of boilerplate code that allows a developer to create immutable reference types with value equality, easy methods to clone the types with slightly different values, and more.

public namespace MyProgram
{
  public record Person
  {
    public string? FirstName { get; init; }
    public string? LastName { get; init; }
  }

  public record PersonWithHeight : Person
  {
    public int HeightInInches { get; init; }

    public PersonWithHeight Grow(int inches) =>
      this with { HeightInInches = HeightInInches + inches };
  }
}

PersonWithHeight person = new()
{
  FirstName = "Brant",
  LastName = "Burnett",
  HeightInInches = 69
};

Under the covers, records are really classes with a lot of boilerplate code already added to deal with equality comparisons, cloning, ToString, etc.

What are init only setters?

Init only setters are not really specific to records, though they are quite powerful when combined. You can see an example of init only setters above in the example for records. Instead of a set keyword, the property uses an init keyword. These properties can only be set as part of an object initializer combined with the constructor, after which they may not be modified.

Person person = new()
{
  FirstName = "Brant" // Allowed
};

person.LastName = "Burnett"; // This will cause a compiler error

Under the covers, C# does this by making the setter method have a slightly different signature. Normally, the signature would be void set_FirstName(string value), but an init only setter has the signature void modreq(System.Runtime.CompilerServices.IsExternalInit) set_FirstName(string value). Note that modreq can’t be directly added to a method signature in C#, this is an IL construct. C# adds it for you in this case.

Requirements to Create Records and Init Only Setters

LangVersion 9

Your project must be using C# 9 or later. If you’re targeting .NET 5, this should be the case already. However, if you target other runtimes, you may need to manually enable C# 9 in your .csproj file.

<PropertyGroup>
  <LangVersion>9</LangVersion>
</PropertyGroup>

You must also be using Visual Studio 2019 16.8 or later, or MSBuild 2019 16.8 or later, or the .NET Core SDK 5.0.100 or later. These are the versions that include the C# 9 compiler.

Creating Init Only Properties on Older Frameworks

The key to init-only properties is the IsExternalInit class, which is basically nothing but a placeholder (somewhat like an empty attribute) that is applied to the void return type of the setter. This type is defined as part of .NET 5, but if you’re not targeting .NET 5 then it’s not available for the compiler to reference.

CS0518 Predefined type 'System.Runtime.CompilerServices.IsExternalInit' is not defined or imported

To fix this, you must include the type yourself in your code. I recommend a copy/paste of the following into a file in your project. It includes conditional compilation directives which work if you’re multi-targeting so that it isn’t included unless necessary.

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.

#if NETSTANDARD2_0 || NETSTANDARD2_1 || NETCOREAPP2_0 || NETCOREAPP2_1 || NETCOREAPP2_2 || NETCOREAPP3_0 || NETCOREAPP3_1 || NET45 || NET451 || NET452 || NET6 || NET461 || NET462 || NET47 || NET471 || NET472 || NET48

using System.ComponentModel;

// ReSharper disable once CheckNamespace
namespace System.Runtime.CompilerServices
{
    /// <summary>
    /// Reserved to be used by the compiler for tracking metadata.
    /// This class should not be used by developers in source code.
    /// </summary>
    [EditorBrowsable(EditorBrowsableState.Never)]
    internal static class IsExternalInit
    {
    }
}

#endif

Creating Records on Older Frameworks

Records actually work fine on older frameworks without any special changes, so long as you aren’t using init only setters.

However, records do transparently apply init only setters if you use this syntax to define the properties:

public record Person(string FirstName, string LastName)
{
}

In that case, be sure to add the IsExternalInit class above.

Consuming Records and Init Only Properties

What about including records and init only properties in things like NuGet packages? What are the requirements for package consumers to be able to use these features?

Private Members

It is safe to include private or internal records or properties with init only setters in public facing assemblies. Records are basically just syntactic sugar on top of classes, and modreq used by init only setters have been around a long time.

Public Init Only Setters

To use a public or protected property with an init only setter, the consumer must be using a C# compiler that supports C# 9. Even if they aren’t using LangVersion 9 in their csproj, the compiler must be capable of understanding the modreq. If the consumer doesn’t understand the init only setter, it will be unable to access the setter at all and will appear as a read-only property.

Similarly, other languages like VB.NET don’t like init only setters. In fact, VB.NET won’t recognize the property at all, even as read-only, and even with the latest version of the VB.NET compiler.

As a result, I do not recommend using init only setters for public members unless it is for an internal project with a known list of consumers. All of these consumers must be C# projects, and all developers must be using the latest C# compiler.

Public Records

The compatibility of records across different versions of C# is a bit more confusing. First of all, if you’re using init only setters on your records (you probably are) then see those rules above.

C# consumers can get most of the other features of records, except cloning. The clone method is hidden under the special name <Clone>$ and you can’t reach it directly in C#, you must use the with operator which is only available in C# 9.

The same limitation applies in VB.NET, except even on the latest version there is no equivalent of the with operator. This makes cloning completely unavailable.

Summary

Okay, all of that was pretty convoluted. Variables include your target framework, your consumer’s target framework, your LangVersion, and the version of MSBuild or .NET Core SDK installed on the consumer’s development machine and build agents.

For developers of NuGet packages which must be consumed by many users, here’s a matrix that will hopefully make things a bit clearer. These are my recommendations, some of these listed as Not Available could be considered partially available. But in my opinion the limitations aren’t worth it and it should be avoided.

Private/Internal Members	.NET 5.0 Target	Older Targets
C# .NET 5.0 Consumer	Available	Available (*)
VB .NET 5.0 Consumer	Available	Available (*)
C# 9 Older Framework Consumer	n/a	Available (*)
C# <9 Older Framework Consumer	n/a	Available (*)
VB Older Framework Consumer	n/a	Available (*)

Public/Protected Members	.NET 5.0 Target	Older Targets
C# .NET 5.0 Consumer	Available	Available (*)
VB .NET 5.0 Consumer	Available	Available (*)
C# 9 Older Framework Consumer	n/a	Available (*)
C# <9 Older Framework Consumer	n/a	Not Available
VB Older Framework Consumer	n/a	Not Available

(*) = Must add IsExternalInit class snippet above

Conclusion

To boil it all down even more simply, here are my overall recommendations for when you should and should not use records and init only setters.

Project Type	Public Records	Internal/Private Records	Public/Protected Init Only Setters	Internal/Private Init Only Setters
Internal Use	Yes	Yes	Yes	Yes
NuGet	No	Yes	No	Yes
NuGet .NET 5 Target Only	Yes	Yes	Yes	Yes

Reclaiming HD Space from Docker Desktop on WSL 2

2020-12-11T11:00:00+00:00

Over time, Docker Desktop running on Windows Subsystem for Linux 2 (a.k.a. WSL 2) may start to eat away at your hard drive space. Here is how I was able to free up over 100GB.

Freeing up space within Docker

The first problem is freeing up the space being used by Docker internally. This may include container images, containers, dangling image layers, volumes, and even networks. There are several different command which will help clean these up.

It isn’t necessarily required to perform all of these steps, you should edit based on your particular needs. I will say that container images are the biggest culprit in most cases. Also, in general it is safe to delete container images, as they may be downloaded again as needed.

Since we’re talking primarily about Windows, these examples are in Powershell. However, the general concept should work from Bash as well.

# Delete all containers (if acceptable). This allows the images they are referencing to be deleted,
# but is not required. The first command ensures that all containers are stopped.
docker ps -q | % { docker stop $_ }
docker ps -aq | % { docker rm $_ }

# Delete all container images. This may return a few errors but that is usually fine.
docker images --format "{{.Repository}}:{{.Tag}}" | % { docker rmi $_ }

Once this is done, further commands will do more cleanup:

# Cleans up several different items.
docker system prune

# Optionally, this format will also delete your Docker storage volumes. Beware of data loss.
docker system prune --volumes

If you want to delete some volumes, but leave others in place, I have used scripts like this one in the past.

# Delete all volumes with names that do not contain "halyard" or "vscode".
docker volume ls -q | where { -not ($_ -match "halyard" -or $_ -match "vscode") } | % { docker volume rm $_ }

Reclaiming the space for Windows

After freeing space within Docker, the space will (unfortunately) not be freed for Windows to use. The problem is that Docker keeps its data within a VHDX virtual drive file. This file now has lots of free space within it, but it needs to be shrunk.

Adding to the problem is that Windows Hyper-V isn’t great about recognizing unused sectors within a VHDX file using the EXT4 Linux file system. I won’t pretend to be an expert, but my understanding is that we need to convince Linux to send TRIM commands to the hardware abstraction layer to indicate unused sectors. Once this is done, Hyper-V can more successfully shrink the VHDX file.

# Run this as an Administrator, not all of these steps work as a regular Windows user.

# Perform the TRIM commands and then delete the image we just used.
docker run --rm --privileged --pid=host docker/desktop-reclaim-space
docker rmi docker/desktop-reclaim-space

# Shutdown Docker and WSL 2. You may wish to exit Docker Desktop gracefully before this step.
# If you get file in use errors on the next step, not performing this step is the likely culprit.
wsl --shutdown

# Optimize the VHDX file to reclaim free space. This may take a few minutes.
Optimize-VHD -Path ${env:LOCALAPPDATA}\Docker\wsl\data\ext4.vhdx -Mode Full

Side note

If you’re running antivirus, be sure you’ve excluded VHDX files from real time scans for better performance within Docker. See Recommended antivirus exclusions for Hyper-V hosts for details.

Conclusion

In my case, this took my VHDX file from over 120 GB to about 10GB, which was a pretty big win for my laptop’s 500GB SSD. Please let me know if you find any other tips/tricks in the comments that I should add to this post.

IAsyncEnumerable Is Your Friend, Even In .NET Core 2.x

2019-12-01T11:00:00+00:00

This blog is one of The December 1st entries on the 2019 C# Advent Calendar. Thanks for having me again Matt!

My favorite new feature in C# 8 has got to be Asynchronous Streams, a.k.a. Asynchronous Enumerables. However, I think there may some confusion as to what they do, when to use them, and even if they can be used in a particular project. This post will hopefully clarify some of these points.

TL;DR

You can use IAsyncEnumerable<T> and the related C# 8 features in .NET Core 2.x or .NET Framework 4.6.1, not just .NET Core 3.0!

Why use `IAsyncEnumerable<T>`?`

When writing efficient applications intended to handle large numbers of simultaneous operations, such as web applications, blocking operations are the enemy. Any time an application is waiting on some kind of I/O-bound operation, such as a network response or a hard disk read, it is always best to relinquish the thread back to the thread pool. This allows the CPU to work on other operations while the method is waiting, and then continue the work once there is more to be done, without using up all of the threads in the thread pool. Lots of details about why are available here.

In many cases, it’s efficient enough to simply return a regular IEnumerable<T> asynchronously, like so:

public async Task DoWork()
{
    var query = BuildMyQuery();

    IEnumerable<XYZ> queryResult = await query.ExecuteAsync();

    foreach (var item in queryResult)
    {
        // Do work here
    }
}

However, this is may not be the most efficient approach. There are two potential limitations, depending on the backing implementation of ExecuteAsync in the example above.

The implementation of ExecuteAsync may return after it gets the first part of the data, or even none. If it is enumerated faster than the data is arriving it will block waiting for more items to arrive. This will block the executing thread.
The implementation of ExecuteAsync may wait until it has all of the data before returning. This delays the point where DoWork may begin processing data.

IAsyncEnumerable<T> and its sibling IAsyncEnumerator<T>, on the other hand, return a Task as the stream is iterated. This allows methods such as ExecuteAsync to return early and then wait for more data as it is iterated, without blocking the thread.

When Not To Use IAsyncEnumerable

Don’t use IAsyncEnumerable<T> for any collection which is inherently synchronous and CPU-bound. For those cases, continuing using IEnumerable<T>. The extra overhead of handling asynchronous tasks will usually be less performant in these scenarios.

Knowing which type to use as the return type on an interface method is a bit tricker. The interface can have different backing implementations which may or may not be synchronous. In this case, use the pattern for the most likely scenario. If in doubt, lean towards IAsyncEnumerable<T> because it can be used for either scenario and is therefore more flexible.

Returning an IAsyncEnumerable in C# 8

For simple use cases, returning an IAsyncEnumerable<T> using an iterator function is as easy as an IEnumerable<T>.

public async IAsyncEnumerable<XYZ> GetXYZAsync() {
    for (var i=0; i<20; i++)
    {
        var item = await GetXYZById(i);

        yield return item;
    }
}

It is also possible to write an iterator method which returns IAsyncEnumerator<T>.

If the method supports cancellation, the CancellationToken should to be decorated with the EnumeratorCancellation attribute:

public async IAsyncEnumerable<XYZ> GetXYZAsync([EnumeratorCancellation] CancellationToken cancellationToken = default) {
    for (var i=0; i<20; i++)
    {
        var item = await GetXYZById(i, cancellationToken);

        yield return item;
    }
}

Consuming an IAsyncEnumerable in C# 8

To consume an IAsyncEnumerable, simply use the new await foreach statement within an asynchronous method.

await foreach (var item in GetXYZAsync())
{
    // do things here
}

To control the synchronization context, ConfigureAwait is available, just like on Task.

await foreach (var item in GetXYZAsync().ConfigureAwait(false))
{
    // do things here
}

To pass a cancellation token:

await foreach (var item in GetXYZAsync().WithCancellation(cancellationToken))
{
    // do things here
}

Special Compatibility Concerns

Depending on the type of project and the version of .NET being targeted, there may be concerns about compatibility. One myth is that these features can only be used with .NET Core 3.0 and C# 8.

Can I Use IAsyncEnumerable When Targeting .NET Core 2.x?

Short answer: Yes

To gain access to IAsyncEnumerable, install the compatibility NuGet package Microsoft.Bcl.AsyncInterfaces. This provides the types that are missing in .NET Standard 2.0.

However, producing and consuming IAsyncEnumerables is a bit more difficult. Here’s an example consumer:

var enumerable = GetXYZAsync();
var enumerator = enumerable.GetAsyncEnumerator();
try
{
    while (await enumerator.MoveNextAsync())
    {
        var item = enumerator.Current;

        // Do things here
    }
}
finally
{
    await enumerator.DisposeAsync();
}

To get around this limitation, there are ways to access C# 8 language features, like asynchronous streams, even from .NET Core 2.x. The requirements are:

Use .NET Core SDK 3.0 or MSBuild Tools 2019 as the compiler.
Use Visual Studio 2019 or VSCode as the IDE.
Add a <LangVersion>8</LangVersion> property to the project file.

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp2.0</TargetFramework>
    <LangVersion>8</LangVersion>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Bcl.AsyncInterfaces" Version="1.0.0" />
  </ItemGroup>

</Project>

Can I Use IAsyncEnumerable When Targeting .NET Framework

Short answer: Yes, 4.6.1 or later

.NET Framework 4.6.1 is compatible with .NET Standard 2.0. Therefore, so long as the project is targeting .NET Framework 4.6.1 or later, the same rules apply as for .NET Core 2.x. Just follow the same steps as above.

What About NuGet Packages?

Short answer: Yes, targeting .NET Standard 2.0 or later

When creating a NuGet package, maintaining backwards compatibility is key. This can make it difficult to use new features like asynchronous streams. The good news is that there is a relatively easy path.

Dual target .NET Standard 2.0 and 2.1.
Consider targeting .NET 4.6.1 as well, see Microsoft’s guidance on cross platform targeting.
Include Microsoft.Bcl.AsyncInterfaces for the lower version targets only.
Add a <LangVersion>8</LangVersion> property to the project file.

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

  <PropertyGroup>
    <TargetFrameworks>net461;netstandard2.0;netstandard2.1</TargetFrameworks>
    <LangVersion>8</LangVersion>
  </PropertyGroup>

  <ItemGroup Condition=" '$(TargetFramework)' == 'net461' Or '$(TargetFramework)' == 'netstandard2.0' ">
    <PackageReference Include="Microsoft.Bcl.AsyncInterfaces" Version="1.0.0" />
  </ItemGroup>

</Project>

However, this approach has problems if the package needs to target versions of .NET Core before 2.0, .NET Standard before 2.0, or .NET Framework before 4.6.1. The Microsoft.Bcl.AsyncInterfaces package isn’t compatible with frameworks prior these versions. This can still be addressed by using preprocessor conditionals within the codebase to exclude IAsyncEnumerable<T> support, but is much more cumbersome and outside the scope of this post.

What about LINQ?

Most .NET developers love to use LINQ, either using the query syntax or using the functional syntax like .Where(p => p != null) or .Select(p => p.Property). Is it possible to use LINQ with IAsyncEnumerable<T>?

To get support for the functional LINQ syntax, such as .Where(p => p != null) or .Select(p => p.Property), install System.Linq.Async. This package is brought to us by the group that makes ReactiveX. Be sure to use at least version 4.0.0.

Conclusion

Don’t be afraid to use IAsyncEnumerable<T> in your code. It’s really a lot more available than most developers think it is, and is very easy to use.

Blue/Green Message Bus Handling on Kubernetes with Shawarma

2019-08-12T06:00:00+00:00

In the modern world of cloud-based microservices and continuous delivery, blue/green deployments (a.k.a red/black deployments) have become commonplace. This approach provides a way to safely deploy an application with zero down time, and quickly roll back to the previous version if there is a problem. If you’re deploying in the cloud and not using blue/gren deployments, stop reading now and go find out what you’re missing.

At CenterEdge Software our primary deployment strategy is blue/green deployments to Kubernetes using Spinnaker. However, in practice we quickly discovered a limitation of the typical blue/green deployment strategy.

TL;DR

We’ve solved the problem of blue/green deployments of message bus consumers on Kubernetes using a lightweight sidecar and a simple application plugin. We call the system Shawarma. (Yes, it’s an Avengers MCU reference)

The Problem

The key to blue/green deployments is the ability to route incoming requests to just the active version of the service, leaving the inactive version idle. This works great for incoming HTTP requests, as the blue/green deployment pipeline will put the active service on the load balancer and remove the inactive service. You’ll only have a brief window where both versions are serving HTTP requests.

However, queued messages being processed from your message bus, such as Kafka or RabbitMQ, should be restricted as well. These also represent a form of input, like HTTP requests, which should only be processed by the active version. However, message bus processing is normally a pull process, not push, which makes the problem more complicated.

Possible Solutions

There are several possible approaches to solving the problem, but many suffer from too much complexity. For example, one approach is to separate message bus processing from the service and forward requests to the service over HTTP. I’ll call this the Redirection Approach.

This approach helps to maintain separation of concerns, since the service itself isn’t required to know about its deployment or understand if it’s the active or inactive version. However, it adds a lot of complexity, requires deploying an additional service, and results in a signifcant performance hit for high-volume queues.

Another approach, which I’ll call the Colorful Service Approach, requires that the service know about its deployment status by monitoring the load balancer.

The Colorful Service Approach is simpler in many ways, but now our concerns are not separate. The service itself needs to know about the deployment environment, how to check the status of the load balancer, and more. While this works, it doesn’t make for a very Evolutionary Architecture.

The Shawarma Solution

At CenterEdge, we’ve created our own, open source solution to this problem, Shawarma. Shawarma is specifically designed for Kubernetes, and works via a modified version of the Colorful Service Approach. It simplifies the design even further, and maintains separation of concerns by keeping the application itself agnostic. It takes advatange of the Kubernetes API and built-in support for watch commands to receive notifications about state changes within the Kubernetes cluster.

In the Shawarma Approach, each service gets a single additional HTTP endpoint which receives POST operations informing the service of its state, active or inactive. It doesn’t know anything at all about the deployment environment, it only knows this single, basic data point.

The brains of the operation is a Shawarma sidecar deployed within the Kubernetes pod. This sidecar container knows about Kubernetes and its Services and Endpoints, and monitors Kubernetes to know if the application is active or inactive on the assigned load balancer. When the status changes, it makes an HTTP POST calls to notify the main service. The main service can then discontinue or restart any background processing, including message bus processing.

Shawarma Implementation

The Shawarma sidecar is implemented as a very lightweight Go application, available on Docker Hub. At this point it’s in beta testing at CenterEdge, but the early signs are very encouraging.

Additionally, we recognized very quickly that deployments needed to be kept as simple as possible. The need to configure dozens of microservices with a sidecar container was daunting. To that end, we’ve created a simple Kubernetes MutatingAdmissionWebhook. When the Shawarma Webhook is deployed, a simple annotation on a Pod (or Deployment template) will automatically configure the sidecar.

apiVersion: v1
kind: Pod
metadata:
  labels:
    app: shawarma-example
    active: 'true'
  annotations:
    # The annotation value is name of the service for Shawarma to monitor
    shawarma.centeredge.io/service-name: shawarma-example
spec:
  # ...

A full example set can be found here.

Application State in ASP.NET Core

Since CenterEdge is a .NET shop, we’ve also implemented some supporting NuGet packages to handle the application state.

Package	Description
Shawarma.Abstractions	Basic abstractions and models
Shawarma.AspNetCore	.NET Core middleware for receiving and handling application state
Shawarma.Hosting	The `IShawarmaService` system, an equivalent to IHostedService which starts and stops based on application state

Using these SDK packages, adding slim, agnostic handling of Shawarma application state is easy.

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddMvc()
        .AddShawarmaHosting()
        // Add any IShawarmaService instances to be managed
        .AddShawarmaService<TestService>();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    // Add before MVC or other handlers
    app
        .UseShawarma()
        .UseMvc();
}

public class TestService : GenericShawarmaService
{
    public TestService(ILogger<TestService> logger)
        : base(logger)
    {
    }

    protected override Task StartInternalAsync(CancellationToken cancellationToken)
    {
        // Start doing work here
        return Task.CompletedTask;
    }

    protected override Task StopInternalAsync(CancellationToken cancellationToken)
    {
        // Stop doing work here
        return Task.CompletedTask;
    }
}

Conclusion

Hopefully, the Shawarma project will be helpful to other services deploying microservices to Kubernetes. We’re very open to feedback, issues may be filed at GitHub. We’d also love some help from the community developing application state SDKs for other frameworks such as Java and Node.

It’s also worth nothing that the Shawarma Approach is useful for more than just message bus processing. Any kind of background work being handled outside of HTTP requests can benefit, such as scheduled tasks or polling remote data sources.

A Restful Job Pattern For A C# Microservice

2018-12-06T12:30:00+00:00

This blog is one of The December 6th entries on the 2018 C# Advent Calendar. Thanks for having me again Matt!

One of the key differences between REST (Representational State Transfer) and RPC (Remote Procedure Calls) is that all actions within REST are conducted as if getting or mutating a specific resource. In most cases, especially basic CRUDL operations, this makes for a cleaner and more concise API structure than RPC. However, it can also add friction in certain cases.

One such case is dealing with long-running jobs. What if creating a new resource takes time and isn’t immediately available? I won’t go into the details in this post, here is a post by Victor Farazdagi that provides an overview. However, I’m going to use the basic endpoints he discusses in my examples.

This concept is great, but what about the practical implementation? If your application is a based on a single, long-lived server that never fails or reboots, read no further because the implementation is easy. If, on the other hand, your application operates in the real world of ephemeral servers, load balancers, microservices, and unreliable hardware, keep reading!

Note: The completed and runnable example is available at https://github.com/brantburnett/CouchbaseRestfulJobPattern.

The Architecture

Before I dig into an implementation, let’s discuss the high-level architecture of the application.

The application is a microservice running in a Docker container
There will be multiple instances of the application behind a load balancer
Any given instance may die at any given time due to hardware failure, scale-in, etc.
The instances all share a data store (in this case Couchbase, but any data store supporting atomic writes would suffice)
The instances are connected by a message bus which supports At Least Once delivery (such as RabbitMQ, Kafka, etc)

I’m also going to assume that we already have the basic application in place with endpoints for managing stars, but it currently doesn’t use the job pattern.

The Requirements

When a star is created, we should return quickly with a link to a long-running job
There should be a way to monitor the job for completion and retrieve to star ID
Jobs should trigger quickly under normal circumstances
Job processing load should be at least somewhat balanced across application instances
Jobs should only run on one application instance at a time
An application instance shouldn’t oversubscribe to too many jobs at once
Job processing should not prevent the application from exiting during scale-in or maintenance
Jobs should be resumed on another application instance if an instance is stopped or fails

The Job Document

First, let’s create a JobRepository that can be used to persist the job and its status to the database. We’ll support document expirations on jobs so that old, completed jobs can be cleaned up eventually.

[DocumentTypeFilter(TypeString)]
public class Job
{
    private const string TypeString = "job";

    public long Id { get; set; }
    public string Type => TypeString;

    [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
    public Star CreateStar { get; set; }

    [JsonConverter(typeof(StringEnumConverter))]
    public JobStatus Status { get; set; }

    public static string GetKey(long id) => $"{TypeString}-{id}";
}

public class JobRepository
{
    private readonly IBucket _bucket;

    public JobRepository(IDefaultBucketProvider bucketProvider)
    {
        _bucket = bucketProvider.GetBucket();
    }

    public Task<IEnumerable<Job>> GetAllJobsAsync()
    {
        var context = new BucketContext(_bucket);

        return context.Query<Job>()
            .OrderBy(p => p.Id)
            .ExecuteAsync();
    }

    public Task<IEnumerable<Job>> GetIncompleteJobsAsync()
    {
        var context = new BucketContext(_bucket);

        return context.Query<Job>()
            .Where(p => p.Status != JobStatus.Complete)
            .OrderBy(p => p.Id)
            .ExecuteAsync();
    }

    public async Task<Job> GetJobAsync(long id)
    {
        var result = await _bucket.GetDocumentAsync<Job>(Job.GetKey(id));
        if (result.Status == ResponseStatus.KeyNotFound)
        {
            return null;
        }

        // Throw an exception on a low-level error
        result.EnsureSuccess();

        return result.Content;
    }

    public async Task CreateJobAsync(Job job)
    {
        if (job == null)
        {
            throw new ArgumentNullException(nameof(job));
        }

        job.Id = await GetNextJobIdAsync();

        var document = new Document<Job>
        {
            Id = Job.GetKey(job.Id),
            Content = job
        };

        var result = await _bucket.InsertAsync(document);
        result.EnsureSuccess();
    }

    public async Task UpdateJobAsync(Job job, TimeSpan? expiration)
    {
        if (job == null)
        {
            throw new ArgumentNullException(nameof(job));
        }

        var document = new Document<Job>
        {
            Id = Job.GetKey(job.Id),
            Expiry = (uint) (expiration?.TotalMilliseconds ?? 0),
            Content = job
        };

        var result = await _bucket.ReplaceAsync(document);
        result.EnsureSuccess();
    }

    private async Task<long> GetNextJobIdAsync()
    {
        // Redacted here for clarity
    }
}

Next, let’s create JobService to handle business logic associated with these jobs (we’ll be fleshing this out more later).

public class JobService
{
    private readonly JobRepository _jobRepository;


    public JobService(JobRepository jobRepository)
    {
        _jobRepository = jobRepository ?? throw new ArgumentNullException(nameof(jobRepository));
    }

    public async Task<Job> CreateStarJobAsync(Star star)
    {
        var job = new Job
        {
            CreateStar = star,
            Status = JobStatus.Queued
        };

        await _jobRepository.CreateJobAsync(job);

        return job;
    }
}

Next, we need a simple controller to get Job status.

[Route("job")]
[ApiController]
public class JobsController : ControllerBase
{
    private readonly JobRepository _jobRepository;
    private readonly IMapper _mapper;

    public JobsController(JobRepository jobRepository, IMapper mapper)
    {
        _jobRepository = jobRepository ?? throw new ArgumentNullException(nameof(jobRepository));
        _mapper = mapper ?? throw new ArgumentNullException(nameof(mapper));
    }

    // GET job
    [HttpGet]
    public async Task<ActionResult<IEnumerable<JobDto>>> Get()
    {
        var jobs = await _jobRepository.GetAllJobsAsync();

        return jobs.Select(p => _mapper.Map<JobDto>(p)).ToList();
    }

    // GET job/5
    [HttpGet("{id}")]
    public async Task<ActionResult<JobDto>> Get(long id)
    {
        var result = await _jobRepository.GetJobAsync(id);
        if (result == null)
        {
            return NotFound();
        }

        return _mapper.Map<JobDto>(result);
    }
}

And, finally, we need to modify StarsController to create the job when a request is made, and return 202 Accepted as the status with a Location header.

[HttpPost]
public async Task<IActionResult> Post([FromBody] StarDto star)
{
    if (!ModelState.IsValid)
    {
        return BadRequest();
    }

    star.Id = 0;
    var job = await _jobService.CreateStarJobAsync(_mapper.Map<Star>(star));

    return AcceptedAtAction("Get", "Jobs", new {id = job.Id});
}

Performing The Action

As an observant reader, I’m sure you noticed that we actually aren’t doing anything with the job yet. It’s just storing the Job document in Couchbase, but it never actually processes the job and the status will remain Pending.

For the next step, we need to make use of our message bus. Of course, we could just start the job on a background thread as part of CreateStarJobAsync. However, this could result in unbalanced load. Due to requirement #6, we’re going to eventually put limiters in place so that an application instance won’t process too many jobs at once. What would happen if the instance that received the POST request was already at the limit, but some other instance still had available capacity? We’d prefer for the work to be picked up on the other instance. Starting the job via the message bus separates the receiving instance from the processing instance, but still maintains a fast response time for requirement #3.

At this point, I’ll assume that the application has a simple MessageBus class that acts as an abstraction for sending and receiving these messages. First, we add some logic to JobService.

public async Task<Job> CreateStarJobAsync(Star star)
{
    var job = new Job
    {
        CreateStar = star,
        Status = JobStatus.Queued
    };

    await _jobRepository.CreateJobAsync(job);

    // We're adding this line to the existing method
    QueueJob(job.Id);

    return job;
}

// And adding these methods below

public void QueueJob(long id)
{
    _messageBus.SendMessage(new Message {JobId = id});
}

public async Task ProcessNextJobAsync(CancellationToken cancellationToken)
{
    var message = await _messageBus.ReceiveMessage(cancellationToken);
    if (message != null)
    {
        await ExecuteJobAsync(message.JobId, cancellationToken);
    }
}

public async Task ExecuteJobAsync(long id, CancellationToken token)
{
    // Reload the document to make sure it's still pending
    var job = await _jobRepository.GetJobAsync(id);
    if (job.Status == JobStatus.Complete)
    {
        return;
    }

    // Update the status to Running
    job.Status = JobStatus.Running;
    await _jobRepository.UpdateJobAsync(job, null);

    // We're just emulating a long running job here, so just delay
    await Task.Delay(TimeSpan.FromSeconds(45), token);

    // To emulate a failed job, either throw an exception here
    // Or stop the app before the delay above is reached

    // Finish creating the star
    await _starRepository.CreateStarAsync(job.CreateStar);

    // Update the job status document
    job.Status = JobStatus.Complete;
    await _jobRepository.UpdateJobAsync(job, TimeSpan.FromDays(1));
}

Now, we add a JobProcessor class that loops and calls ProcessNextJobAsync until disposed.

public class JobProcessor : IDisposable
{
    private readonly JobService _jobService;
    private readonly ILogger<JobProcessor> _logger;

    private readonly CancellationTokenSource _cts = new CancellationTokenSource();

    private bool _started;
    private bool _disposed;

    public JobProcessor(JobService jobService, ILogger<JobProcessor> logger)
    {
        _jobService = jobService ?? throw new ArgumentNullException(nameof(jobService));
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }

    public void Start()
    {
        if (_disposed)
        {
            throw new ObjectDisposedException(nameof(JobProcessor));
        }

        if (!_started)
        {
            Task.Run(Poll);

            _started = true;
        }
    }

    public void Dispose()
    {
        if (!_disposed)
        {
            _cts.Cancel();

            _disposed = true;
        }
    }

    private async Task Poll()
    {
        while (!_cts.IsCancellationRequested)
        {
            try
            {
                await _jobService.ProcessNextJobAsync(_cts.Token);
            }
            catch (OperationCanceledException)
            {
                // Ignore
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Unhandled exception in JobPoller");
            }
        }
    }
}

And, finally, we start the poller when the application starts and dispose it when stopping by adding these lines to Startup in the Configure method.

var jobProcessor = app.ApplicationServices.GetRequiredService<JobProcessor>();
jobProcessor.Start();

var appLifetime = app.ApplicationServices.GetRequiredService<IApplicationLifetime>();
appLifetime.ApplicationStopping.Register(() =>
{
    jobProcessor.Dispose();
});

Now we’ve addressed requirement #3 (start processing quickly), requirement #4 (load balance the processing across instances), and requirement #7 (the ApplicationStopping event will dispose the JobProcessor which then cancels any current processing via the CancellationToken).

Preventing Duplicate Processing

When working with an At Least Once message bus, there’s the possibility that two instances may receive the same message. Additionally, when we implement resumption of failed jobs for requirement #8 there will be an even greater risk of duplicate processing. However, having the same job processed at the same time by more than one instance is usually a bad thing.

We need to use a distributed mutex to ensure that only one instance may be working on a job at a time. When we start processing the job, we’ll request a mutex. If it’s denied, then the job is in process somewhere else and we skip it. If the mutex is issued, we hold it until we get done processing the job.

Note: This logic uses the Couchbase.Extensions.Locks package, which I’ve blogged about before.

First, we add this method to JobRepository:

public Task<ICouchbaseMutex> LockJobAsync(long id, TimeSpan expiration)
{
    return _bucket.RequestMutexAsync(Job.GetKey(id), expiration);
}

Then, we alter the ExecuteJobAsync method in JobService to wrap the work in the mutex.

public async Task ExecuteJobAsync(long id, CancellationToken token)
{
    try
    {
        using (var mutex = await _jobRepository.LockJobAsync(id, TimeSpan.FromMinutes(1)))
        {
            mutex.AutoRenew(TimeSpan.FromSeconds(15), TimeSpan.FromHours(1));

            // Once we have the lock, reload the document to make sure it's still pending
            var job = await _jobRepository.GetJobAsync(id);
            if (job.Status == JobStatus.Complete)
            {
                return;
            }

            // Update the status to Running
            job.Status = JobStatus.Running;
            await _jobRepository.UpdateJobAsync(job, null);

            // We're just emulating a long running job here, so just delay
            await Task.Delay(TimeSpan.FromSeconds(45), token);

            // To emulate a failed job, either throw an exception here
            // Or stop the app before the delay above is reached

            // Finish creating the star
            await _starRepository.CreateStarAsync(job.CreateStar);

            // Update the job status document
            job.Status = JobStatus.Complete;
            await _jobRepository.UpdateJobAsync(job, TimeSpan.FromDays(1));
        }
    }
    catch (CouchbaseLockUnavailableException)
    {
        // Ignore and skip processing
    }
}

Note: It’s particularly important to reload the Job from the data store and check its status before processing. This should be done within the mutex in case another instance is finishing the job just as this instance is trying to start the job.

Preventing Oversubscription

Requirement #6 states that a single application instance shouldn’t oversubscribe and process too many jobs at once. If an instance were to do this, too many CPU cycles could be spent on job processing to the detriment of HTTP response time.

The current implementation already limits an instance to one job at a time, but let’s say we wanted to make it 2. This change to JobProcessor solves it.

private readonly SemaphoreSlim _concurrencyLimiter = new SemaphoreSlim(2);

private async Task Poll()
{
    while (!_cts.IsCancellationRequested)
    {
        try
        {
            await _concurrencyLimiter.WaitAsync(_cts.Token);

#pragma warning disable 4014
            _jobService.ProcessNextJobAsync(_cts.Token)
                .ContinueWith(t =>
                {
                    _concurrencyLimiter.Release();

                    if (t.IsFaulted)
                    {
                        _logger.LogError(t.Exception, "Unhandled exception in JobPoller");
                    }
                }, _cts.Token);
#pragma warning restore 4014
        }
        catch (OperationCanceledException)
        {
            // Ignore
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Unhandled exception in JobPoller");
        }
    }
}

Of course, better yet the limit should be configurable using IOptions<T>!

Resuming Jobs

At this point, the only requirement we’re missing is #8, resuming failed jobs on another instance. However, it’s one of the most important requirements! Modern cloud infrastructures must be built to be highly fault tolerant, and should built on the premise of when a failure happens, not if.

To address resuming, we’ll have a single application instance run a query every minute looking for jobs that are not flagged as Completed. It will test for a mutex on each job to see if it’s already running, and if not refire the message into the message bus. A mutex issued to a failed application instance will eventually expire, causing the message to fire and another available instance to resume the work.

We’ll also use another mutex for this process itself, so that only one instance tries it every minute. This will prevent every instance from firing multiple events for the same job at the same time.

public class JobRecoveryPoller : IDisposable
{
    private static readonly TimeSpan PollInterval = TimeSpan.FromMinutes(1);

    private readonly JobService _jobService;
    private readonly JobRepository _jobRepository;
    private readonly ILogger<JobRecoveryPoller> _logger;
    private readonly IBucket _bucket;

    private readonly CancellationTokenSource _cts = new CancellationTokenSource();

    private bool _started;
    private bool _disposed;


    public JobRecoveryPoller(JobService jobService, JobRepository jobRepository, IDefaultBucketProvider bucketProvider,
        ILogger<JobRecoveryPoller> logger)
    {
        _jobService = jobService ?? throw new ArgumentNullException(nameof(jobService));
        _jobRepository = jobRepository ?? throw new ArgumentNullException(nameof(jobRepository));
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));

        _bucket = bucketProvider.GetBucket();
    }

    public void Start()
    {
        if (_disposed)
        {
            throw new ObjectDisposedException(nameof(JobProcessor));
        }

        if (!_started)
        {
            Task.Run(Poll);

            _started = true;
        }
    }

    public void Dispose()
    {
        if (!_disposed)
        {
            _cts.Cancel();

            _disposed = true;
        }
    }

    public async Task Poll()
    {
        while (!_cts.IsCancellationRequested)
        {
            try
            {
                // Wait for the poll interval
                await Task.Delay(PollInterval, _cts.Token);

                // Take out a lock for job recovery polling
                // Don't dispose so that it holds until it expires after PollInterval
                // This will ensure only one instance of the app polls every poll interval
                await _bucket.RequestMutexAsync("jobRecoveryPoller", PollInterval);

                var jobs = await _jobRepository.GetIncompleteJobsAsync();
                foreach (var job in jobs)
                {
                    try
                    {
                        // Try to lock the job to see if it's being processed currently
                        using (_jobRepository.LockJobAsync(job.Id, TimeSpan.FromSeconds(1)))
                        {
                        }

                        // Make sure we've unlocked the job before we get here
                        // And fire events into the message bus for the unhandled job
                        // This allows any instance with capacity to pick up the job
                        _jobService.QueueJob(job.Id);
                    }
                    catch (CouchbaseLockUnavailableException)
                    {
                        // Job is already being processed, ignore
                    }
                }
            }
            catch (OperationCanceledException)
            {
                // Ignore
            }
            catch (CouchbaseLockUnavailableException)
            {
                // Unable to lock for singleton job recovery poller process, ignore
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Unhandled exception in JobRecoveryPoller");
            }
        }
    }
}

We just need to alter our startup code again to start and dispose the recovery poller.

var jobProcessor = app.ApplicationServices.GetRequiredService<JobProcessor>();
jobProcessor.Start();

var jobRecoveryPoller = app.ApplicationServices.GetRequiredService<JobRecoveryPoller>();
jobRecoveryPoller.Start();

var appLifetime = app.ApplicationServices.GetRequiredService<IApplicationLifetime>();
appLifetime.ApplicationStopping.Register(() =>
{
    jobProcessor.Dispose();
    jobRecoveryPoller.Dispose();
});

Conclusion

As you can see, handling long running jobs in a microservice architecture can be a bit tricky. Hopefully, having this pattern to use as a starting point will make things easier for you.

Here are a few improvements to consider in a real world implementation. I left these off intentionally so that I could focus on the key aspects of the requirements.

Support for multiple different types of jobs
Interfaces for the repositories and services at allow for mocking in unit tests
An actual message bus (duh!)
Put the pattern into a reusable Nuget package (If there’s enough interest, I might do this myself)

If anyone sees any problems with my code or approach, please let me know so I can make updates.

Note: The completed and runnable example is available at https://github.com/brantburnett/CouchbaseRestfulJobPattern.

Using Amazon Elastic Container Service for Kubernetes (EKS) on Windows 10

2018-11-08T14:45:00+00:00

At CenterEdge Software, we currently operate our Kubernetes clusters on AWS. We manage the clusters ourselves, using the kops tool. Unfortunately, managing your own Kubernetes cluster adds a lot of overhead.

Therefore, I recently embarked on a proof of concept using Amazon Elastic Container Service for Kubernetes, a.k.a. EKS. I quickly found that a significant friction point in this process was my Windows 10 laptop, which is a problem since CenterEdge Software is a Microsoft shop.

Below I share some of the steps I found that helped along the way. I won’t cover setting up the EKS cluster itself, I’ll let the AWS documentation handle that.

Prerequisites

Install kubectl and the AWS CLI. I used Chocolatey to install both.

 choco install -y kubernetes-cli
 choco install -y awscli

Configure AWS CLI with your credentials
```
 aws configure
```

Setting Up AWS IAM Authenticator

When using EKS, kubectl must be configured to use the AWS IAM Authenticator. This lightweight utility is called by kubectl to get authentication tokens, and uses your credentials configured for the AWS CLI. It can support IAM roles and multiple profiles, but for this example I’ll keep it simple and assume we’re using the default profile configured via aws configure.

Download the authenticator. The current URL for Windows is https://amazon-eks.s3-us-west-2.amazonaws.com/1.11.5/2018-12-06/bin/windows/amd64/aws-iam-authenticator.exe, but you may want to find the up-to-date version here.
Place aws-iam-authenticator.exe somewhere in your system path. For example, I was lazy and put it in C:\ProgramData\Chocolatey\bin.
Right-click on aws-iam-authenticator.exe, select Properties, and Unblock the file so it can be executed.
Confirm that the command is working from a new shell window:
```
 aws-iam-authenticator --help
```

Update: I updated some of the links above, and here is a script to download aws-iam-authenticator and add it to your path:

$installDir = "${env:LOCALAPPDATA}\aws-iam-authenticator"
$version = "1.11.5/2018-12-06"
 
New-Item -ItemType Directory $installDir -ErrorAction SilentlyContinue
 
Invoke-WebRequest -OutFile $installDir\aws-iam-authenticator.exe -UseBasicParsing "https://amazon-eks.s3-us-west-2.amazonaws.com/$version/bin/windows/amd64/aws-iam-authenticator.exe"
 
Unblock-File $installDir\aws-iam-authenticator.exe
 
$path = [Environment]::GetEnvironmentVariable("PATH", [EnvironmentVariableTarget]::User) -split ";"
if ($path -inotcontains $installDir) {
  $path += $installDir
  [Environment]::SetEnvironmentVariable("PATH", $path -join ";", [EnvironmentVariableTarget]::User)
 
  $env:PATH = (([Environment]::GetEnvironmentVariable("PATH", [EnvironmentVariableTarget]::Machine) -split ";") + $path) -join ";"
}

Adding Your Cluster To Your Kubernetes Config

The easiest way to add your cluster to your Kubernetes configuration is using the AWS CLI. It’s also possible to keep multiple configuration files, but I prefer having multiple contexts inside my default configuration file.

# Substitute "brant" below with the name of your EKS cluster
aws eks update-kubeconfig --name brant

However, after this is complete I recommend changing the name of the created context to be more usable. The first parameter below is the name of the context output by the update-kubeconfig command. The second is the new name.

kubectl config rename-context arn:aws:eks:us-east-1:000000000000:cluster/brant brant

Finally, test it out!

kubectl get svc

Working From Ubuntu on Windows using WSL

Unfortunately, many tools you may wish to use are Linux tools and don’t work well from Windows. An easy solution is to install Ubuntu on Windows 10. However, making your previous configuration for EKS work in Ubuntu requires a few more steps.

Install [kubectl]https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-binary-using-native-package-management) in Ubuntu.
Add a KUBECONFIG environment variable to your Windows user profile (alter the path below if needed):
```
 setx KUBECONFIG ${env:USERPROFILE}\.kube\config
```

Configure WSL to pass KUBECONFIG into Ubuntu, while remapping the path:

 # WSLENV is a colon-separated list of environment variables to copy to Ubuntu from your Windows Profile
 # Appending "/p" to the variable name tells WSL that the variable is a path, and to remap the path to the Ubuntu path when it's copied
 setx WSLENV $($(if ([System.String]::IsNullOrWhitespace(${env:WSLENV})) { "" } else { ${env:WSLENV} + ":"}) + "KUBECONFIG/p")

Restart Ubuntu
Test it out. Kubectl will run in Ubuntu, which in turn executes the Windows aws-iam-authenticator.exe process to get the authentication token.
```
 kubectl get svc
```

Conclusion

At this point, you should have complete access to your EKS cluster via kubectl from both Powershell and Ubuntu Bash. Now the real fun can begin!

Concurrency, Locks, the Cloud, and Couchbase

2018-11-04T15:30:00+00:00

In an application that supports parallel processing, concurrency management is almost invariably required. There are many forms of parallel processing, including multithreading, multiple processes, or multiple servers. In the case of multithreading, different languages/frameworks will generally provide highly efficient in-process locks. For multiple process scenarios, such as NodeJS using the cluster module, there are various options which use interprocess communication.

What About Multiple Servers?

These days it feels like every application is designed to run in the cloud. Applications designed for the cloud are built, from the ground up, to support running multiple copies of the application on multiple servers. Or at least, they should be. If you’re building a cloud app that isn’t designed for horizontal scaling, I’ll go out on a limb and say you’re doing it wrong.

So how should a distributed application handle locks and concurrency? Many scenarios can still take advantage of in-process locks. For example, Linq2Couchbase uses in-process locks to cache reflection results to improve performance. Since the cache is kept separately in-process on each server, the locks may be in-process. In fact, they should be in-process whenever possible to maintain performance.

However, these are not the only concurrency scenarios. In my work on microservices and other cloud architectures, I have frequently encountered scenarios where distributed locks are preferable or required. For example:

Refreshing/managing shared caches stored in a cache cluster. If there are multiple requests that miss the cache at the same time, it may be desirable to have only one server/request refresh the cache to keep load low.
Managing distributed jobs. For example, only one server in the cluster may run a job at once, but the servers “negotiate” which server runs the job via locks. Lock expiration may also be used to resume the job if a server fails unexpectedly.
Scheduled task management. A task may need to run once an hour, but only one server in your cluster should execute the task.

Distributed Locks and Couchbase

There are many solutions available for distributed locks, but at CenterEdge Software we specifically wanted an option powered by Couchbase. We already use Couchbase as our primary data store in the cloud, so using Couchbase avoids the need to spin up an additional HA cluster just to manage locks.

Couchbase’s CP architecture makes it ideal for managing distributed locks. Because each document has a single server responsible for it, and updates are atomic, we can safely assume that two servers cannot mutate the same document simultaneously. There may be edge cases during server failover, but during normal operations, or even rebalance operations, consistency will be maintained.

Couchbase.Extensions.Locks

To help manage distributed locks in Couchbase, I created the Couchbase.Extensions.Locks NuGet package. This package has kindly been adopted by the Couchbase SDK team (thanks guys!) so that all C# developers can take advantage of this lightweight abstraction layer. It’s currently in beta to give the community a chance to perform testing, but it is running in production successfully at CenterEdge Software today.

At this time, Couchbase.Extensions.Locks only supports mutexes, a.k.a. Mutual Exclusion. This assures developers that only one thread of one application instance is within a critical section at a time. Future iterations may add other forms of concurrency control.

The supplied mutexes also require an expiration. This protects against indefinite locks due to application failure. There are built-in utilities to assist with renewing the mutex if your process is long running.

using (var mutex = await bucket.RequestMutexAsync("my-lock-name", TimeSpan.FromSeconds(10) /* expiration */))
{
    mutex.AutoRenew(TimeSpan.FromSeconds(5) /* renewal interval */, TimeSpan.FromMinutes(1) /* maximum lifetime */);

    while (true)
    {
        // Do some work here

        // This lock will be held until the end of the using statement,
        // so long as the total loop time is less than one minute
        // If the application crashes, the lock will be released within 10 seconds.
    }
}

Complete instructions are available in the GitHub repository, including several usage patterns. This includes a pattern for retries in case the lock is unavailable initially. In this case I chose a pattern using Polly, I intentionally did not build the pattern into the Locks package. This allows developers to choose their favorite retry pattern and library, without introducing a specific dependency into the Locks package.

Using an memcached bucket for locks, or ephemeral for Couchbase Server Enterprise Edition 5.0 or later, is preferable. There generally isn’t a need for lock documents to be persisted to disk, so this avoids unnecessary overhead on the cluster. If the bucket is configured for NRU (not recently used) ejection, make sure the locks are short-lived or have a fast renewal rate. This will ensure they aren’t ejected, thereby releasing the lock, unexpectedly.

Conclusion

For C# developers, there is now a standard package which delivers simple and lightweight distributed mutexes via a Couchbase cluster. I’m hopeful that that developers using other languages, such as Node or Go, may make similar packages using the same document schema. This would allow locks to be shared between any microservice in an application, regardless of language.

Please feel free to file GitHub issues if you find any bugs or have suggestions, and let me know on Twitter if you like it! We’ll probably roll an official release after we’ve collected some feedback and fixed any issues.

RandomDev

Generic Type Construction With Static Virtual Interface Members

The Backstory

The Problem

Enter Static Virtual Interface Members

Conclusion

Using Roslyn to Power C# SDK Generation from OpenAPI Specifications

What is Roslyn

Performance

Extensibility

Extensibility and JSON Serialization

Embedded Source Code

Other Functionality

Future Work

Conclusion

String Interpolation Trickery and Magic with C# 10 and .NET 6

Interpolated String Handler Overview

Custom Interpolated String Handlers

Now Bring On The Magic

An Example: Parameterized SQL Queries

Example Implementation

Other Random Ideas

Random Idea #1: JSON Building Without POCOs

Random Idea #2: Safely Building HTML

Random Other Idea #3: Hash Codes

Conclusion

C# 9 Records and Init Only Settings Without .NET 5

TL;DR

What are Records?

What are init only setters?

Requirements to Create Records and Init Only Setters

LangVersion 9

Creating Init Only Properties on Older Frameworks

Creating Records on Older Frameworks

Consuming Records and Init Only Properties

Private Members

Public Init Only Setters

Public Records

Summary

Conclusion

Reclaiming HD Space from Docker Desktop on WSL 2

Freeing up space within Docker

Reclaiming the space for Windows

Side note

Conclusion

IAsyncEnumerable Is Your Friend, Even In .NET Core 2.x

TL;DR

Why use IAsyncEnumerable<T>?`

When Not To Use IAsyncEnumerable

Returning an IAsyncEnumerable in C# 8

Consuming an IAsyncEnumerable in C# 8

Special Compatibility Concerns

Can I Use IAsyncEnumerable When Targeting .NET Core 2.x?

Can I Use IAsyncEnumerable When Targeting .NET Framework

What About NuGet Packages?

What about LINQ?

Conclusion

Blue/Green Message Bus Handling on Kubernetes with Shawarma

TL;DR

The Problem

Possible Solutions

The Shawarma Solution

Shawarma Implementation

Application State in ASP.NET Core

Conclusion

A Restful Job Pattern For A C# Microservice

The Architecture

The Requirements

The Job Document

Performing The Action

Preventing Duplicate Processing

Preventing Oversubscription

Resuming Jobs

Conclusion

Using Amazon Elastic Container Service for Kubernetes (EKS) on Windows 10

Prerequisites

Setting Up AWS IAM Authenticator

Adding Your Cluster To Your Kubernetes Config

Working From Ubuntu on Windows using WSL

Conclusion

Why use `IAsyncEnumerable<T>`?`