Examples & benchmarks

Every feature of Huml.Net has a runnable, self-asserting example in the companion huml-dotnet-examples repository. Each example is a small console app that demonstrates one feature and asserts its own behaviour, so the set doubles as an end-to-end test suite run against the published NuGet package.

git clone https://github.com/primeBeri/huml-dotnet-examples
cd huml-dotnet-examples
./run-examples.ps1        # runs all examples and aggregates results

Or run one at a time:

dotnet run --project src/examples/E01.GettingStarted -c Release

The examples

Example	Feature	Related guide
E01 GettingStarted	Deserialise, serialise, round-trip	Getting started
E02 NamingPolicies	Kebab-case keys, [HumlProperty] overrides	Customize property names
E03 Enums	[HumlEnumValue] custom wire names	Work with enums
E04 Polymorphism	[HumlPolymorphic] incl. nested/collection elements	Serialize polymorphic types
E05 CustomConverters	A HumlConverter<T> for a value type	Write a custom converter
E06 Populate	Overlay a partial document onto an instance	Overlay onto an instance
E07 ErrorHandling	The exception contract; HumlOptions.Strict	Handle errors
E08 SourceGeneration	Reflection-free metadata via HumlGeneratedContext	Use the source generator
E09 Options	Naming policy, collection format, ignore condition, number handling	Options reference
E10 ConstructorBinding	Records, [HumlConstructor], init-only properties	Bind constructors & records
E11 ExtensionData	[HumlExtensionData] overflow bucket; Disallow	Capture unknown keys
E12 AotPublish	AOT-safe Parse path; source-gen path avoiding IL2026/IL3050	Publish AOT / trimmed
E13 Versioning	DetectedVersion, VersionSource, UnknownVersionBehaviour	Versioning model

Benchmarks

The same repository hosts the BenchmarkDotNet suite comparing Huml.Net against System.Text.Json in reflection and source-generated modes:

dotnet run --project benchmarks/HumlNet.Benchmarks -c Release

Recorded figures and commentary: Performance benchmarks here, or benchmarks/RESULTS.md in the examples repository.