Recent updates to NetEscapades.EnumGenerators: new APIs and System.Memory support

The article summarizes updates to version 1.0.0-beta19 of the NetEscapades.EnumGenerators NuGet package, a source generator that creates fast methods for working with enums by replacing slow built-in operations like `ToString()` with optimized switch statements. New features include the ability to disable number parsing in `Parse()` and `TryParse()` methods, support for automatically applying `ToLowerInvariant()` or `ToUpperInvariant()` to serialized enums, and added `ReadOnlySpan<T>` API support when using the System.Memory package.

In this post I describe some of the recent updates added in version 1.0.0-beta19 of my source generator NuGet package NetEscapades.EnumGenerators https://github.com/andrewlock/NetEscapades.EnumGenerators which you can use to add fast methods for working with enum s. I start by briefly describing why the package exists and what you can use it for, then I walk through some of the changes in the latest release. Why should you use an enum source generator? why-should-you-use-an-enum-source-generator- NetEscapades.EnumGenerators https://github.com/andrewlock/NetEscapades.EnumGenerators provides a source generator that is designed to work around an annoying characteristic of working with enums: some operations are surprisingly slow. As an example, let's say you have the following enum: public enum Colour { Red = 0, Blue = 1, } At some point, you want to print the name of a Color variable, so you create this helper method: public void PrintColour Colour colour { Console.WriteLine "You chose "+ colour.ToString ; // You chose Red } While this looks like it should be fast, it's really not. NetEscapades.EnumGenerators works by automatically generating an implementation that is fast. It generates a ToStringFast method that looks something like this: public static class ColourExtensions { public string ToStringFast this Colour colour = colour switch { Colour.Red = nameof Colour.Red , Colour.Blue = nameof Colour.Blue , = colour.ToString , } } } This simple switch statement checks for each of the known values of Colour and uses nameof to return the textual representation of the enum . If it's an unknown value, then it falls back to the built-in ToString implementation for simplicity of handling of unknown values for example this is valid C : PrintColour Colour 123 . If we compare these two implementations using BenchmarkDotNet https://benchmarkdotnet.org/ for a known colour, you can see how much faster the ToStringFast implementation is, even in .NET 10 | Method | Mean | Error | StdDev | Median | Gen0 | Allocated | |---|---|---|---|---|---|---| | ToString | 6.4389 ns | 0.1038 ns | 0.0971 ns | 6.4567 ns | 0.0038 | 24 B | | ToStringFast | 0.0050 ns | 0.0202 ns | 0.0189 ns | 0.0000 ns | - | - | Obviously your mileage may vary and the results will depend on the specific enum and which of the generated methods you're using, but in general, using the source generator should give you a free performance boost If you want to learn more about all the features the package provides, check my previous blog posts or see the project README . That's the basics of why I think you should take a look at the source generator. Now let's take a look at the latest features added. Updates in 1.0.0-beta19 updates-in-1-0-0-beta19 Version 1.0.0-beta19 of NetEscapades.EnumGenerators https://www.nuget.org/packages/NetEscapades.EnumGenerators/ was released to nuget.org recently and includes a number of new features. I'll describe each of the updates in more detail below, covering the following: - Support for disabling number parsing. - Support for automatically calling ToLowerInvariant or ToUpperInvariant on the serialized enum. - Add support for ReadOnlySpan<T APIs when using the https://www.nuget.org/packages/System.Memory . System.Memory NuGet package There are other fixes and features in 1.0.0-beta19, but these are the ones I'm focusing on in this post. I'll show some of the other features in the next post Support for disabling number parsing and additional options support-for-disabling-number-parsing-and-additional-options The first feature addresses a long-standing request https://github.com/andrewlock/NetEscapades.EnumGenerators/issues/80 , disabling the fallback "number parsing" implemented in Parse and TryParse . For clarity I'll provide a brief example. Let's take the Color example again: EnumExtensions public enum Colour { Red = 0, Blue = 1, } As well as ToStringFast , we generate similar "fast" Parse , TryParse , and most of the other System.Enum static methods that you might expect. The TryParse method for the above code looks something like this: public static bool TryParse string? name, out Colour value { switch name { case nameof Colour.Red : value = Colour.Red; return true; case nameof Colour.Blue : value = Colour.Blue; return true; case string s when int.TryParse name, out var val : value = Colour val; return true; default: value = default; return false; } } The first two branches in this example are what you might expect; the source generator generates an explicit switch statement for the Colour enum. However, the third case may look a little odd. The problem is that enum s in C are not a closed list of values, you can always do something like this: Colour valid = Colour 123; string stillValid = valid.ToString ; // "123" Colour parsed = Enum.Parse<Colour stillValid ; // 123 Console.WriteLine valid == parsed ; // true Essentially, you can pretty much parse any integer that has been ToString ed as any enum. That's why the source generated code includes the case statement to try parsing as an integer—it's to ensure compatibility with the "built-in" Enum.Parse and TryParse behaviour. However, that behaviour isn't always what you want. Arguably, it's rarely what you want, hence the request https://github.com/andrewlock/NetEscapades.EnumGenerators/issues/80 to allow disabling it. Given it makes so much sense to allow disabling it, it's perhaps a little embarrassing that it took so long to address. I dragged my feet on it for several reasons: - The built-in System.Enum works like this, and I want to be as drop-in compatible as possible. - There's a trivial "fix" by checking first that the first digit is not a number. e.g. if char.IsDigit text 0 && ColourExtensions.TryParse text, out var value - It's another configuration switch that would need to be added to Parse and TryParse Of all the reasons, that latter point is the one that vexed me. There were already two configuration knobs for Parse and TryParse , as well as versions that accept both string and ReadOnlySpan<char : public static partial class ColourExtensions { public static Colour Parse string? name ; public static Colour Parse string? name, bool ignoreCase ; public static Colour Parse string? name, bool ignoreCase, bool allowMatchingMetadataAttribute ; public static Colour Parse ReadOnlySpan<char name ; public static Colour Parse ReadOnlySpan<char name, bool ignoreCase ; public static Colour Parse ReadOnlySpan<char name, bool ignoreCase, bool allowMatchingMetadataAttribute ; } My concern was adding more and more parameters or overloads would make the generated API harder to understand. The simple answer was to take the classic approach of introducing an "options" object. This encapsulates all the available options in a single parameter, and can be extended without increasing the complexity of the generated APIs: public static partial class ColourExtensions { public static Colour Parse string? name, EnumParseOptions options ; public static Colour Parse ReadOnlySpan<char name, EnumParseOptions options ; } The EnumParseOptions object https://github.com/andrewlock/NetEscapades.EnumGenerators/blob/master/src/NetEscapades.EnumGenerators.Attributes/EnumParseOptions.cs is defined in the source generator dll that's referenced by your application, so it becomes part of the public API. It's defined as a readonly struct to avoid allocating an object on the heap just to call Parse which would negate some of the benefits of these APIs . public readonly struct EnumParseOptions { private readonly StringComparison? comparisonType; private readonly bool blockNumberParsing; public EnumParseOptions StringComparison comparisonType = StringComparison.Ordinal, bool allowMatchingMetadataAttribute = false, bool enableNumberParsing = true { comparisonType = comparisonType; AllowMatchingMetadataAttribute = allowMatchingMetadataAttribute; blockNumberParsing = enableNumberParsing; } public StringComparison ComparisonType = comparisonType ?? StringComparison.Ordinal; public bool AllowMatchingMetadataAttribute { get; } public bool EnableNumberParsing = blockNumberParsing; } The main difficulty in designing this object was that the default values i.e. EnumParseOptions default had to match the "default" values used in other APIs, i.e. Not case sensitive- Number parsing enabled Don't match metadata attributes see my previous post /recent-updates-to-netescapaades-enumgenerators/ about recent changes to metadata attributes . The final object ticks all those boxes, and it means you can now disable number parsing, using code like this: string someNumber = "123"; ColourExtensions.Parse someNumer, new EnumParseOptions enableNumberParsing: false ; // throws ArgumentException As well as introducing number parsing, this also provided a way to sneak in the ability to use any type of StringComparison during Parse or TryParse methods, instead of only supporting Ordinal and OrdinalIgnoreCase . Support for automatic support-for-automatic-tolowerinvariant-calls ToLowerInvariant calls ToLowerInvariant callsThe next feature https://github.com/andrewlock/NetEscapades.EnumGenerators/pull/177 was also a feature request that's been around for a long time https://github.com/andrewlock/NetEscapades.EnumGenerators/issues/36 , the ability to do the equivalent of ToString .ToLowerInvariant but without the intermediate allocation, and with the transformation done at compile time, essentially generating something similar to these: public static class ColourExtensions { public static string ToStringLowerInvariant this Colour colour = colour switch { Colour.Red = "red", Colour.Blue = "blue", = colour.ToString .ToLowerInvariant , }; public static string ToStringUpperInvariant this Colour colour = colour switch { Colour.Red = "RED", Colour.Blue = "BLUE", = colour.ToString .ToUpperInvariant , } } There are various reasons you might want to do that, for example if third-party APIs require that you use upper/lower for your enums, but you want to keep your definitions as canonical C naming. This was another case where I could see the value, but I didn't really want to add it, as it looked like it would be a headache. ToStringLower is kind of ugly, and there would be a bunch of extra overloads required again. Just as for the number parsing scenario, the solution I settled on was to add a SerializationOptions object https://github.com/andrewlock/NetEscapades.EnumGenerators/blob/master/src/NetEscapades.EnumGenerators.Attributes/SerializationOptions.cs L6 that supports a SerializationTransform , which can potentially be extended in the future if required though I'm not chomping at the bit to add more options right now public readonly struct SerializationOptions { public SerializationOptions bool useMetadataAttributes = false, SerializationTransform transform = SerializationTransform.None { UseMetadataAttributes = useMetadataAttributes; Transform = transform; } public bool UseMetadataAttributes { get; } public SerializationTransform Transform { get; } } public enum SerializationTransform { None, LowerInvariant, UpperInvariant, } You can then use the ToStringFast overload that takes a SerializationOptions object, and it will output the lower version of your enum, without needing the intermediate ToStringFast call: js var colour = Colour.Red; Console.WriteLine colour.ToStringFast new transform: SerializationTransform.LowerInvariant ; // red It's not the tersest of syntax, but there's ways to clean that up, and it means that adding additional options later if required should be less of an issue, but we shall see. In the short-term, it means that you can now use this feature if you find yourself needing to call ToLowerInvariant or ToUpperInvariant on your enums. Support for the support-for-the-system-memory-nuget-package System.Memory NuGet package System.Memory NuGet package From the start, NetEscapades.EnumGenerators has had support for parsing values from ReadOnlySpan<char , just like the modern APIs in System.Enum do but faster 😉 . However, these APIs have always been guarded by a pre-processor directive; if you're using .NET Core 2.1+ or .NET Standard 2.1 then they're available, but if you're using .NET Framework, or .NET Standard 2.0, then they're not available. if NETCOREAPP2 1 OR GREATER || NETSTANDARD2 1 OR GREATER public static bool IsDefined in ReadOnlySpan<char name ; public static bool IsDefined in ReadOnlySpan<char name, bool allowMatchingMetadataAttribute ; public static Colour Parse in ReadOnlySpan<char name ; public static bool TryParse in ReadOnlySpan<char name, out Colour colour ; // etc endif In my experience, this isn't a massive problem these days. If you're targeting any version of .NET Core or modern .NET, then you have the APIs. If, on the other hand, you're on .NET Framework, then the speed of Enum.ToString will really be the least of your performance worries, and the lack of the APIs probably don't matter that much. Where it could still be an issue is .NET Standard 2.0. It's not recommended to use this target if you're creating libraries for .NET Core or modern .NET, but if you need to target both .NET Core and .NET Framework, then you don't necessarily have a lot of choice, you need to use .NET Standard. What's more, there's a System.Memory NuGet package https://www.nuget.org/packages/System.Memory that provides polyfills for many of the APIs, in particular ReadOnlySpan<char .As I understand it the polyfill implementation isn't generally asfast as the built-in version, but it's still something of an improvement So the new feature in 1.0.0-beta19 of NetEscapades.EnumGenerators is that you can define an MSBuild property, EnumGenerator UseSystemMemory=true , and the ReadOnlySpan<char APIs will be available where previously they wouldn't be. Note that you only need to define this if you're targeting .NET Framework or .NET Standard 2.0 and want the ReadOnlySpan<char APIs. <Project Sdk="Microsoft.NET.Sdk" <PropertyGroup <TargetFrameworks netstandard2.0</TargetFrameworks < -- 👇Setting this in a .NET Standard 2.0 project enables the ReadOnlySpan<char APIs-- <EnumGenerator UseSystemMemory true</EnumGenerator UseSystemMemory </PropertyGroup <ItemGroup <PackageReference Include="NetEscapades.EnumGenerators" Version="1.0.0-beta19" / <PackageReference Include="System.Memory" Version="4.6.3" / </ItemGroup </Project Setting this property defines a constant, NETESCAPADES ENUMGENERATORS SYSTEM MEMORY , which the updated generated code similarly predicates on: // 👇 New in 1.0.0-beta19 if NETCOREAPP2 1 OR GREATER || NETSTANDARD2 1 OR GREATER || NETESCAPADES ENUMGENERATORS SYSTEM MEMORY public static bool IsDefined in ReadOnlySpan<char name ; public static bool IsDefined in ReadOnlySpan<char name, bool allowMatchingMetadataAttribute ; public static Colour Parse in ReadOnlySpan<char name ; public static bool TryParse in ReadOnlySpan<char name, out Colour colour ; // etc endif There are some caveats: - The System.Memory package doesn't provide an implementation of int.TryParse that works with ReadOnlySpan<char , so: If you're attempting to parse a ReadOnlySpan<char , and the ReadOnlySpan<char doesn't represent one of your enum types and you haven't disabled number parsing then the APIs will potentially allocate, so that they can call int.TryParse string . - Additional warnings are included in the XML docs to warn about the above scenario - If you set the variable, and haven't added a reference to System.Memory , you'll get compilation warnings. As part of shipping the feature, I've also tentatively added "detection" of referencing the System.Memory NuGet package in the package .targets file, so that EnumGenerator UseSystemMemory=true should be automatically set, simply by referencing System.Memory . However, I consider this part somewhat experimental, as it's not something I've tried to do before, I'm not sure it's something you should do, and I'm a long way from thinking it'll work 100% of the time 😅 I'd be interested in feedback on how I should do this, and/or whether it works for you I also experimented with a variety of other approaches. Instead of using a defined constant, you could also detect the availability of ReadOnlySpan<char in the generator itself, and emit different code entirely. But you'd still need to detect whether the int.TryParse overloads are available i.e. is ReadOnlySpan<char "built in" or package-provided , and overall it seemed way more complex to handle than the approach I settled on. I'm still somewhat torn though, and maye revert to this approach in the future. And I'm open to other suggestions So in summary, if you're using NetEscapades.EnumGenerators in a netstandard2.0 or .NET Framework package, and you're already referencing System.Memory , then in theory you should magically get additional ReadOnlySpan<char APIs by updating to 1.0.0-beta19. If that's not the case, then I'd love if you could raise an issue https://github.com/andrewlock/NetEscapades.EnumGenerators/issues so we can understand why, but you can also simply set EnumGenerator UseSystemMemory=true to get all that performance goodness guaranteed. Before I close, I'd like to say a big thank you to everyone who has raised issues and PRs for the project, especially Paulo Morgado https://github.com/paulomorgado for his discussion and work around the System.Memory feature All feedback is greatly appreciated, so do raise an issue https://github.com/andrewlock/NetEscapades.EnumGenerators/issues if you have any problems. When is a non-pre-release 1.0.0 release coming? when-is-a-non-pre-release-1-0-0-release-coming- Soon. I promise 😅 So give the new version a try and flag any issues so they can be fixed before we settle on the final API for once and for all 😀 Summary summary In this post I walked through some of the recent updates to NetEscapades.EnumGenerators https://github.com/andrewlock/NetEscapades.EnumGenerators shipped in version 1.0.0-beta18. I showed how introducing options objects for both the Parse / TryParse and ToString methods allowed introducing new features such as disabling number parsing and serializing directly with ToLowerInvariant . Finally, I showed the new support for ReadOnlySpan<char APIs when using .NET Framework or .NET Standard 2.0 with the System.Memory NuGet package https://www.nuget.org/packages/System.Memory If you haven't already, I recommend updating and giving it a try If you run into any problems, please do log an issue on GitHub https://github.com/andrewlock/NetEscapades.EnumGenerators/issues .🙂