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.

Fortunately, there's a detailed .NET page in Arch Linux Wiki which proved very helpful for resolving my issue. According to it, I could choose between two approaches to get the .NET 11 SDK preview installed:

• do it manually using the dotnet-install script, or
• use user repository packages exclusively for installing .NET.

I chose the second approach. I first uninstalled the dotnet-sdk-10.0 package and started experimenting with AUR packages to get everything working. Even after reading the documentation, it took me a few tries before I succeeded.

In the end, I learned the following:

• I need to have either dotnet-host-bin or dotnet-host-preview-bin package installed. The former only works with stable versiosn, so the latter is required to be able to also install the preview versions.
• For each SDK version, three packages have to be installed: dotnet-sdk-bin, dotnet-runtime-bin and aspnet-runtime-bin. These three install the latest stable release, i.e., .NET 10 at the time of writing. The preview version adds preview to the package names (e.g., dotnet-sdk-preview-bin) and the older stable versions add their version number to the package names (e.g., dotnet-sdk-9.0-bin for .NET 9).

This meant that to install the SDKs for the preview version and all still supported stable versions, I had to install the following packages:

• common host package: dotnet-host-preview-bin
• .NET 11 SDK preview: dotnet-sdk-preview-bin, dotnet-runtime-preview-bin, aspnet-runtime-preview-bin
• .NET 10 SDK: dotnet-sdk-bin, dotnet-runtime-bin, aspnet-runtime-bin
• .NET 9 SDK: dotnet-sdk-9.0-bin, dotnet-runtime-9.0-bin, aspnet-runtime-9.0-bin
• .NET 8 SDK: dotnet-sdk-8.0-bin, dotnet-runtime-8.0-bin, aspnet-runtime-8.0-bin

After installing all the packages listed above, I ended up with the following SDKs on my machine:

❯ dotnet --list-sdks
8.0.423 [/usr/share/dotnet/sdk]
9.0.316 [/usr/share/dotnet/sdk]
10.0.301 [/usr/share/dotnet/sdk]
11.0.100-preview.6.26359.118 [/usr/share/dotnet/sdk]

I assume that by simply updating the already installed packages, these SDKs should be updated to their respective latest versions. I expect that I'll only have to install additional packages when .NET 11 gets released because dotnet-sdk-bin will then install .NET 11 instead and I'll have to install dotnet-sdk-10.0-bin for .NET 10.

I might also uninstall the preview packages altogether at that time since I won't be all that interested in .NET 12 until a few months before release. And of course, I'll eventually uninstall .NET 8 and .NET 9 after they aren't supported anymore.

A workflow-dispatch trigger allows a workflow to be triggered manually. When such a trigger is present in a workflow, GitHub adds a Run workflow button to its web page. In the button dropdown, the branch to run the workflow on can be selected and the values for all the workflow inputs can be set.

However, I had no such button available for my workflow even after I added a workflow-dispatch trigger to it. As I learned later, it was because I only had the workflow-dispatch trigger on the feature branch and not on the main branch, and button only show up when the trigger is present in the main branch. Of course, I didn't want to add it to the main branch, as I wanted to test everything in the feature branch first.

Fortunately, a workflow with a workflow-dispatch trigger on a non-main branch can still be triggered for that branch in other ways:

• with a REST call, or
• with GitHub CLI.

Since I'm already using GitHub CLI to create repositories for sample code for my blog posts, I liked the second option better. And it was indeed very easy to use. Since my GitHub CLI was already authenticated, I could simply invoke gh workflow run from my local repository folder and specify the workflow file, the branch and the input values, e.g.:

gh workflow run build.yml --ref feature/azure-static-web-app -f deploy=true

It turned out that once you know how, it's even easier to manually trigger a workflow with GitHub CLI than via the web page. I'm likely going to use it now even when I could run it from the web page just because it's more convenient.

In IIS, I used URL rewrite module to implement it:

<rule name="Redirect to www">
    <match url=".*" />
    <conditions logicalGrouping="MatchAny">
        <add input="{HTTP_HOST}" pattern="^(www\.)(.*)$" negate="true" />
    </conditions>
    <action type="Redirect" url="https://www.{HTTP_HOST}/{R:0}" redirectType="Permanent"/>
</rule>

For Azure Static Web App, I ended up doing it as part of my custom domain setup. First, I had set up both custom domains: www and apex.

The simper of the two was the www subdomain:

• In my DNS configuration I had to add a CNAME entry pointing at the autogenerated azurestaticapps.net URL of my Azure Static Web App listed on its Overview page in Azure Portal.
• On the Custom domains page of the Azure Static Web App in Azure Portal, I had to add an entry for my www domain with CNAME type. After it was validated, the web page started responding at my www subdomain.

Setting up the apex domain was a bit more involved. Since my domain registrar doesn't support ALIAS records or domain forwarding, I had to go the A record route:

• To validate the domain, I had to add an entry on the Custom domains page for my apex domain with type TXT. This generated a code for me which I had to enter as the value for the corresponding TXT entry in my DNS configuration.
• Once the TXT entry was validated, it was time to add an A entry for the apex domain in my DNS configuration. I got the value for it, i.e., the IP, in the stableInboundIP field of the JSON view on the Overview page of my Azure Static Web App in Azure Portal.

After all of this was successfully set up, it was time for the very last step: configuring the redirect from the apex domain to the www subdomain. I could achieve this by setting my www subdomain entry on the Custom domains page in Azure Portal as default. As a side effect, this also redirects any requests from the autogenerated azurestaticapps.net domain to my www custom subdomain. I don't expect (m)any such requests, but it's still nice to have this redirect in place.

I chose Jest as my testing framework or ts-jest to be precise since I used Typescript. I set it up in my api folder by simply following the instructions:

npm install --save-dev jest ts-jest @types/jest
npx ts-jest config:init

I modified my package.json to invoke jest when running npm test:

{
  "scripts": {
    "test": "jest"
  }
}

And I added jest types to my tsconfig.json so that I didn't have to import test, expect and other Jest symbols:

{
  "compilerOptions": {
    "types": ["node", "jest"]
  }
}

Since an HTTP-triggered Azure Function accepts HttpRequest and InvocationContext as parameters, I had to mock these two first to make my tests simpler.

For InvocationContext, I created a minimal mock I could use with every call. Because I prefer writing TypeScript in strict mode, I had to set all non-optional fields even if I don't need them in my code:

class MockContext implements InvocationContext {
  invocationId: string = "";
  functionName: string = "";
  extraInputs: InvocationContextExtraInputs = {
    get: function (): unknown {
      throw new Error("Function not implemented.");
    },
    set: function (inputOrName: FunctionInput | string, value: unknown): void {
      throw new Error("Function not implemented.");
    },
  };
  extraOutputs: InvocationContextExtraOutputs = {
    set: function (output: HttpOutput): void {
      throw new Error("Function not implemented.");
    },
    get: function (outputOrName: FunctionOutput | string): unknown {
      throw new Error("Function not implemented.");
    },
  };
  log(...args: any[]): void {
    console.log("[test] log:", ...args);
  }
  trace(...args: any[]): void {
    console.trace("[test] trace:", ...args);
  }
  debug(...args: any[]): void {
    console.debug("[test] debug:", ...args);
  }
  info(...args: any[]): void {
    console.info("[test] info:", ...args);
  }
  warn(...args: any[]): void {
    console.warn("[test] warn:", ...args);
  }
  error(...args: any[]): void {
    console.error("[test] error:", ...args);
  }
  retryContext?: RetryContext;
  traceContext?: TraceContext;
  triggerMetadata?: TriggerMetadata;
  options: EffectiveFunctionOptions = {
    trigger: {
      type: "",
      name: "",
    },
    extraInputs: [],
    extraOutputs: [],
  };
}

The HttpRequest contains the custom x-ms-original-url header which serves as the only relevant input to my function, so I simply create the mocked HttpRequest instance inside the helper function I use to invoke the function under test:

const baseUrl = "https://www.myserver.com";

async function invokeRedirect(route: string): Promise<HttpResponseInit> {
  const context = new MockContext();
  const request = new HttpRequest({
    url: "http://localhost/api/redirect",
    method: "GET",
    headers: { "x-ms-original-url": `${baseUrl}${route}` },
  });

  return await redirect(request, context);
}

For a successful redirect, the most important part of the response is the location header which contains the URL to redirect to. The headers field in the response is a union type, but since I know the exact type my function returns, I simplified the assertion code by always casting the value to that type:

const response = await invokeRedirect(route);

expect(response.status).toBe(301);
const location = (response.headers as Record<string, string> | undefined)
  ?.location;
expect(location).toBe(expected);

Since I want to test the function for many supported inputs, data-driven tests are a good fit:

test.each`
  route                   | expected
  ${"/categories/dotnet"} | ${"/tags/dotnet.html"}
  ${"/categories/csharp"} | ${"/tags/csharp.html"}
`(
  "redirects to $route -> $expected",
  async ({ route, expected }: { route: string; expected: string }) => {
    // ...
  },
);

To test the behavior for URLs without a matching redirect, I had to mock the fetch function which my function uses to read the response body:

const notFoundPageText = "404 Not Found";

global.fetch = jest.fn().mockResolvedValue({
  ok: true,
  status: 200,
  text: () => Promise.resolve(notFoundPageText),
});

To be as thorough as possible, I decided to also verify the fetch invocation, not only the response of the function under test:

expect(global.fetch).toHaveBeenCalledTimes(1);
expect(global.fetch).toHaveBeenCalledWith(`${baseUrl}/errors/404.html`);

expect(response.status).toBe(404);
expect(response.body).toBe(notFoundPageText);
const contentType = (response.headers as Record<string, string> | undefined)?.[
  "Content-Type"
];
expect(contentType).toBe("text/html");

To start each test with a clean state, I clear the mocks after every test:

afterEach(() => {
  jest.clearAllMocks();
});

You can find a sample project in my GitHub repository. I started off with the sample project from my previous blog post and added tests to it. The last commit adds all the tests as well as the extra setup to make them work.

Although the unit tests are great for thoroughly testing all the use cases for the Azure function, you shouldn't completely rely on them. Before deploying the function, it's a good idea to run it locally and invoke it using curl, for example:

curl -H "x-ms-original-url: http://localhost:7071/categories/dotnet" -v http://localhost:7071/api/redirect

This way the function will at least run in a simulated Azure Functions runtime, not only in a Node runtime provided by Jest.

Of course, the final and ultimate test will be when the Azure Function is deployed and invoked in Azure. You should have a small set of test cases prepared to run whenever you deploy any changes to your Azure Function. Only then can you be certain that it works as expected.