But there's also value in test code being easy to read and understand. When a test breaks you want to quickly see what it is doing and what failed. And that is not going to happen if the test code is long and unstructured. And the only way to achieve that is to treat your test code the same way as your production code: as its complexity is growing you should refactor it.

Let's take a look at a test from my previous blog post:

[Test]
public async Task SlowResponseAfterPointOfNoReturnTest()
{
    SetUpApiResponses(TimeSpan.FromSeconds(0.6), TimeSpan.FromSeconds(0.6));

    using var httpClient = _factory.CreateClient();

    var stopwatch = Stopwatch.StartNew();
    var response = await httpClient.PostAsync(
        "/submissions",
        new StringContent(string.Empty)
    );
    stopwatch.Stop();
    response.EnsureSuccessStatusCode();
    var submissionFromCreate = await response
        .Content
        .ReadFromJsonAsync<Submission>();
    Assert.That(stopwatch.ElapsedMilliseconds, Is.InRange(1000, 1100));
    Assert.That(submissionFromCreate, Is.Not.Null);
    Assert.That(submissionFromCreate.Id, Is.Not.EqualTo(Guid.Empty));
    Assert.That(submissionFromCreate.Phase1CompletedAt, Is.Not.Null);
    Assert.That(submissionFromCreate.Phase2CompletedAt, Is.Null);

    await Task.Delay(TimeSpan.FromSeconds(1));

    var submissionFromGet = await httpClient.GetFromJsonAsync<Submission>(
        $"/submissions/{submissionFromCreate.Id}"
    );
    Assert.That(submissionFromGet, Is.Not.Null);
    Assert.That(submissionFromGet.Id, Is.EqualTo(submissionFromCreate.Id));
    Assert.That(submissionFromGet.Phase1CompletedAt, Is.Not.Null);
    Assert.That(submissionFromGet.Phase2CompletedAt, Is.Not.Null);
}

The test is rather short but there is still some effort required to fully understand what is happening. The code in between the assertion blocks has many responsibilities: it initializes the test case, it makes REST calls, it measures time. This makes it difficult to see what is the actual test scenario.

With some refactoring this can be significantly improved:

[Test]
public async Task SlowResponseAfterPointOfNoReturnTest()
{
    var scenario = new SubmissionScenario(
        _application,
        TimeSpan.FromSeconds(0.6),
        TimeSpan.FromSeconds(0.6)
    );

    var submissionFromCreate = await scenario.CreateSubmissionAsync();
    Assert.That(scenario.LastResponseTimeMilliseconds, Is.InRange(1000, 1100));
    Assert.That(submissionFromCreate, Is.Not.Null);
    Assert.That(submissionFromCreate.Id, Is.Not.EqualTo(Guid.Empty));
    Assert.That(submissionFromCreate.Phase1CompletedAt, Is.Not.Null);
    Assert.That(submissionFromCreate.Phase2CompletedAt, Is.Null);

    await Task.Delay(TimeSpan.FromSeconds(1));

    var submissionFromGet = await scenario.GetSubmissionAsync();
    Assert.That(submissionFromGet, Is.Not.Null);
    Assert.That(submissionFromGet.Id, Is.EqualTo(submissionFromCreate.Id));
    Assert.That(submissionFromGet.Phase1CompletedAt, Is.Not.Null);
    Assert.That(submissionFromGet.Phase2CompletedAt, Is.Not.Null);
}

I have moved the low-level code for making REST calls and measuring response times into separate clearly-named methods. It's now much easier to see that the test only creates a submission and retrieves it after a short delay.

The new helper methods hide all the low-level implementation details:

public async Task<Submission?> CreateSubmissionAsync()
{
    var stopwatch = Stopwatch.StartNew();
    var response = await _httpClient.PostAsync(
        "/submissions",
        new StringContent(string.Empty)
    );
    stopwatch.Stop();
    LastResponseStatusCode = response.StatusCode;
    LastResponseTimeMilliseconds = stopwatch.ElapsedMilliseconds;
    if (!response.IsSuccessStatusCode)
    {
        return null;
    }
    var submission = await response.Content.ReadFromJsonAsync<Submission>();
    if (submission != null)
    {
        _lastSubmissionId = submission.Id;
    }
    return submission;
}

public async Task<Submission?> GetSubmissionAsync()
{
    return await _httpClient.GetFromJsonAsync<Submission>(
        $"/submissions/{_lastSubmissionId}"
    );
}

The methods return only REST responses and store all the other details as local state for easy access from assertions. Even the submission ID is stored locally so that you don't need pass it from one method to the other.

I've also moved all the setup code from the test class:

• The setup method to the same scenario class that hosts the two methods above:

  public class SubmissionScenario : IDisposable
  {
      private readonly WebApplicationUnderTest _application;
      private readonly HttpClient _httpClient;
  
      public SubmissionScenario(
          WebApplicationUnderTest application,
          TimeSpan phase1Delay,
          TimeSpan phase2Delay
      )
      {
          _application = application;
          _httpClient = _application.Factory.CreateClient();
          SetUpApiResponses(phase1Delay, phase2Delay);
      }
  
      // ...
  
      public void Dispose()
      {
          _httpClient.Dispose();
      }
  }
  

• And the code for starting the web application under test to a separate class so that it could be used from different scenario classes:

  public class WebApplicationUnderTest : IDisposable
  {
      public WebApplicationFactory<Program> Factory { get; }
      public WireMockServer Server { get; }
  
      public WebApplicationUnderTest()
      {
          Server = WireMockServer.Start();
          Factory = new WebApplicationFactory<Program>()
              .WithWebHostBuilder(builder =>
              {
                  builder.ConfigureAppConfiguration(
                      (_, config) =>
                      {
                          config.AddInMemoryCollection(
                              new Dictionary<string, string?> {
                                  ["BaseAddress"] = Server.Url
                              }
                          );
                      }
                  );
              });
      }
  
      public void Dispose()
      {
          Factory.Dispose();
          Server.Dispose();
      }
  }
  

This way the test class is only responsible for the test cases it contains. And it's now much easier to share the helper code between multiple test classes if needed without resorting to inheritance and deriving all test classes from a common base class.

I suggest you clone the test project from my GitHub repository and look at it in your favorite IDE. It should make it much easier to see how the code is structured. You can also check how I improved the other tests in the project. And even inspect the exact changes I made to the original unstructured tests since those are still available in the repository as a separate commit.

With some minimum refactoring effort I managed to make the tests much more readable. Of course, further improvements could be made:

• The long blocks of assertions which repeat a lot across all tests could be moved to custom assertions.
• A separate builder class for the scenario would make the initialization code even easier to understand, especially as the number of parameter grows.

The core of my original solution was a method with the following structure:

public async Task<Guid> CreateAsync()
{
    var submission = new Submission(Guid.NewGuid(), null, null);

    var cancellationTokenSource = new CancellationTokenSource();
    cancellationTokenSource.CancelAfter(TimeSpan.FromSeconds(1));
    Task[] tasks =
    [
        ProcessAsync(submission, cancellationTokenSource.Token),
        Task.Delay(TimeSpan.FromSeconds(1), CancellationToken.None),
    ];
    await Task.WhenAny(tasks);

    return submission.Id;
}

The same timeout period was specified in two places:

• the CancellationTokenSource and in turn its cancellation token which is passed into the actual worker method ProcessAsync, and
• the Task.Delay call which defines how long we wait for the worker method to complete.

The request timeouts middleware hooks into the HttpContext.RequestAborted cancellation token and makes sure that it requests cancellation not only when the underlying connection is aborted but also when the specified timeout expires.

So instead of creating the cancellation token inside the wrapper method, it should now be passes into the method from the controller:

public async Task<Guid> CreateAsync(CancellationToken cancellationToken)
{
    var submission = new Submission(Guid.NewGuid(), null, null);

    Task[] tasks =
    [
        ProcessAsync(submission, cancellationToken),
        Task.Delay(TimeSpan.FromSeconds(1), CancellationToken.None),
    ];
    await Task.WhenAny(tasks);

    return submission.Id;
}

But even after this change, we still rely on a separate Task.Delay call to stop waiting for the ProcessAsync method to complete. We don't want that because the delay value is defined independently from the request timeout configuration.

Fortunately, there is a simpler way to stop waiting for ProcessAsync to complete and keep it running in the background which I could have used even in my original solution:

public async Task<Guid> CreateAsync(CancellationToken cancellationToken)
{
    var submission = new Submission(Guid.NewGuid(), null, null);
    try
    {
        await ProcessAsync(submission, cancellationToken)
            .WaitAsync(cancellationToken);
    }
    catch (OperationCanceledException)
        when (cancellationToken.IsCancellationRequested)
    {
        // The request timeout elapsed,
        // but processing may continue in the background
    }
    return submission.Id;
}

The task returned by WaitAsync will complete either when the original task (i.e., the ProcessAsync method) completes or when the cancellation token requests the cancellation, whichever comes first. Which matches exactly what I achieved in the original implementation using Task.Delay.

Notice how I need to ignore the OperationCanceledException thrown when awaiting the WaitAsync method. Otherwise the exception would have been thrown from this method instead of the value being returned.

Of course, there is some setup required to use the request timeouts middleware:

builder.Services.AddRequestTimeouts();
// ...
app.UseRequestTimeouts();

And in the controller, the cancellation token has to be retrieved and passed along:

[HttpPost]
[RequestTimeout(1000)]
public async Task<IActionResult> Create()
{
    var submissionId = await submissionsService.CreateAsync(
        HttpContext.RequestAborted
    );
    // ...
}

In this particular case, I specified the request timeout with an attribute on the action method, but I could also do it at the controller level or with a global default.

I have a fully working sample project in my GitHub repository. The tests cover all three possible outcomes:

• the worker method completes before the timeout expires,
• the timeout expires before the worker method reaches the point of no return, so the method aborts,
• the timeout expires after the worker method reaches the point of no return, so the method continues in the background.

Check my next blog post how I refactored these tests to make them easier to understand.

You might wonder why I haven't used this approach in my old blog post. For some reason, I have only recently learned about the request timeouts middleware although it has been available since .NET 8. That's also why I decided to now revisit the topic once more.

I was dealing with a field that could be serialized into two different JSON types, depending on its contents. It could be serialized as string:

{
  "Version": "1.0.0"
}

Or, it could be serialized as a number:

{
  "Version": 1
}

A union type is dedicated to modeling data which can be represented as one of multiple types, in this case a string or a number. And if you need to always access it as a string as I did, you can add custom property for that:

public union StringOrNumber(string, long)
{
    public string? StringValue => this switch
    {
        string stringValue => stringValue,
        long longValue => longValue.ToString(),
        null => null
    };
}

You can now use this type to model the multi-type field in the JSON object:

public class AppInfo
{
    public StringOrNumber Version { get; init; }
}

With this setup, the deserialized value is typed correctly for both of the above cases, i.e., string or number, respectively. And the StringValue returns its string equivalent:

[Test]
public void DeserializesStringValue()
{
    const string json = """{"Version":"1.0.0"}""";

    var appInfo = JsonSerializer.Deserialize<AppInfo>(json);

    Assert.That(appInfo, Is.Not.Null);
    Assert.That(appInfo.Version.Value, Is.EqualTo("1.0.0"));
    Assert.That(appInfo.Version.StringValue, Is.EqualTo("1.0.0"));
}

[Test]
public void DeserializesNumericValue()
{
    const string json = """{"Version":1}""";

    var appInfo = JsonSerializer.Deserialize<AppInfo>(json);

    Assert.That(appInfo, Is.Not.Null);
    Assert.That(appInfo.Version.Value, Is.EqualTo(1));
    Assert.That(appInfo.Version.StringValue, Is.EqualTo("1"));
}

And if the Version field is missing or set to null, the typed and string value are also both null. Only the union type is non-null since it's a value type:

[Test]
public void DeserializesMissingValue()
{
    const string json = """{"Version":null}""";

    var appInfo = JsonSerializer.Deserialize<AppInfo>(json);

    Assert.That(appInfo, Is.Not.Null);
    Assert.That(appInfo.Version.Value, Is.EqualTo(null));
    Assert.That(appInfo.Version.StringValue, Is.EqualTo(null));
}

You can find a sample project with all code from this blog post in my GitHub repository. It includes the tests for serialization as well. It works as expected without any additional code.

Union types are a useful addition to C#. Some scenarios which required special handling in the past now just work out of the box. To try them out, you will need the latest .NET 11 SDK pre-release, Release Candidate 1 at the time of writing. It comes even with a go-live support license, so you can deploy it to production if you feel courageous. I would suggest you wait at least until the final release in November, though.

Labeled break and continue statements are useful exclusively in nested loops to make exiting from inner loops simpler and more readable. Here's a small example taking advantage of the new syntax:

outer: for (var row = 0; row < values.GetLength(0); row++)
{
    for (var col = 0; col < values.GetLength(1); col++)
    {
        cellsProcessed++;
        if (shouldContinue(values[row,col]))
            continue outer;
        if (shouldBreak(values[row, col]))
            break outer;
    }
    rowsProcessed++;
}

Notice the outer label on the outer for loop. It's being referenced from the continue and break statements inside the inner for loop. Without the labels the two statements would affect the inner loop. With the labels, they affect the outer loop.

Before C# 15, equivalent code could best be written using goto statements:

for (var row = 0; row < values.GetLength(0); row++)
{
    for (var col = 0; col < values.GetLength(1); col++)
    {
        cellsProcessed++;
        if (shouldContinue(values[row,col]))
            goto outer_continue;
        if (shouldBreak(values[row, col]))
            goto outer_break;
    }
    rowsProcessed++;
    outer_continue: ;
}

outer_break: ;

The code isn't much different but its semantics aren't as obvious. The two labels (outer_continue and outer_break) mark the spot to jump to instead of the loop being affected. And the goto statement intention is less clear than the intention of continue and break statements. Naming the labels appropriately helps somewhat, though.

If you wanted to avoid using goto statements because they are considered harmful, the code would get even more convoluted:

for (var row = 0; row < values.GetLength(0); row++)
{
    var continueFlag = false;
    for (var col = 0; col < values.GetLength(1); col++)
    {
        cellsProcessed++;
        if (shouldContinue(values[row, col]))
        {
            continueFlag = true;
            break;
        }
        if (shouldBreak(values[row, col]))
        {
            breakFlag = true;
            break;
        }
    }

    if (breakFlag)
        break;
    if (!continueFlag)
        rowsProcessed++;
}

Admittedly, this is a direct rewrite of the original code from above without labels. It could probably be somewhat improved with further refactoring but the intention of the code still wouldn't be as clear as in the version with labeled continue and break statements.

As all C# 15 language features, labeled continue and break statements are still in preview and could change before C# 15 is released. With .NET 11 preview 7, you have to set the language version to preview in your project to use them:

<PropertyGroup>
  <LangVersion>preview</LangVersion>
</PropertyGroup>

I have created a sample project with the three code snippets above slightly expanded and covered with tests. You can clone it from my GitHub repository.

I don't think labeled continue and break statements will be used much, just like goto statements don't seem to be. However, in the very specific scenarios they are addressing, using them is worth it as it can make code easier to write and understand.

Extension methods have been added to C# as a part of LINQ a long time ago. In essence, they were static methods which could be called as if they were members of the type of their first parameter:

public static string? FirstCharToUpper(this string? receiver)
{
    return string.IsNullOrEmpty(receiver)
        ? receiver
        : string.Concat(receiver[..1].ToUpper(), receiver.AsSpan(1));
}

They had to be placed in a static class and the first parameter had to be introduced with this keyword. Such a method could be called as a member method of its first parameter which therefore didn't have to be passed in as a parameter:

"me".FirstCharToUpper()

The extension members feature of C# 14 added support for adding other member types as extensions. To make this possible, the syntax for declaring them had to be different from the existing extension method syntax. Their syntax is more similar to regular type members, but they have to be inside an extension block, in a static class. The old syntax is still supported for extension instance methods, but a new one was added to match the syntax of other extension member types:

extension(string? receiver)
{
    public string? FirstCharToUpper()
    {
        return string.IsNullOrEmpty(receiver)
            ? receiver
            : string.Concat(receiver[..1].ToUpper(), receiver.AsSpan(1));
    }
}

Other supported member types were:

• instance properties:

  extension(string? receiver)
  {
      public bool IsEmptyField =>
          string.IsNullOrEmpty(receiver) || receiver == "N/A";
  }
  

• static methods:

  extension(string?)
  {
      public static string? Create(string? pattern, int count)
      {
          if (pattern == null)
          {
              return null;
          }
  
          if (pattern.Length == 0 || count <= 0)
          {
              return string.Empty;
          }
  
          var builder = new StringBuilder(pattern.Length * count);
          for (var i = 0; i < count; i++)
          {
              builder.Append(pattern);
          }
  
          return builder.ToString();
      }
  }
  

• static properties:

  extension(string?)
  {
      public static string NotAvailable => "N/A";
  }
  

• operators:

  extension(string?)
  {
      public static string? operator *(string? pattern, int count)
      {
          return string.Create(pattern, count);
      }
  }
  

In addition to all these extension member types, C# 15 now also supports extension indexers. The syntax follows the pattern of all other extension members:

extension(IEnumerable<int> sequence)
{
    public int this[int index] => sequence.ElementAt(index);
}

Just like other extension member types, extension indexers are only considered by the compiler when there are no matching actual member indexers. Even implicit Index and Range indexers have precedence over extension indexers with the same type. E.g., if a type has an int indexer and a Length or Count property, then the Index indexer is implicitly supported and an extension Index indexer will be ignored even if you implement it.

In addition to all that, extension indexers for arrays and strings will be ignored altogether as documented at the very bottom in the collapsed section of the feature specification:

The current spec and baseline rules for array access and string access mean that extension indexers don't work on arrays or strings.
Yet the declaration of such extension indexers is permitted.

Extension indexers are currently a preview feature and might still change. To use them in .NET 11 preview 7, you must set the language version to preview in your project:

<PropertyGroup>
  <LangVersion>preview</LangVersion>
</PropertyGroup>

A sample project with all supported extension member types (the ones from C# 14 and the indexers newly added in C# 15) is available in my GitHub repository. Feel free to clone it and try out the feature yourself.

With the addition of extension indexers in C# 15, the originally planned scope of extension members from C# 14 has been completed. The only remaining member type without extension support are conversion operators which aren't even planned for now as stated in the feature specification:

Does not cover user-defined implicit and explicit conversion operators, which are not yet designed or planned.

Let's start with a quick reminder, what collection expressions are. Since the early days of C#, collection types could be initialized using the collection initializer syntax. For example, an array could be initialized with:

var oldSyntax = new[] { 1, 2, 3 };

Collection expressions provide an alternative syntax (notice how the variable has to be explicitly typed so that the compiler knows which type of collection to instantiate):

int[] newSyntax = [1, 2, 3];

The new syntax also added support for the spread element to initialize a new collection as a concatenation of elements from multiple existing collections, inspired by the Javascript spread syntax:

int[] array = [1, 2];
Span<int> span = [3, 4];
List<int> list = [5, 6];
int[] finalArray = [.. array, .. span, .. list];

However, the new collection expression wasn't a full replacement for all use cases. Some collection constructors have parameters which tweak how the collection gets created. For example, a list can be created with a larger initial size, which is useful if we know in advance that more items will be added to it:

var oldSyntax = new List<int>(10) { 1, 2, 3 };

Before C# 15, the same final result couldn't be achieved using collection expression syntax. The addition of so-called collection expression arguments in C# 15 makes it possible to specify values for the collection constructor parameters. The following syntax is equivalent to the one above:

List<int> newSyntax = [with(10), 1, 2, 3];

The constructor parameters are specified using the with keyword which has to be the first element in the collection expression. Its parameters must match the parameters of a constructor of the collection type being initialized.

Collection initializers can't be used with all collections. Immutable collections are such an example. The closest alternative without using collection expressions are the builder methods with params arguments. This means that the following call invokes the Create<string>(params ReadOnlySpan<string> items) method (and called Create<string>(params string[] items) before parameter collections from C# 13 added params support to other types of collections):

var oldSyntax = ImmutableHashSet.Create("a", "b", "c");

Collection expression can invoke the same method using the syntax identical to other types of collections which support collection initializers:

ImmutableHashSet<string> newSyntax = ["a", "b", "c"];

With the addition of collection expression arguments in C# 15, collection builders with other arguments in addition to the span or array for specifying the elements to be added to the collection can now supported by the collection expression syntax. For example:

ImmutableHashSet<string> newSyntax =
[
  with(StringComparer.OrdinalIgnoreCase),
  "a",
  "A"
];

This new syntax is equivalent to the old one without collection expressions:

var oldSyntax = ImmutableHashSet.Create(StringComparer.OrdinalIgnoreCase, "a", "A");

As you can deduce from the given example, in the case of builder methods the collection expression arguments map to the builder method parameters placed before the span items parameter.

Just like all other C# 15 features, collection expression arguments are still in preview and might change before the November release. To use them in .NET 11 preview 7 you have to set the language version to preview:

<PropertyGroup>
  <LangVersion>preview</LangVersion>
</PropertyGroup>

I created a sample project with all the code from this blog post and pushed it to my GitHub repository. It's an easy way to try out this feature yourself.

Collection expression arguments are in essence only syntactic sugar. But so were collection expressions themselves and I still see them used quite regularly nowadays. WIth this new addition, collection expressions can now be used in a few more cases where they couldn't be before.

Each union type implements the IUnion interface with a single Value property:

public interface IUnion
{
    object? Value { get; }
}

To initialize the Value property, a constructor is generated for each case type, e.g.:

public Shape(Square square)
{
    Value = square;
}

This constructor is used by the implicit conversion operator which allows us to directly assign an instance of any case type to the union type:

Shape shape = new Square(2);

Since the union type is just a regular type, we can add custom members to it:

public union Shape(Square, Circle)
{
    public double Area =>
        this switch
        {
            Square square => Math.Pow(square.Length, 2),
            Circle circle => Math.PI * Math.Pow(circle.Radius, 2)
        };
}

By following the requirements for a union type we can even implement our own custom union type which supports exhaustive switch expressions just like the autogenerated one. It has to:

• implement the IUnion interface
• have a constructor for each case type with its instance as the only parameter
• return that case type instance via the Value property
• be annotated with the [Union] attribute

[Union]
public struct CustomShape : IUnion
{
    public object? Value { get; }

    public CustomShape(Square square)
    {
        Value = square;
    }

    public CustomShape(Circle circle)
    {
        Value = circle;
    }

    public static implicit operator CustomShape(Square square) => new(square);

    public static implicit operator CustomShape(Circle circle) => new(circle);
}

The implicit conversion operators are optional. If we don't implement them, the compiler will generate them for us.

But why would we even want to implement our own custom union type when the compiler can do it for us? It could be for performance reasons. The compiler-generated union type always stores the case type instance as an object just like the struct above. If our case types are value types, this means that they are boxed every time they are stored in the union type and unboxed every time they are read from it. We can avoid this with a custom union type:

[Union]
public readonly struct IntOrDouble : IUnion
{
    private enum ValueType : byte
    {
        None,
        Int,
        Double,
    }

    private readonly int _intValue;
    private readonly double _doubleValue;
    private readonly ValueType _type = ValueType.None;

    public object? Value =>
        _type switch
        {
            ValueType.Int => _intValue,
            ValueType.Double => _doubleValue,
            _ => null,
        };

    public IntOrDouble(int value)
    {
        _type = ValueType.Int;
        _intValue = value;
    }

    public IntOrDouble(double value)
    {
        _type = ValueType.Double;
        _doubleValue = value;
    }

    public bool TryGetValue(out int value)
    {
        value = _intValue;
        return _type == ValueType.Int;
    }

    public bool TryGetValue(out double value)
    {
        value = _doubleValue;
        return _type == ValueType.Double;
    }
}

Notice the two TryGetValue methods in this custom union type. When they are present, the compiler uses them in favor of the Value property when the union type is used with type matching, e.g.,

if (union is int value)
{
    // ...
}

These methods make sure that boxing and unboxing can be completely avoided. Of course, if the Value property is accessed directly, the value will still be boxed, as there is no other way to return a value type as an object.

As already mentioned in the previous blog post, union types are still in preview and can change before the final release, but they are already available to try out in .NET 11 preview 7. You have to set the language version to preview in your project for them to work:

<PropertyGroup>
  <LangVersion>preview</LangVersion>
</PropertyGroup>

You can find a sample project with all the code from this blog post and more in my GitHub repository. Feel free to clone it and play around with it.

Although you can use union types as soon as you understand their basic syntax, it's interesting to learn what the compiler does for you. And while it's unlikely that you'll need to implement your own custom union type, it's good to know that it's possible.

Before C# 15, there were several ways to return multiple different types from a method or store them in a single variable. You can use the type of the common ancestor of your types. This gives you two options for your types

1. They have to implement the same interface. If the only purpose of the interface is to provide a common ancestry (i.e., it doesn't define any members to implement), such an interface is called a marker interface:

   public interface IShape { }
   
   public record Square(double Length) : IShape;
   
   public record Circle(double Radius) : IShape;
   

2. They have to derive from the same base class (usually abstract if it's only used to provide common ancestry):

   public abstract record Shape { }
   
   public record Square(double Length) : Shape;
   
   public record Circle(double Radius) : Shape;
   

In both cases, a catch-all discard pattern has to be added to a type-based switch expression:

return shape switch
{
    Square square => Math.Pow(square.Length, 2),
    Circle circle => Math.PI * Math.Pow(circle.Radius, 2),
    _ => throw new NotSupportedException($"{shape.GetType()} is not supported."),
};

Otherwise, the following warning is generated by the compiler:

Warning CS8509 : The switch expression does not handle all possible values of its input type (it is not exhaustive). For example, the pattern _ is not covered.

Unfortunately that same discard pattern which resolves the warning also means that the compiler can't generate a warning if you add another sibling type at a later time. That type will already be covered by the discard pattern as far as the compiler is concerned.

For the abstract base class approach, C# 15 changes this with the introduction of closed class hierarchies which I explored in my previous blog post.

But what if you can't derive your types from a common ancestor (e.g., because you are using types which you haven't defined yourself)?

public record Square(double Length);

public record Circle(double Radius);

The only obvious choice before C# 15 was to use object as the return type or variable type. Since the object type doesn't constraint the type of the assigned value in any way, the compiler of course can't reason about the exhaustiveness of a switch expression and always requires a discard pattern to be added.

The OneOf library provides one possible solution for this challenge. It introduces a generic OneOf type which you can use to combine multiple unrelated types into one. You can even give a custom name to that type by taking advantage of the using alias directives:

using Shape = OneOf<Square, Circle>;

This doesn't change how switch expressions treat these type in any way. However, the OneOf type comes with a Match method which you can use instead:

return shape.Match(
    square => Math.Pow(square.Length, 2),
    circle => Math.PI * Math.Pow(circle.Radius, 2)
);

Although the syntax is different, the functionality is equivalent. But if you add another type to your OneOf type alias:

using Shape = OneOf<Square, Circle, Rectangle>;

The code won't build anymore:

Error CS7036 : There is no argument given that corresponds to the required parameter f2 of OneOf<Square, Circle, Rectangle>.Match<TResult>(Func<Square, TResult>, Func<Circle, TResult>, Func<Rectangle, TResult>)

The number of parameters of the Match method matches the number of generic type arguments in your OneOf type declaration. Therefore, when you add another type argument, you must also add another method parameter or the code won't compile. Your code won't behave incorrectly because you forgot to do that.

With C# 15 you have an alternative to the OneOf type which is built into the language: union types. Just like the OneOf type, it allows you to specify which (unrelated) types you want to work with:

public union Shape(Square, Circle);

Unlike the OneOf type, you can now use these types in a switch expression without any warnings even if you don't include a discard pattern:

return shape switch
{
    Square square => Math.Pow(square.Length, 2),
    Circle circle => Math.PI * Math.Pow(circle.Radius, 2)
};

And when you add another type to your union:

public union Shape(Square, Circle, Rectangle/);

The compiler will generate a warning if you don't handle that new type in the switch expression:

Warning CS8509 : The switch expression does not handle all possible values of its input type (it is not exhaustive). For example, the pattern Cs15UnionTypes.Union.Rectangle is not covered.

It's the same behavior as when using closed class hierarchies.

Of course, the feature is still in preview and it can change before the final release. You can already try it out in its current state with .NET 11 preview 7. To enable it, you have to set the language version to preview in your project:

<PropertyGroup>
  <LangVersion>preview</LangVersion>
</PropertyGroup>

I created a sample project with all five approaches from this post and put it in my GitHub repository. You can use it as a starting point to explore this feature on your own.

Union types are a complement to closed class hierarchies in C# 15. They both improve the experience when using type-based switch expressions, each for its own use case. Where closed class hierarchies address exhaustiveness for types with a common base type, unions do it for unrelated types. And give you a way to declare a predefined set of unrelated types to return from a method or assign to a variable or parameter.

Class hierarchies are referring to a base class and the classes derived from it. For example:

public abstract record OpenShape { }

public record OpenSquare(double Length) : OpenShape { }

public record OpenCircle(double Radius) : OpenShape { }

A switch expression can be used to handle each type differently:

var area = shape switch
{
    OpenSquare square => Math.Pow(square.Length, 2),
    OpenCircle circle => Math.PI * Math.Pow(circle.Radius, 2),
};

Although the code covers all the classes, currently derived from OpenShape, the code above still generates a compiler warning:

Warning CS8509 : The switch expression does not handle all possible values of its input type (it is not exhaustive). For example, the pattern _ is not covered.

That's because the compiler cannot be sure that the code won't encounter additional classes derived from OpenShape at runtime. Such a class could be defined in a different assembly and passed into code from the original assembly which was compiled without the knowledge of this new class. Such a class hierarchy is called an open class hierarchy because it's open for adding new classes to it. To fix the warning, a catch-all discard pattern has to be added to the switch expression which will handle any classes that are not handled explicitly:

var area = shape switch
{
    OpenSquare square => Math.Pow(square.Length, 2),
    OpenCircle circle => Math.PI * Math.Pow(circle.Radius, 2),
    _ => throw new NotSupportedException($"{shape.GetType()} is not supported."),
};

Even before C# 15, there is a way to prevent new classes from being derived from the base class in a different assembly, with access modifiers making the base class constructor inaccessible from other assemblies:

• Use internal, if you want the constructor publicly accessible in the original assembly.
• Use private protected, if you want the constructor to be protected in the original assembly, i.e., only accessible from derived classes.

public abstract record PrivateShape
{
    private protected PrivateShape() { }
}

public record PrivateSquare(double Length) : PrivateShape { }

public record PrivateCircle(double Radius) : PrivateShape { }

Trying to derive from PrivateShape in a different assembly will generate the following error:

Error CS7036 : There is no argument given that corresponds to the required parameter 'original' of 'PrivateShape.PrivateShape(PrivateShape)'

This is caused by the fact that there is now no parameterless constructor accessible. The constructor mentioned in the error message is the automatically generated copy constructor for a record.

Although this effectively ensures that no class can be derived from PrivateShape in a different assembly, the compiler will still generate a warning for a switch expression without the discard pattern.

However, C# 15 introduces a new keyword closed which can be used on a base class to disallow deriving from it in a different assembly:

public closed record ClosedShape { }

public record ClosedSquare(double Length) : ClosedShape { }

public record ClosedCircle(double Radius) : ClosedShape { }

When trying to do so, the following error will be generated:

Error CS9382 : 'ClosedRectangle': cannot use a closed type 'ClosedShape' from another assembly as a base type.

A class hierarchy with a closed class as its base is treated by the compiler as a closed class hierarchy, meaning that it is closed for adding new classes. A switch expression over such a class hierarchy doesn't require a discard catch-all pattern. The following block of code will compile without warnings:

var area = shape switch
{
    ClosedSquare square => Math.Pow(square.Length, 2),
    ClosedCircle circle => Math.PI * Math.Pow(circle.Radius, 2),
};

You might wonder what is the big deal about having or not having to add a discard pattern to a switch expression. After all, it's only a single line of code. But this line of code has an important impact on what will happen when you add another class to the hierarchy, e.g.:

public record ClosedRectangle(double Length, double Width) : ClosedShape { }

If there is a discard pattern in the switch expression, no new warnings will be generated when you add such a class. Only at run time will you notice that an exception is thrown because you forgot to handle the new class. However, without the discard pattern, a warning will be generated when you add a class to the hierarchy, notifying you immediately that you need to properly handle this new class:

Warning CS8509 : The switch expression does not handle all possible values of its input type (it is not exhaustive). For example, the pattern 'ClosedClassHierarchies.CoreLib.ClosedRectangle' is not covered.

You might also argue that you can still extend a closed class hierarchy indirectly by deriving from a derived class instead of the base class:

public record ClosedColoredSquare(Color Color, double Length)
    : ClosedSquare(Length) { }

Such a class doesn't affect the exhaustiveness of a switch expression, though. The new class will be handled by the existing ClosedSquare case.

As already mentioned, the feature is still in preview, so it can change before the final release. You can already try it out in its current state with .NET 11 preview 6. To enable it, you have to set the language version to preview in your project:

<PropertyGroup>
  <LangVersion>preview</LangVersion>
</PropertyGroup>

You can find a small sample with all the code from this article and more in my GitHub repository. Feel free to clone it and use it as a basis for experimenting with this new feature yourself.

The closed class hierarchies with the closed keywords make the type-based switch expressions safer to use. As long as you don't ignore the warnings in your project you should never again forget to modify an existing switch expression when extending a class hierarchy with a new class.

The problem was that I could only access the repository with root privileges. That was a given on my home lab server where the backups where always created by a scheduled script running in root context. On my home computer, I want to interact with the restic repository as myself without having to elevate privileges.

As I investigated further, I noticed that the files created in the repository were owned by an unknown user, i.e., a user with UID 1000 which didn't even exist on Synology. It turned out that it was the UID of my home lab server user. I haven't encountered any issues before only because the NFS mount was always used as root on my home server and therefore permissions hadn't been checked.

I started playing around with NFS security settings on Synology but I couldn't find a way to interact with the repository as my Synology user. As stated in the Synology documentation:

If AUTH_SYS security flavor is implemented: The client must have exactly the same numerical UID (user identifier) and GID (group identifier) on the NFS client and Synology NAS, or else the client will be assigned the permissions of others when accessing the shared folder. To avoid any permissions conflicts, you can select Map all users to admin from Squash or give "Everyone" permissions to the shared folder.

Of course, the user and group identifiers weren't the same across Synology, my home lab server and my home computer. And I had no interest in trying to make them the same. The available squash options in Synology UI were also rather limited: map root to admin/guest or map all users to admin/guest. As such, they didn't give me an option to map the NFS user to my Synology user without manually tinkering with the etc/exports file which I also didn't want to do.

I took a step back and looked at other ways to access the repository on my Synology NAS. I liked SFTP best because:

• It's built into both Synology and restic.
• I already used SSH to access Synology remotely.

The process of switching from NFS to SFTP was very straightforward.

First, I enabled SFTP access on my Synology. This required two configuration changes in the Control Panel.

• Enable SSH service in Terminal & SNMP > Terminal. Optionally change the Port as well. I had this one enabled already.
• Enable SFTP service in File Services > FTP > SFTP.

With Synology configured correctly, I was ready to configure the client. Since I already used SSH, I could skip some of the following steps, but I'm listing them all anyway:

• I added an entry for my Synology to ~/.ssh/config so that I didn't have to specify all the details every time I wanted to connect to it:

  Host synology
      HostName synology
      Port 2222
      User damir
  

• I created an SSH key so that I didn't have to enter the password every time:

  ssh-keygen -t ed25519 -C "me@mycomputer"
  

• I added the key to the authorized keys on Synology. This was the only time I had to enter my Synology password to connect to it. I didn't have to specify the username and port thanks to the ~/.ssh/config entry above.

  ssh-copy-id -i ~/.ssh/id_ed25519.pub synology
  

• I changed my RESTIC_REPOSITORY to sftp:synology:/restic (again no username or port needed thanks to my SSH configuration).

I followed the same steps on my home server with minor modifications because I had to do it for the root user:

• Add the SSH configuration entry to /root/.ssh/config.
• Run all commands with sudo.
• Set no passphrase for the SSH key so that it can be used from the backup script non-interactively.

Since the ownership and permissions of existing files in the restic repository were in complete disarray, I had to fix those, too:

sudo chown -R damir:users /volume1/restic/
sudo chmod -R a-rwx,u+rwX,g+rwX /volume1/restic/

This was enough to get everything working. The backup created files as my Synology user (the one I used for SSH login). And I could access the restic repository from my home computer without root privileges.

As the final step, I got rid of everything NFS related because I didn't need it anymore:

• I unmounted the NFS share and deleted the mount directory on the client:

  sudo umount /mnt/restic
  sudo rm -rf /mnt/restic
  

• Also on the client, I removed the entry for this mount from etc/fstab/.
• I deleted the NFS Permissions entry for the restic Shared Folder in Synology Control Panel.

Although at first NFS seemed the simplest option for accessing the restic repository on my Synology NAS, SFTP turned out a much better choice in the end. It only took me a year to realize that.