Skip to content

Sample Applications

The samples/ tree is a set of worked examples that exercise Specular end-to-end. Three reusable libraries declare services in different registration styles; hosts consume all three and assert — in process — that Specular discovered exactly the expected service set, then publish under a zero-warning Native AOT guardrail.

You can read the selector expressions below to understand how scanning resolves without running anything — that is the whole point of a compile-time provider.

Each library is a plain class library that references Specular. Collectively they cover interface-matching and attribute-based registration, three lifetimes, and one opt-out type.

LibraryStyleLifetime(s)Notable
Specular.Samples.Cataloginterface-matchingSingletonIXxxService → XxxService
Specular.Samples.Notificationsattribute ([ServiceRegistration])Transient (AsSelf)generic + non-generic attribute
Specular.Samples.Diagnosticsinterface-matchingScopedone [ExcludeFromSampleScan] opt-out

A host calls provider.Scan(services, selector) once per library. Each selector is hashed at the call site and resolved by the source generator at build time into concrete registrations — there is no runtime reflection.

1. Interface-matching, Singleton (Catalog)

Section titled “1. Interface-matching, Singleton (Catalog)”
provider.Scan(
services,
z => z.FromAssemblyOf<IProductService>()
.AddClasses(f => f.InExactNamespaceOf<IProductService>())
.AsMatchingInterface()
.WithSingletonLifetime()
);

AsMatchingInterface() registers ProductService as IProductService, CategoryService as ICategoryService, and so on.

2. Attribute-based, Transient as-self (Notifications)

Section titled “2. Attribute-based, Transient as-self (Notifications)”
provider.Scan(
services,
z => z.FromAssemblyOf<NotificationDispatcher>()
.AddClasses(f => f.WithAttribute<ServiceRegistrationAttribute>())
.AsSelf()
.WithTransientLifetime()
);

Only types carrying [ServiceRegistration] are registered, each as its own concrete type.

3. Interface-matching with an opt-out, Scoped (Diagnostics)

Section titled “3. Interface-matching with an opt-out, Scoped (Diagnostics)”
provider.Scan(
services,
z => z.FromAssemblyOf<IHealthCheck>()
.AddClasses(f => f.WithoutAttribute<ExcludeFromSampleScanAttribute>())
.AsMatchingInterface()
.WithScopedLifetime()
);

WithoutAttribute<ExcludeFromSampleScanAttribute>() is why the opt-out type never appears in the discovered set — the host asserts its absence.

Every host runs the same three Scan calls from samples/hosts/Shared/SampleScan.cs, linked into each project so that each host’s own generator resolves them, and compares the result with a hard-coded expected service set. Each prints a SPECULAR-SAMPLE: MATCH … (or MISMATCH …) line.

HostKindHeadsProves
Specular.Samples.Consoleconsolenet10.0, net11.0exits non-zero on mismatch; zero-warning Native AOT publish
Specular.Samples.WebASP.NET minimal APInet10.0, net11.0fail-fast at startup on mismatch; /services lists discovery; Native AOT
Specular.Samples.BlazorWasmBlazor WebAssemblynet10.0, net11.0scanning in the browser, incl. the net11.0 browser-wasm (no runtime async) build
Specular.Samples.UnoUno Platform (Skia renderer)net11.0 desktop, WebAssembly, Android, iOSscanning in an Uno app on every Uno head
Specular.Samples.Maui.NET MAUInet10.0/net11.0 Android, iOS, Mac Catalyst, Windowsscanning in a MAUI app, including the per-RID mobile heads

The Uno and MAUI hosts need .NET workloads for most heads, so Specular.slnx doesn’t build them; pick heads with SpecularSampleTargetFrameworks (; escaped as %3B on the command line):

Terminal window
dotnet build samples/hosts/Specular.Samples.Maui -p:SpecularSampleTargetFrameworks=net10.0-android%3Bnet11.0-android

The Samples workflow (.github/workflows/samples.yml) runs on Linux, macOS and Windows. On each OS it builds the hosts, runs them, and checks for the MATCH line with samples/smoke.mjs:

HostChecked at runtimeBuild only
Console, WebNative AOT binaries on every OS (Web: GET / must report the match)
Blazor WebAssemblypublished app in headless Chrome on every OS (the browser console must log the match)
Unodesktop head on every OS (SPECULAR_SAMPLE_SMOKE=1 exits before a window opens); WebAssembly head in headless ChromeAndroid, iOS
MAUIMac Catalyst head (SPECULAR_SAMPLE_SMOKE=1 exits before UIKit starts)Android, iOS, Windows

To run the same check locally:

Terminal window
node samples/smoke.mjs exe -- samples/hosts/Specular.Samples.Console/bin/Debug/net10.0/Specular.Samples.Console
node samples/smoke.mjs browser samples/hosts/Specular.Samples.BlazorWasm/bin/Release/net10.0/publish/wwwroot