feat: construct [Singleton(Eager = true)] services at container build time

[vbreuss]

Add a bool Eager property to [Singleton<TImplementation>] and [Singleton<TImplementation, TService>] so a singleton can be constructed at container build time instead of lazily on first resolve. When set, the generated container root's constructor resolves each eager singleton in registration order, after the root's fields are initialized - the synchronous analog of InitializeAsync, which warms only the async-initialized singletons. Because each eager construction routes through the singleton's own cached static resolver (called with the root), a disposable eager singleton is tracked and disposed with the container exactly like a lazily-resolved one. Eager is exposed on the Singleton attribute only (the open-generic Type-ctor form carries no options), so a stray flag on a coalesced non-singleton is ignored.

Eager is for synchronous construction, so an eager singleton that is async-initialized (or reaches one through its non-deferred dependencies) cannot be built synchronously in the strict default and is the new error AWT161 - InitializeAsync warms it instead, or [Container(SyncResolveAfterInit = true)] emits a blocking synchronous resolver that allows synchronous eager construction while async initialization still runs in InitializeAsync. Missing-dependency, cycle and captive cases through an eager singleton are already covered by AWT101/102/105.

Adds behavior tests (eager constructed before any resolve and cached, lazy not; registration order; disposable disposed with the container), generator tests (the eager calls in the root constructor, registration order, no call for a lazy singleton, AWT161 in strict mode, allowed in pragmatic mode), and updates the public-API approval files for the new Eager property.

[github-actions]

Test Results

   18 files  ± 0     18 suites  ±0   4m 39s ⏱️ ±0s
  760 tests +11    759 ✅ +11  1 💤 ±0  0 ❌ ±0 
3 678 runs  +57  3 677 ✅ +57  1 💤 ±0  0 ❌ ±0 

Results for commit 2d9811f. ± Comparison against base commit 3e5dd1d.

♻️ This comment has been updated with latest results.

[github-actions]

👽 Mutation Results

Awaiten

Details

File	Score	Killed	Survived	Timeout	No Coverage	Ignored	Compile Errors	Runtime Errors	Total Detected	Total Undetected	Total Mutants
SingletonAttribute.cs	0.00%	0	2	0	0	0	0	0	0	2	2

The final mutation score is 0.00%

Coverage Thresholds: high:80 low:60 break:0

[github-actions]

🚀 Benchmark Results

Details

BenchmarkDotNet v0.15.8, Linux Ubuntu 24.04.4 LTS (Noble Numbat)

AMD EPYC 9V74 2.87GHz, 1 CPU, 4 logical and 2 physical cores

.NET SDK 10.0.301

[Host] : .NET 10.0.9 (10.0.9, 10.0.926.27113), X64 RyuJIT x86-64-v3
Job=InProcess  Toolchain=InProcessEmitToolchain  IterationCount=15

LaunchCount=1  WarmupCount=10

Resolve	Size	Mean	Error	StdDev	Ratio	Allocated	Alloc Ratio
baseline*	8	8.137 ns	0.0236 ns	0.0221 ns	1.05	-	NA
Awaiten	8	7.755 ns	0.0166 ns	0.0139 ns	1.00	-	NA
MsDI	8	8.950 ns	0.0160 ns	0.0149 ns	1.15	-	NA
Autofac	8	106.697 ns	0.3033 ns	0.2688 ns	13.76	656 B	NA
Jab	8	3.095 ns	0.1687 ns	0.1496 ns	0.40	-	NA
PureDI	8	5.109 ns	0.0081 ns	0.0071 ns	0.66	-	NA
DryIoc	8	8.430 ns	0.1081 ns	0.0903 ns	1.09	-	NA
SimpleInjector	8	10.122 ns	0.0105 ns	0.0099 ns	1.31	-	NA
baseline*	256	8.728 ns	0.0125 ns	0.0111 ns	0.99	-	NA
Awaiten	256	8.783 ns	0.0947 ns	0.0886 ns	1.00	-	NA
MsDI	256	8.427 ns	0.0095 ns	0.0089 ns	0.96	-	NA
Autofac	256	106.595 ns	0.3137 ns	0.2934 ns	12.14	656 B	NA
Jab	256	46.665 ns	0.1698 ns	0.1418 ns	5.31	-	NA
PureDI	256	8.932 ns	0.0053 ns	0.0044 ns	1.02	-	NA
DryIoc	256	9.088 ns	0.1565 ns	0.1387 ns	1.03	-	NA
SimpleInjector	256	14.869 ns	0.0147 ns	0.0123 ns	1.69	-	NA

Details

BenchmarkDotNet v0.15.8, Linux Ubuntu 24.04.4 LTS (Noble Numbat)

AMD EPYC 7763 2.45GHz, 1 CPU, 4 logical and 2 physical cores

.NET SDK 10.0.301

[Host] : .NET 10.0.9 (10.0.9, 10.0.926.27113), X64 RyuJIT x86-64-v3
Job=InProcess  Toolchain=InProcessEmitToolchain  IterationCount=15

LaunchCount=1  WarmupCount=10

Realistic	Mean	Error	StdDev	Ratio	Allocated	Alloc Ratio
baseline*	232.3 ns	1.93 ns	1.81 ns	0.98	568 B	1.00
Awaiten	237.8 ns	4.83 ns	4.52 ns	1.00	568 B	1.00
MsDI	581.7 ns	7.15 ns	6.34 ns	2.45	1104 B	1.94
Autofac	7,829.2 ns	36.26 ns	32.14 ns	32.94	13696 B	24.11
Jab	173.3 ns	1.46 ns	1.36 ns	0.73	432 B	0.76
DryIoc	393.1 ns	4.97 ns	4.65 ns	1.65	944 B	1.66
SimpleInjector	739.6 ns	8.23 ns	7.70 ns	3.11	1096 B	1.93
PureDI	180.2 ns	3.05 ns	2.85 ns	0.76	632 B	1.11

Details

BenchmarkDotNet v0.15.8, Linux Ubuntu 24.04.4 LTS (Noble Numbat)

AMD EPYC 7763 2.45GHz, 1 CPU, 4 logical and 2 physical cores

.NET SDK 10.0.301

[Host] : .NET 10.0.9 (10.0.9, 10.0.926.27113), X64 RyuJIT x86-64-v3
Job=InProcess  Toolchain=InProcessEmitToolchain  IterationCount=15

LaunchCount=1  WarmupCount=10

Build	Size	Mean	Error	StdDev	Ratio	Allocated	Alloc Ratio
baseline*	8	17.933 ns	0.4616 ns	0.4318 ns	1.04	144 B	1.00
Awaiten	8	17.245 ns	0.3956 ns	0.3506 ns	1.00	144 B	1.00
MsDI	8	1,496.061 ns	19.9651 ns	18.6753 ns	86.78	5688 B	39.50
Autofac	8	30,257.778 ns	301.7567 ns	267.4994 ns	1,755.21	33098 B	229.85
Jab	8	9.060 ns	0.2269 ns	0.2123 ns	0.53	96 B	0.67
PureDI	8	15.765 ns	0.6111 ns	0.5716 ns	0.91	128 B	0.89
DryIoc	8	737.816 ns	7.8857 ns	6.9905 ns	42.80	1528 B	10.61
SimpleInjector	8	11,524.157 ns	98.0494 ns	86.9183 ns	668.50	24760 B	171.94
baseline*	256	83.834 ns	1.4265 ns	1.2645 ns	0.92	2128 B	1.00
Awaiten	256	90.985 ns	1.7868 ns	1.5839 ns	1.00	2128 B	1.00
MsDI	256	14,447.789 ns	38.6926 ns	32.3101 ns	158.84	61016 B	28.67
Autofac	256	738,411.716 ns	4,107.6240 ns	3,641.3017 ns	8,118.13	740938 B	348.19
Jab	256	72.586 ns	2.1160 ns	1.8758 ns	0.80	2080 B	0.98
PureDI	256	83.648 ns	2.3168 ns	2.1672 ns	0.92	2112 B	0.99
DryIoc	256	42,383.496 ns	172.3662 ns	161.2315 ns	465.97	80670 B	37.91
SimpleInjector	256	355,597.872 ns	7,575.6220 ns	7,086.2415 ns	3,909.46	573074 B	269.30

baseline* rows show the corresponding Awaiten benchmark from the most recent successful main branch build with results, for regression comparison.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
95.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud