NetEscapades.EnumGenerators.Interceptors 1.0.0-beta18

NetEscapades.EnumGenerators.Interceptors

A source generator interceptor for automatically intercepting calls to ToString() on enums, and replacing them with calls to ToStringFast() generated by NetEscapades.EnumGenerators

This source generator requires the .NET 8.0.400 SDK. You can target earlier frameworks like .NET Core 3.1 etc, but the SDK must be at least 8.0.400

Why use this package?

Many methods that operate with enums, such as the ToString() or HasFlag() method, are surprisingly slow. The NetEscapades.EnumGenerators uses a source generator to provide fast versions of these methods, such as ToStringFast() or HasFlagFast().

The main downside to the extension methods generated by NetEscapades.EnumGenerators is that you have to remember to use them. The NetEscapades.EnumGenerators.Interceptors package solves this problem by intercepting calls to ToString() and replacing them with calls ToStringFast() automatically using the .NET compiler feature called interceptors.

Interceptors were introduced as an experimental feature in C#12 with .NET 8, and are stable in .NET 9. They allow a source generator to "intercept" certain method calls, and replace the call with a different one.

For example if you have this code:

var choice = Color.Red;
Console.WriteLine("You chose: " + choice.ToString());

public enum Color
{
    Red = 0,
    Blue = 1,
}

When you use the NetEscapades.EnumGenerators.Interceptors, the interceptor automatically replaces the call to choice.ToString() at compile-time with a call to ToStringFast(), as though you wrote the following:

// The compiler replaces the call with this 👇 
Console.WriteLine("You chose: " + choice.ToStringFast());

There are many caveats to this behaviour, as described below, but any explicit calls to ToString() or HasFlag() on a supported enum are replaced automatically.

In addition to the caveats listed below, the interceptor approach unfortunately requires boxing the enum, so in general we recommend enabling the usage analyzers in NetEscapades.EnumGenerators instead of using this package.

Adding NetEscapades.EnumGenerators.Interceptors to your project

Add the package to your application using:

dotnet add package NetEscapades.EnumGenerators.Interceptors

This adds a <PackageReference> to your project. You can additionally mark the package as PrivateAssets="all" and ExcludeAssets="runtime".

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  
  <PackageReference Include="NetEscapades.EnumGenerators.Interceptors" Version="1.0.0-beta18" />
  

</Project>

Enabling interception for an enum

By default, adding NetEscapades.EnumGenerators.Interceptors to a project enables interception for all enums defined in that project that use the [EnumExtensions] or [EnumExtensions<T>] attributes. If you wish to intercept calls made to enums with extensions defined in other projects, you must add the [Interceptable<T>] attribute in the project where you want the interception to happen, e.g.

[assembly:Interceptable<DateTimeKind>]
[assembly:Interceptable<Color>]

If you don't want a specific enum to be intercepted, you can set the IsInterceptable property to false, e.g.

[EnumExtensions(IsInterceptable = false)]
public enum Colour
{
    Red = 0,
    Blue = 1,
}

Interception only works when the target type is unambiguously an interceptable enum, so it won't work

• When ToString() is called in other source generated code.
• When ToString() is called in already-compiled code.
• If the ToString() call is implicit (for example in string interpolation)
• If the ToString() call is made on a base type, such as System.Enum or object
• If the ToString() call is made on a generic type

For example:

// All the examples in this method CAN be intercepted
public void CanIntercept()
{
    var ok1 = Color.Red.ToString(); // ✅
    var red = Color.Red;
    var ok2 = red.ToString(); // ✅
    var ok3 = "The colour is " + red.ToString(); // ✅
    var ok4 = $"The colour is {red.ToString()}"; // ✅
}

// The examples in this method can NOT be intercepted
public void CantIntercept()
{
    var bad1 = ((System.Enum)Color.Red).ToString(); // ❌ Base type
    var bad2 = ((object)Color.Red).ToString(); // ❌ Base type
    
    var bad3 = "The colour is " + red; // ❌ implicit
    var bad4 = $"The colour is {red}"; // ❌ implicit

    string Write<T>(T val)
        where T : Enum
    {
        return val.ToString(); // ❌ generic
    }
}