NetEscapades.EnumGenerators.Generators 1.0.0-beta20

NetEscapades.EnumGenerators.Generators

NetEscapades.EnumGenerators.Generators is a source generator package that generates extension methods for enums, to allow fast "reflection".

In general, we recommend installing the NetEscapades.EnumGenerators metapackage. See below for details on choosing between these two packages.

NetEscapades.EnumGenerators requires the .NET 7 SDK or higher. NetEscapades.EnumGenerators.Interceptors requires the .NET 8.0.400 SDK or higher. You can still target earlier frameworks like .NET Core 3.1 etc, the version requirement only applies to the version of the .NET SDK installed.

Why use these packages?

Many methods that work with enums are surprisingly slow. Calling ToString() or HasFlag() on an enum seems like it should be fast, but it often isn't. This package provides a set of extension methods, such as ToStringFast() or HasFlagFast() that are designed to be very fast, with fewer allocations.

For example, the following benchmark shows the advantage of calling ToStringFast() over ToString():

BenchmarkDotNet=v0.13.1, OS=Windows 10.0.19042.1348 (20H2/October2020Update)
Intel Core i7-7500U CPU 2.70GHz (Kaby Lake), 1 CPU, 4 logical and 2 physical cores
  DefaultJob : .NET Framework 4.8 (4.8.4420.0), X64 RyuJIT
.NET SDK=6.0.100
  DefaultJob : .NET 6.0.0 (6.0.21.52210), X64 RyuJIT

Enabling these additional extension methods is as simple as adding an attribute to your enum:

[EnumExtensions] // 👈 Add this
public enum Color
{
    Red = 0,
    Blue = 1,
}

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.

For example, imagine you have this code, which uses the Color enum defined above:

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

By default you need to manually replace these ToString() calls with ToStringFast(). However, 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.

Adding NetEscapades.EnumGenerators.Generators to your project

Add the package to your application using

dotnet add package NetEscapades.EnumGenerators.Generators

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

Setting PrivateAssets="all" means any projects referencing this one won't get a reference to the NetEscapades.EnumGenerators.Generators package. Setting ExcludeAssets="runtime" ensures the NetEscapades.EnumGenerators.Attributes.dll file is not copied to your build output (it is not required at runtime).

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

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

  
  <PackageReference Include="NetEscapades.EnumGenerators.Generators" Version="1.0.0-beta20" 
    PrivateAssets="all" ExcludeAssets="runtime" />
  

</Project>

Adding the package will automatically add a marker attribute, [EnumExtensions], to your project.

To use the generator, add the [EnumExtensions] attribute to an enum. For example:

[EnumExtensions]
public enum MyEnum
{
    First,

    [Display(Name = "2nd")]
    Second,
}

This will generate a class called MyEnumExtensions (by default), which contains a number of helper methods. For example:

public static partial class MyEnumExtensions
{
    public const int Length = 2;

    public static string ToStringFast(this MyEnum value, bool useMetadataAttributes)
        => useMetadataAttributes ? value.ToStringFastWithMetadata() : value.ToStringFast();

    public static string ToStringFast(this MyEnum value)
        => value switch
        {
            MyEnum.First => nameof(MyEnum.First),
            MyEnum.Second => nameof(MyEnum.Second),
            _ => value.ToString(),
        };

    private static string ToStringFastWithMetadata(this MyEnum value)
        => value switch
        {
            MyEnum.First => nameof(MyEnum.First),
            MyEnum.Second => "2nd",
            _ => value.ToString(),
        };

    public static bool IsDefined(MyEnum value)
        => value switch
        {
            MyEnum.First => true,
            MyEnum.Second => true,
            _ => false,
        };

    public static bool IsDefined(string name) => IsDefined(name, allowMatchingMetadataAttribute: false);

    public static bool IsDefined(string name, bool allowMatchingMetadataAttribute)
    {
        var isDefinedInDisplayAttribute = false;
        if (allowMatchingMetadataAttribute)
        {
            isDefinedInDisplayAttribute = name switch
            {
                "2nd" => true,
                _ => false,
            };
        }

        if (isDefinedInDisplayAttribute)
        {
            return true;
        }

        
        return name switch
        {
            nameof(MyEnum.First) => true,
            nameof(MyEnum.Second) => true,
            _ => false,
        };
    }

    public static MyEnum Parse(string? name)
        => TryParse(name, out var value, false, false) ? value : ThrowValueNotFound(name);

    public static MyEnum Parse(string? name, bool ignoreCase)
        => TryParse(name, out var value, ignoreCase, false) ? value : ThrowValueNotFound(name);

    public static MyEnum Parse(string? name, bool ignoreCase, bool allowMatchingMetadataAttribute)
        => TryParse(name, out var value, ignoreCase, allowMatchingMetadataAttribute) ? value : throw new ArgumentException($"Requested value '{name}' was not found.");

    public static bool TryParse(string? name, out MyEnum value)
        => TryParse(name, out value, false, false);

    public static bool TryParse(string? name, out MyEnum value, bool ignoreCase) 
        => TryParse(name, out value, ignoreCase, false);

    public static bool TryParse(string? name, out MyEnum value, bool ignoreCase, bool allowMatchingMetadataAttribute)
        => ignoreCase
            ? TryParseIgnoreCase(name, out value, allowMatchingMetadataAttribute)
            : TryParseWithCase(name, out value, allowMatchingMetadataAttribute);

    private static bool TryParseIgnoreCase(string? name, out MyEnum value, bool allowMatchingMetadataAttribute)
    {
        if (allowMatchingMetadataAttribute)
        {
            switch (name)
            {
                case string s when s.Equals("2nd", System.StringComparison.OrdinalIgnoreCase):
                    value = MyEnum.Second;
                    return true;
                default:
                    break;
            };
        }

        switch (name)
        {
            case string s when s.Equals(nameof(MyEnum.First), System.StringComparison.OrdinalIgnoreCase):
                value = MyEnum.First;
                return true;
            case string s when s.Equals(nameof(MyEnum.Second), System.StringComparison.OrdinalIgnoreCase):
                value = MyEnum.Second;
                return true;
            case string s when int.TryParse(name, out var val):
                value = (MyEnum)val;
                return true;
            default:
                value = default;
                return false;
        }
    }

    private static bool TryParseWithCase(string? name, out MyEnum value, bool allowMatchingMetadataAttribute)
    {
        if (allowMatchingMetadataAttribute)
        {
            switch (name)
            {
                case "2nd":
                    value = MyEnum.Second;
                    return true;
                default:
                    break;
            };
        }

        switch (name)
        {
            case nameof(MyEnum.First):
                value = MyEnum.First;
                return true;
            case nameof(MyEnum.Second):
                value = MyEnum.Second;
                return true;
            case string s when int.TryParse(name, out var val):
                value = (MyEnum)val;
                return true;
            default:
                value = default;
                return false;
        }
    }

    public static MyEnum[] GetValues()
    {
        return new[]
        {
            MyEnum.First,
            MyEnum.Second,
        };
    }

    public static string[] GetNames()
    {
        return new[]
        {
            nameof(MyEnum.First),
            nameof(MyEnum.Second),
        };
    }
}

If you create a "Flags" enum by decorating it with the [Flags] attribute, an additional method is created, which provides a bitwise alternative to the Enum.HasFlag(flag) method:

public static bool HasFlagFast(this MyEnum value, MyEnum flag)
    => flag == 0 ? true : (value & flag) == flag;

Note that if you provide a [EnumMember] attribute, the value you provide for this attribute can be used by methods like ToStringFast() and TryParse() by passing the argument useMetadataAttributes: true. Alternatively, you can use the [Display] or [Description] attributes, and set the MetadataSource property on the [EnumExtensions] attribute e.g.

[EnumExtensions(MetadataSource = MetadataSource.DisplayAttribute)]
public enum EnumWithDisplayNameInNamespace
{
    First = 0,
    [Display(Name = "2nd")]
    Second = 1,
    Third = 2,
}

Alternatively, you can use MetadataSource.None to choose none of the metadata attributes. In this case, the overloads that take a useMetadataAttributes parameter will not be emitted.

You can set the default metadata source to use for a whole project by setting the EnumGenerator_EnumMetadataSource property in your project:

<PropertyGroup>
  <EnumGenerator_EnumMetadataSource>EnumMemberAttribute</EnumGenerator_EnumMetadataSource>
</PropertyGroup>

You can override the name of the extension class by setting ExtensionClassName in the attribute and/or the namespace of the class by setting ExtensionClassNamespace. By default, the class will be public if the enum is public, otherwise it will be internal.

Usage Analyzers

NetEscapades.EnumGenerators includes optional analyzers that encourage the use of the generated extension methods instead of the built-in System.Enum methods. These analyzers can help improve performance by suggesting the faster, generated, alternatives like ToStringFast(), HasFlagFast(), and TryParse().

Enabling the analyzers

The usage analyzers are disabled by default. To enable them, set the EnumGenerator_EnableUsageAnalyzers MSBuild property to true in your project:

<PropertyGroup>
  <EnumGenerator_EnableUsageAnalyzers>true</EnumGenerator_EnableUsageAnalyzers>
</PropertyGroup>

Alternatively, add a .globalconfig file to your project with the following content:

is_global = true
build_property.EnumGenerator_EnableUsageAnalyzers = true

After using one of these configuration options, the analyzers in your project should be enabled with the default severity of Warning.

Configuring analyzer severity (optional)

Once enabled, you can optionally configure the severity of individual analyzer rules using one or more .editorconfig files. For example, the following changes all the built-in analyzers to report usages as errors instead of warnings

[*.{cs,vb}]

# NEEG004: Use ToStringFast() instead of ToString()
dotnet_diagnostic.NEEG004.severity = error

# NEEG005: Use HasFlagFast() instead of HasFlag()
dotnet_diagnostic.NEEG005.severity = error

# NEEG006: Use generated IsDefined() instead of Enum.IsDefined()
dotnet_diagnostic.NEEG006.severity = error

# NEEG007: Use generated Parse() instead of Enum.Parse()
dotnet_diagnostic.NEEG007.severity = error

# NEEG008: Use generated GetNames() instead of Enum.GetNames()
dotnet_diagnostic.NEEG008.severity = error

# NEEG009: Use generated GetValues() instead of Enum.GetValues()
dotnet_diagnostic.NEEG009.severity = error

# NEEG010: Use generated GetValuesAsUnderlyingType() instead of Enum.GetValuesAsUnderlyingType()
dotnet_diagnostic.NEEG010.severity = error

# NEEG011: Use generated TryParse() instead of Enum.TryParse()
dotnet_diagnostic.NEEG011.severity = error

# NEEG012: Call ToStringFast() on enum in StringBuilder.Append() for better performance
dotnet_diagnostic.NEEG012.severity = error

These are reported in both your IDE and via the CLI as Roslyn errors:

Valid severity values include: none, silent, suggestion, warning, and error.

Code fixes

All usage analyzers include automatic code fixes. When a diagnostic is triggered, you can use the quick fix functionality in your IDE to automatically replace the System.Enum method with the corresponding generated extension method:

Package referencing options

NetEscapades.EnumGenerators is a metapackage that references additional packages for functionality.

NetEscapades.EnumGenerators
  |____NetEscapades.EnumGenerators.Generators
  |____NetEscapades.EnumGenerators.RuntimeDependencies

These packages provide the following functionality:

• NetEscapades.EnumGenerators is a meta package for easy install.
• NetEscapades.EnumGenerators.Generators contains the source generator itself.
• NetEscapades.EnumGenerators.RuntimeDependencies contains dependencies that need to be referenced at runtime by the generated code.

The default approach is to reference the meta-package in your project. The runtime dependencies and generator packages will then flow transitively to any project that references yours, and the generator will run in those projects by default.

Avoiding runtime dependencies

In some cases you may not want these dependencies to flow to other projects. This is common when you are using NetEscapades.EnumGenerators internally in your own library, for example. In this scenario, we suggest you take the following approach:

• Reference NetEscapades.EnumGenerators.Generators directly, and set PrivateAssets=All
• Optionally reference NetEscapades.EnumGenerators.RuntimeDependencies directly.

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

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

  
  <PackageReference Include="NetEscapades.EnumGenerators.Generators" Version="1.0.0-beta20" PrivateAssets="All"/>

  
  <PackageReference Include="NetEscapades.EnumGenerators.RuntimeDependencies" Version="1.0.0-beta20" />
</Project>

The NetEscapades.EnumGenerators.RuntimeDependencies packages is a "normal" dependency, that contains types that are used by the generated code, such as EnumParseOptions, SerializationOptions, and SerializationTransform:

namespace NetEscapades.EnumGenerators;

/// <summary>
/// Defines the options use when parsing enums using members provided by NetEscapades.EnumGenerator.
/// </summary>
public readonly struct EnumParseOptions { }

/// <summary>
/// Options to apply when calling <c>ToStringFast</c> on an enum. 
/// </summary>
public readonly struct SerializationOptions

/// <summary>
/// Transform to apply when calling <c>ToStringFast</c> 
/// </summary>
public enum SerializationTransform

If the NetEscapades.EnumGenerators.RuntimeDependencies package is not found, the generated code creates nested versions of the dependencies in each generated extension method instead:

namespace SomeNameSpace;


public static partial class MyEnumExtensions
{
    // ... generated members
    
    // The runtime dependencies are generated as nested types instead
    public readonly struct EnumParseOptions { }
    public readonly struct SerializationOptions
    public enum SerializationTransform
}

Generating the runtime dependencies as nested types has both upsides and downsides:

• It avoids placing downstream dependency requirements on consumers of your library.
• If the generated extension methods are internal, the generated runtime dependencies are also internal, and so not exposed to downstream consumers.
• It makes consuming the APIs that use the runtime dependencies more verbose.

Choosing the correct packages for your scenario

In general, for simplicity, we recommend referencing NetEscapades.EnumGenerators, and thereby using NetEscapades.EnumGenerators.RuntimeDependencies. This particularly makes sense when you are the primary consumer of the extension methods, or where you don't mind if consumers end up referencing the generator package.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  <PackageReference Include="NetEscapades.EnumGenerators" Version="1.0.0-beta20" />
</Project>

In contrast, if you are producing a reusable library and don't want any runtime dependencies to be exposed to consumers, we recommend using NetEscapades.EnumGenerators.Generators and setting PrivateAssets=All and ExcludeAssets="runtime".

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  <PackageReference Include="NetEscapades.EnumGenerators.Generators" Version="1.0.0-beta20" PrivateAssets="All" ExcludeAssets="runtime" />
</Project>

The final option is to reference NetEscapades.EnumGenerators.Generators and set PrivateAssets=All and ExcludeAssets="runtime" (to avoid it being referenced transitively), but then also reference NetEscapades.EnumGenerators.RuntimeDependencies, to produce easier-to consume APIs.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  <PackageReference Include="NetEscapades.EnumGenerators.Generators" Version="1.0.0-beta20" PrivateAssets="All" ExcludeAssets="runtime"/>
  <PackageReference Include="NetEscapades.EnumGenerators.RuntimeDependencies" Version="1.0.0-beta20" />
</Project>

Enabling automatic interception

Interceptors were introduced as an experimental feature in C#12 with .NET 8. They allow a source generator to "intercept" certain method calls, and replace the call with a different one. NetEscapades.EnumGenerators has support for intercepting ToString() and HasFlag() method calls.

To use interceptors, you must be using at least version 8.0.400 of the .NET SDK. This ships with Visual Studio version 17.11, so you will need at least that version or higher.

To use interception, add the additional NuGet package NetEscapades.EnumGenerators.Interceptors to your project 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", similarly to NetEscapades.EnumGenerators.

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
    }
}

Preserving usages of the [EnumExtensions] attribute

The [EnumExtensions] attribute is decorated with the [Conditional] attribute, so their usage will not appear in the build output of your project. If you use reflection at runtime on one of your enums, you will not find [EnumExtensions] in the list of custom attributes. If you wish to preserve these attributes in the build output, you can define the NETESCAPADES_ENUMGENERATORS_USAGES MSBuild variable.

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    
    <DefineConstants>$(DefineConstants);NETESCAPADES_ENUMGENERATORS_USAGES</DefineConstants>
  </PropertyGroup>

  
  <PackageReference Include="NetEscapades.EnumGenerators" Version="1.0.0-beta20" />
</Project>