Intellenum

Intellenum is an open-source C# library designed for fast and efficient enum handling. It uses C# source generation to create backing code that enables extremely fast, allocation-free lookups using methods like FromName, FromValue, and their Try... variants.

Unlike standard C# enums, Intellenum is designed to be used with partial class definitions, allowing you to define static members that represent your enum values. It also includes code analyzers to prevent common safety issues, such as accidental defaulting.

[Intellenum]
public partial class CustomerType
{
    public static readonly CustomerType Standard, Gold;
}

Intellenum is designed for high performance, often outperforming standard C# enums and other smart enum libraries in key operations.

Key performance highlights:

• IsDefined / TryFromValue: Significantly faster than standard Enum.IsDefined or Enum.TryParse.
• ToString(): Optimized for speed, comparable to or faster than SmartEnums.
• FromName(): Highly efficient lookup compared to standard Enum.TryParse.
• Value Access: Provides near-instant access to the underlying value.

When using Vogen, it is recommended to use class or struct instead of record (or record class/record struct).

Because Vogen is designed to wrap and protect a single primitive value, the standard benefits of C# records (like built-in value-based equality and boilerplate reduction) do not align with Vogen's purpose. Using records introduces specific side effects and behaviors that may not be desired in a Value Object context.

Intellenum supports serialization and deserialization using the following libraries:

• System.Text.Json
• Newtonsoft.Json
• Dapper
• Entity Framework Core
• Linq2Db
• TypeConverters

By default, Intellenum serializes using the Value property, matching the behavior of native C# enums. If you use System.Text.Json, you can also serialize dictionaries that use an Intellenum as a key.

ToString()

Calling .ToString() on an Intellenum member returns the name of the member.

TypeConverters

Intellenum provides a TypeConverter that behaves differently depending on the target type:

• Converting a member to a string returns the value of the member as a string.
• It can also convert an underlying type back to its matching Intellenum enum.

If the underlying primitive implements IComparable<>, Intellenum can hoist this functionality to the generated wrapper.

To enable this, you must set the ComparisonGeneration configuration to UseUnderlying. When enabled, the generated wrapper will implement both IComparable<> (with the generic argument being the type of the wrapper) and the non-generic IComparable. The resulting method signature is public [ReturnType] CompareTo([primitive] other).

Intellenum supports various serialization and conversion workflows:

• Serialization: It serializes using the Value property, similar to native C# enums. It is compatible with:
  • System.Text.Json
  • Newtonsoft.Json
  • Dapper
  • Entity Framework Core
  • Linq2Db
  • TypeConverters
• Dictionary Keys: You can use an Intellenum as a key in a Dictionary, and it can be serialized (specifically supported by System.Text.Json).
• ToString() Behavior: Calling .ToString() on a member returns the name of the member. However, the provided TypeConverter will return the value of the member as a string when converting to a string type.
• TypeConverters: They can convert an underlying type back into its matching Intellenum.

When calling TryParse on a wrapper, the following lifecycle occurs:

1. The method calls the underlying primitive's TryParse method.
2. If parsing succeeds, the resulting value is passed to the wrapper's Validate method.
3. If Validate fails, TryParse returns false. The out parameter will contain:
   • null for classes.
   • The default value for structs (note: accessing this default value may throw if it is a value object).

Important Change (v4.0+): In version 4.0 and later, TryParse no longer throws a ValueObjectValidationException on validation failure; it follows the idiomatic pattern of returning false instead.

Intellenum automatically generates a TypeConverter for every Value Object defined with the [ValueObject<T>] attribute.

When an ASP.NET Core application receives a request, the routing framework inspects the parameter types. If a parameter is a Value Object, the framework looks for the associated TypeConverter (e.g., CityNameTypeConverter). It then calls the converter's ConvertTo method, which internally calls the Value Object's From method to transform the primitive input (such as a string) into the Value Object instance.

// Example of the generated attribute applied to your struct
[TypeConverter(typeof(CityNameTypeConverter))]
public partial struct CityName
{
}