Proposal: generate custom quantities against the UnitsNet package #1745

Problem

Adding a quantity of your own on top of the UnitsNet package is possible, but it's a lot of hand-written code. The HowMuch sample (Samples/UnitsNetSetup.Configuration/ConfigureWithCustomQuantities.cs) is about 250 lines:

• a unit enum and a struct implementing ILinearQuantity<,>;
• hand-written equality, comparison, parsing and formatting;
• a QuantityInfo, plus a .resx file for abbreviations.

It still lacks the generated API that built-in quantities have, such as HowMuch.FromSomes(1), howMuch.Somes, and operators with built-in quantities. The docs call this approach "highly experimental and incomplete".

UnitsNet.Modular generates custom quantities from JSON, with the same API as built-in ones. But it replaces UnitsNet rather than working with it: the two can't be referenced together (UNM016). An application that uses UnitsNet today can't add one quantity this way.

Finding: generated code is close to working outside UnitsNet

I copied generated quantity code (Turbidity and Length, renamed) into a separate project that references the built UnitsNet.dll, and compiled it. The only errors come from 7 internal APIs that generated code calls:

Everything else that generated code uses, including QuantityInfo, UnitDefinition, UnitParser.Default and QuantityFormatter, is already public.

Proposal

Let applications generate their own quantities with the CodeGen that generates the built-in ones, as part of their build:

<!-- MyApp.csproj, which references UnitsNet -->
<ItemGroup>
  <PackageReference Include="UnitsNet.CodeGen" PrivateAssets="all" />
  <UnitsNetDefinition Include="Units/*.json" />
</ItemGroup>

The JSON uses the same schema as Common/UnitDefinitions. On build, CodeGen generates only those quantities into obj/, in the same shape as the built-in ones: From<Unit> methods, unit properties, Parse/ToString, and relations. They compile into the application's own assembly.

This builds on #1742, which runs CodeGen from MSBuild during the repo's own build. The package would contain CodeGen and an MSBuild targets file that runs it on the application's definitions. What's needed:

1. CodeGen options: input and output paths, a target namespace, and an "external" mode that generates only the given definitions using public APIs.
2. Abbreviations: generated .restext files embedded in the application's assembly, passed to QuantityInfo as a ResourceManager. The HowMuch sample already does this.
3. Registration: a generated extension, such as UnitsNetSetup.ConfigureDefaults(b => b.WithMyQuantities()), wrapping WithAdditionalQuantities.
4. Relations with built-in quantities: the package ships the built-in JSON so CodeGen can generate operators like HowMuch * Length = Mass on the custom type. Operators between two built-in quantities can't be added this way.
5. Unit enum values: each application keeps its own enum value file next to its JSON, like Common/UnitEnumValues.g.json, so values stay stable as units are added.

Compared with UnitsNet.Modular

Question: is Modular the planned direction for v7? If so, it may be better to let Modular's generator target the UnitsNet package, rather than adding a second generator path. I'd like your view before going further.

Possible steps

Each is additive and independently useful:

1. Make the internal helpers above public, or generate public alternatives. This also helps hand-written custom quantities today.
2. Add CodeGen options for paths, namespace and external mode.
3. Package CodeGen with the MSBuild targets.
4. Later, units as objects. If Proposal: units as objects in v6 (UnitOf<TQuantity> instead of unit enums) #1740 lands, generated custom quantities use UnitOf<TQuantity> units instead of an enum, so there are no enum values to coordinate between packages.

Related: #1742 (CodeGen runs in the build), #1740 (units as objects), #902 (source generators), #1181 (one package per quantity), #1728 (feedback on a custom quantity built with Modular), UnitsNet.Modular.

🤖 Generated with Claude Code

https://claude.ai/code/session_012XKhDsyHDc5BHrmibxScqG