CSharpEssentials.Enums 5.1.0

CSharpEssentials.Enums

One spelling per enum member across JSON, ASP.NET Core binding, OpenAPI, EF Core and outgoing HTTP. Mark an enum with [StringEnum] and a bundled source generator writes its metadata and helpers at compile time: no reflection, trim and NativeAOT safe.

Installation

dotnet add package CSharpEssentials.Enums

The package contains the source generator, the analyzers and the code fixes. Any CSharpEssentials package brings the generator and analyzers: every package that depends on Enums, directly or through another CSharpEssentials package, passes them on. A project that references one of them gets [StringEnum] metadata, the CSE analyzers and the CSharpEssentialsEnumNaming property without a direct CSharpEssentials.Enums reference. Reference CSharpEssentials.Enums directly only when the project uses no other CSharpEssentials package that depends on it (.Core, .Clone, .Time, .DependencyInjection, .Endpoints and .RequestResponseLogging do not depend on it).

Inside this repository the samples and tests use ProjectReferences; a ProjectReference does not carry the referenced project's own generator output, but analyzers from that project's NuGet packages do flow. The samples and tests therefore reference CSharpEssentials.Enums.Generators with OutputItemType="Analyzer" themselves (the tests also import build/CSharpEssentials.Enums.props for CSharpEssentialsEnumNaming).

Targets net11.0, net10.0, net9.0, netstandard2.1 and netstandard2.0. Registration needs C# 9 or later.

Declare an enum

using System.ComponentModel;
using System.Text.Json.Serialization;
using CSharpEssentials.Enums;

[StringEnum]
[Description("Order lifecycle state.")]
public enum OrderStatus
{
    Pending,                                   // "pending"
    [EnumAlias("Approval")] PendingApproval,   // "pending_approval", also reads "Approval"
    [JsonStringEnumMemberName("sent")] Shipped, // "sent"
    [EnumFallback] Unknown = 99,               // what tolerant readers map unknown values to
}

• [StringEnum] opts the enum in. Nested enums are supported (the class for Order.State is Order_StateExtensions).
• [EnumAlias(...)] adds spellings that are read everywhere but never written.
• [EnumFallback] marks the member that data reads (database rows, responses of other services, message payloads) map unknown values to. Request input never uses it: an unknown request value is a 400.
• [Description] texts appear in the OpenAPI value table.

Wire names

The wire name is the one string every layer writes. It is resolved in this order:

1. [JsonStringEnumMemberName("...")] on the member
2. [EnumMember(Value = "...")] on the member
3. [StringEnum(Naming = EnumNaming.KebabCaseLower)] on the enum
4. the CSharpEssentialsEnumNaming MSBuild property of the project
5. SnakeCaseLower

EnumNaming values: Default (use the project setting), SnakeCaseLower (pending_approval), SnakeCaseUpper (PENDING_APPROVAL), KebabCaseLower (pending-approval), KebabCaseUpper (PENDING-APPROVAL), CamelCase (pendingApproval), PascalCase (PendingApproval). The separators follow System.Text.Json.JsonNamingPolicy, so HTTPStatus is http_status.

<PropertyGroup>
  <CSharpEssentialsEnumNaming>KebabCaseLower</CSharpEssentialsEnumNaming>
</PropertyGroup>

Generated helpers

For OrderStatus the generator writes OrderStatusExtensions:

OrderStatus status = OrderStatus.PendingApproval;

status.ToWireName();                                // "pending_approval"
OrderStatusExtensions.PendingApprovalWireName;      // "pending_approval" (const)
status.IsDefined();                                 // true (flags: a combination of defined flags)

OrderStatusExtensions.TryParseWire("Approval", out OrderStatus parsed); // true, PendingApproval
OrderStatusExtensions.ParseWire("pending_approval");                     // PendingApproval
OrderStatusExtensions.ParseWire("gone");                                 // throws EnumValueException

status.ToOptimizedString();                         // "PendingApproval"
status.ToKebabCase();                               // "pending-approval"
status.ToLowerCase();                               // "pendingapproval"
status.ToUpperCase();                               // "PENDINGAPPROVAL"
status.AsUnderlyingType();                          // 1
OrderStatusExtensions.IsDefined("PendingApproval"); // true (member names)
OrderStatusExtensions.GetNames();                   // member names
OrderStatusExtensions.GetValues();                  // all members

• ToWireName() throws EnumValueException for an undefined value. [Flags] values are formatted as comma separated wire names of single flags.
• TryParseWire/ParseWire accept every known spelling (wire name, member name in any casing, alias, the number of a defined member) and never return the fallback member.
• {Member}SnakeCase and {Member}KebabCase constants keep their 4.x values.
• ToSnakeCase(), TryParse and Parse are obsolete; use ToWireName(), TryParseWire and ParseWire. ToSnakeCase() keeps its 4.x output (HTTPStatus → httpstatus), while ToWireName() returns http_status. That old spelling is read as an extra alias, so stored values still load.

Conventions and runtime API

One EnumConventions instance drives every layer. EnumConventions.Default is:

It is a record, so derive variants with with: EnumConventions.Default with { AcceptNumbers = false }.

using CSharpEssentials.Enums;

// Parse and format without the generated class (for example in generic code)
bool ok = EnumValueParser.TryParse("approval", EnumReadMode.Input, EnumConventions.Default,
    out OrderStatus value, out EnumValueError? error);
string text = EnumValueFormatter.Format(OrderStatus.Shipped, EnumWireFormat.String); // "sent"

// Metadata
EnumInfo<OrderStatus> info = EnumMetadata.Get<OrderStatus>();
IReadOnlyList<string> wireNames = info.WireNames; // ["pending", "pending_approval", "sent", "unknown"]
bool registered = EnumMetadata.IsRegistered(typeof(OrderStatus));

EnumReadMode.Input is the strict mode for values a caller sends you. EnumReadMode.Data accepts every known spelling and applies UnknownValue. On failure EnumValueError carries the enum type, the value, the allowed wire names and the path; EnumValueException wraps it.

Wire it into each layer:

See Enums end to end and the end-to-end sample.

Flags

[StringEnum]
[Flags]
public enum Permissions
{
    None = 0,
    Read = 1,
    Write = 2,
    Delete = 4,
}

[Flags] enums are JSON arrays (["read","write"]), repeated or comma separated query values, and an integer bitmask in the database (FlagsStorage = Integer). Give every member an explicit value and a None = 0 member. The analyzers check this: CSE0005 (no explicit values with integer storage), CSE0006 (no zero member) and CSE0007 (a member that is neither a single bit nor a combination of other members). [EnumFallback] is not allowed on flags (CSE0008), because unknown bits are always rejected.

Use flags for a fixed, small set of independent on/off capabilities (permissions, feature toggles, days of week). Use List<TEnum> for a user-chosen multi-select, a set that grows often or past 64 members, or when a member needs data attached. Use a single enum for one value at a time (statuses, types).

Renaming a member safely

A wire name is a contract: it is in JSON payloads, URLs, OpenAPI clients and database rows. Changing it (renaming a member, changing Naming or [JsonStringEnumMemberName]) also changes the check constraint, so dotnet ef migrations add emits DropCheckConstraint + AddCheckConstraint and nothing else. Rows that still hold the old name make AddCheckConstraint fail.

Option 1: rename the C# member only (recommended for public APIs). Pin the old wire name, which has the highest priority:

[JsonStringEnumMemberName("shipped")] Dispatched, // was Shipped; the wire name stays "shipped"

Nothing changes on the wire or in the database, and the next migration is empty.

Option 2: change the wire name. Keep the old spelling readable and rewrite the stored data:

[EnumAlias("shipped")] Dispatched, // writes "dispatched", still reads "shipped"

Every layer now writes dispatched and still reads shipped (input and data). Edit the generated migration so the data is rewritten between the two constraint operations:

protected override void Up(MigrationBuilder migrationBuilder)
{
    migrationBuilder.DropCheckConstraint(name: "ck_orders_Status_enum", table: "orders");
    migrationBuilder.Sql("""UPDATE orders SET "Status" = 'dispatched' WHERE "Status" = 'shipped';""");
    migrationBuilder.AddCheckConstraint(name: "ck_orders_Status_enum", table: "orders", sql: "..."); // as generated
}

ConvertEnumColumn<OrderStatus>("orders", "Status", from: EnumStoredAs.Text, to: EnumStorage.String) does the same rewrite for every non-canonical spelling (aliases, member names, other casings). Run EnumDataAudit.Sql<OrderStatus>(...) (see EF Core) before deploying to check that no other value would fail the constraint. Keep the alias as long as old clients or stored payloads (JSON columns, queues) may still send shipped.

Other services that read your output and do not know dispatched yet reject it, unless their copy of the enum has an [EnumFallback] member and they read in Data mode: then they map it to the fallback member. Ship the new name to consumers before producers start writing it.

Diagnostics

CSE0011 is not used (folded into CSE0015). When CSE0002, CSE0003, CSE0004, CSE0008 or CSE0009 applies, the generator writes no metadata for that enum.

AOT and trimming

• The [StringEnum] path uses no reflection. JSON converters, EF Core converters, model binders and OpenAPI schemas get typed instances from the generated metadata. CSharpEssentials.Enums and CSharpEssentials.Json set IsAotCompatible on net8.0 and later, so the trim analyzer checks them.
• The reflection opt-ins are annotated [RequiresUnreferencedCode] and [RequiresDynamicCode]: EnumMetadata.GetOrCreateWithReflection, AddEnumConventionsWithReflection (JSON and ASP.NET Core), EnumConverterFactory.CreateWithReflectionFallback and ConfigureEnumConventionsWithReflection (EF Core). The default path never calls them.
• A [StringEnum] enum without metadata fails loudly (CSE0015 at build time, an exception when its converter is created). It never falls back to numbers silently.
• In AOT apps serialize with a source-generated JsonSerializerContext; the ConvertToJson/ConvertFromJson helpers and EnhancedJsonSerializerOptions of CSharpEssentials.Json use reflection-based serialization.

Glossary

Full vocabulary and the normative matrix: enum conventions design.

Migrating from 4.x

See Migrating from 4.x to 5.0: obsolete helpers, the ToSnakeCase() vs ToWireName() difference and the database rollout.