NeedlrSourceGenBootstrap

NexusLabs.Needlr.Generators

NeedlrSourceGenBootstrap Class

Runtime bootstrap registry for source-generated Needlr components.

public static class NeedlrSourceGenBootstrap

Inheritance System.Object 🡒 NeedlrSourceGenBootstrap

Remarks

The source generator emits a module initializer in the host assembly that calls one of the Register overloads with the generated TypeRegistry identity and providers. Needlr runtime can then discover generated registries without any runtime reflection.

Methods

NeedlrSourceGenBootstrap.Register(Func<IReadOnlyList<InjectableTypeInfo>>, Func<IReadOnlyList<PluginTypeInfo>>) Method

Registers the generated type and plugin providers for this application.

public static void Register(System.Func<System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.Generators.InjectableTypeInfo>> injectableTypeProvider, System.Func<System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.Generators.PluginTypeInfo>> pluginTypeProvider);

Parameters

injectableTypeProvider System.Func<System.Collections.Generic.IReadOnlyList<InjectableTypeInfo>>

pluginTypeProvider System.Func<System.Collections.Generic.IReadOnlyList<PluginTypeInfo>>

NeedlrSourceGenBootstrap.Register(Func<IReadOnlyList<InjectableTypeInfo>>, Func<IReadOnlyList<PluginTypeInfo>>, Action<object>) Method

Registers the generated type, plugin, and decorator providers for this application.

public static void Register(System.Func<System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.Generators.InjectableTypeInfo>> injectableTypeProvider, System.Func<System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.Generators.PluginTypeInfo>> pluginTypeProvider, System.Action<object>? decoratorApplier);

Parameters

injectableTypeProvider System.Func<System.Collections.Generic.IReadOnlyList<InjectableTypeInfo>>

Provider for injectable types.

pluginTypeProvider System.Func<System.Collections.Generic.IReadOnlyList<PluginTypeInfo>>

Provider for plugin types.

decoratorApplier System.Action<System.Object>

Action that applies decorators to the service collection. The parameter is an IServiceCollection, but typed as object to avoid dependency on Microsoft.Extensions.DependencyInjection in this assembly.

NeedlrSourceGenBootstrap.Register(Func<IReadOnlyList<InjectableTypeInfo>>, Func<IReadOnlyList<PluginTypeInfo>>, Action<object>, Action<object,object>) Method

Registers the generated type, plugin, decorator, and options providers for this application.

public static void Register(System.Func<System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.Generators.InjectableTypeInfo>> injectableTypeProvider, System.Func<System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.Generators.PluginTypeInfo>> pluginTypeProvider, System.Action<object>? decoratorApplier, System.Action<object,object>? optionsRegistrar);

Parameters

injectableTypeProvider System.Func<System.Collections.Generic.IReadOnlyList<InjectableTypeInfo>>

Provider for injectable types.

pluginTypeProvider System.Func<System.Collections.Generic.IReadOnlyList<PluginTypeInfo>>

Provider for plugin types.

decoratorApplier System.Action<System.Object>

Action that applies decorators to the service collection. The parameter is an IServiceCollection, but typed as object to avoid dependency on Microsoft.Extensions.DependencyInjection in this assembly.

optionsRegistrar System.Action<System.Object,System.Object>

Action that registers options with the service collection and configuration. Parameters are (IServiceCollection, IConfiguration), typed as object to avoid dependencies.

NeedlrSourceGenBootstrap.Register(Type, Func<IReadOnlyList<InjectableTypeInfo>>, Func<IReadOnlyList<PluginTypeInfo>>) Method

Registers the generated registry identity and its type and plugin providers.

public static void Register(System.Type registryParticipantType, System.Func<System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.Generators.InjectableTypeInfo>> injectableTypeProvider, System.Func<System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.Generators.PluginTypeInfo>> pluginTypeProvider);

Parameters

registryParticipantType System.Type

A generated type whose assembly identifies the registry participant.

injectableTypeProvider System.Func<System.Collections.Generic.IReadOnlyList<InjectableTypeInfo>>

Provider for injectable types.

pluginTypeProvider System.Func<System.Collections.Generic.IReadOnlyList<PluginTypeInfo>>

Provider for plugin types.

Example

NeedlrSourceGenBootstrap.Register(
    typeof(MyApp.Generated.TypeRegistry),
    MyApp.Generated.TypeRegistry.GetInjectableTypes,
    MyApp.Generated.TypeRegistry.GetPluginTypes);

Remarks

The generated TypeRegistry type is carried separately from injectable and plugin metadata so assemblies with empty registries remain visible to Needlr plugins.

NeedlrSourceGenBootstrap.Register(Type, Func<IReadOnlyList<InjectableTypeInfo>>, Func<IReadOnlyList<PluginTypeInfo>>, Action<object>, Action<object,object>) Method

Registers the generated registry identity and its type, plugin, decorator, and options providers.

public static void Register(System.Type registryParticipantType, System.Func<System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.Generators.InjectableTypeInfo>> injectableTypeProvider, System.Func<System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.Generators.PluginTypeInfo>> pluginTypeProvider, System.Action<object>? decoratorApplier, System.Action<object,object>? optionsRegistrar);

Parameters

registryParticipantType System.Type

A generated type whose assembly identifies the registry participant.

injectableTypeProvider System.Func<System.Collections.Generic.IReadOnlyList<InjectableTypeInfo>>

Provider for injectable types.

pluginTypeProvider System.Func<System.Collections.Generic.IReadOnlyList<PluginTypeInfo>>

Provider for plugin types.

decoratorApplier System.Action<System.Object>

Action that applies decorators to the service collection. The parameter is an IServiceCollection, but typed as object to avoid dependency on Microsoft.Extensions.DependencyInjection in this assembly.

optionsRegistrar System.Action<System.Object,System.Object>

Action that registers options with the service collection and configuration. Parameters are (IServiceCollection, IConfiguration), typed as object to avoid dependencies.

Example

NeedlrSourceGenBootstrap.Register(
    typeof(MyApp.Generated.TypeRegistry),
    MyApp.Generated.TypeRegistry.GetInjectableTypes,
    MyApp.Generated.TypeRegistry.GetPluginTypes,
    null,
    null);

Remarks

Generated module initializers use this overload so the runtime can retain assembly identity even when both metadata providers return empty collections.

NeedlrSourceGenBootstrap.RegisterExtension(Action<object,object>) Method

Registers an extension that provides additional service registrations. Extensions are invoked after the main options registrar during BuildServiceProvider.

public static void RegisterExtension(System.Action<object,object> extensionRegistrar);

Parameters

extensionRegistrar System.Action<System.Object,System.Object>

Action that registers extension services with the service collection and configuration. Parameters are (IServiceCollection, IConfiguration), typed as object to avoid dependencies.

Remarks

Use this method from extension package module initializers to register additional services. For example, FluentValidation can register its validators without modifying core Needlr.

Needlr's own runtime composition (ConfiguredSyringe, WebApplicationSyringe, and MauiSyringe) reads options and extension registrars from NexusLabs.Needlr.SourceGenRegistry so that NexusLabs.Needlr.Injection does not need a dependency on this assembly. Extension packages that already depend on NexusLabs.Needlr.Generators.Attributes may keep using this registry; extension packages that only depend on NexusLabs.Needlr should use SourceGenRegistry.RegisterExtension instead.

NeedlrSourceGenBootstrap.RegisterPlugins(Func<IReadOnlyList<PluginTypeInfo>>) Method

Registers plugin types that were emitted by another source generator and are therefore invisible to TypeRegistryGenerator at compile time.

public static void RegisterPlugins(System.Func<System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.Generators.PluginTypeInfo>> pluginTypeProvider);

Parameters

pluginTypeProvider System.Func<System.Collections.Generic.IReadOnlyList<PluginTypeInfo>>

Provider for the generator-emitted plugin types.

Remarks

Roslyn source generators run in isolation — each generator receives the original compilation and cannot see types emitted by other generators. This means TypeRegistryGenerator cannot discover types produced by a second generator (e.g., a CacheProviderGenerator emitting *CacheConfiguration records).

The solution is a runtime registration: the second generator emits a [ModuleInitializer] that calls RegisterPlugins(). Module initializers run before any user code, so by the time the application calls IPluginFactory.CreatePluginsFromAssemblies<T>() all providers are combined.

Example of what the second generator should emit:

[ModuleInitializer]
internal static void Initialize()
{
    NeedlrSourceGenBootstrap.RegisterPlugins(() =>
    [
        new PluginTypeInfo(
            typeof(MyCacheConfiguration),
            [typeof(CacheConfiguration)],
            static () => new MyCacheConfiguration(),
            [])
    ]);
}

NeedlrSourceGenBootstrap.TryGetDecoratorApplier(Action<object>) Method

Gets the decorator applier (if any).

public static bool TryGetDecoratorApplier(out System.Action<object>? decoratorApplier);

Parameters

decoratorApplier System.Action<System.Object>

Action that applies decorators to the service collection. The parameter is an IServiceCollection, but typed as object to avoid dependency on Microsoft.Extensions.DependencyInjection in this assembly.

Returns

System.Boolean
True if a decorator applier is registered.

NeedlrSourceGenBootstrap.TryGetExtensionRegistrar(Action<object,object>) Method

Gets the combined extension registrar (if any extensions are registered).

public static bool TryGetExtensionRegistrar(out System.Action<object,object>? extensionRegistrar);

Parameters

extensionRegistrar System.Action<System.Object,System.Object>

Combined action that invokes all registered extensions. Parameters are (IServiceCollection, IConfiguration), typed as object to avoid dependencies.

Returns

System.Boolean
True if any extension registrars are registered.

Remarks

The returned action invokes every registrar in registration order. Unlike TryGetProviders, extension registrars are not affected by test scopes.

NeedlrSourceGenBootstrap.TryGetOptionsRegistrar(Action<object,object>) Method

Gets the options registrar (if any).

public static bool TryGetOptionsRegistrar(out System.Action<object,object>? optionsRegistrar);

Parameters

optionsRegistrar System.Action<System.Object,System.Object>

Action that registers options with the service collection and configuration. Parameters are (IServiceCollection, IConfiguration), typed as object to avoid dependencies.

Returns

System.Boolean
True if an options registrar is registered.

Remarks

The options registrar is supplied by the generated module initializer through the four-argument Register(Func<IReadOnlyList<InjectableTypeInfo>>, Func<IReadOnlyList<PluginTypeInfo>>, Action<object>, Action<object,object>) overload. Needlr's own runtime composition reads options registrars from NexusLabs.Needlr.SourceGenRegistry; this accessor exists for hosts that compose generated registrations directly against this assembly.

NeedlrSourceGenBootstrap.TryGetProviders(Func<IReadOnlyList<InjectableTypeInfo>>, Func<IReadOnlyList<PluginTypeInfo>>) Method

Gets the registered providers (if any).

public static bool TryGetProviders(out System.Func<System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.Generators.InjectableTypeInfo>> injectableTypeProvider, out System.Func<System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.Generators.PluginTypeInfo>> pluginTypeProvider);

Parameters

injectableTypeProvider System.Func<System.Collections.Generic.IReadOnlyList<InjectableTypeInfo>>

pluginTypeProvider System.Func<System.Collections.Generic.IReadOnlyList<PluginTypeInfo>>

Returns

System.Boolean

NeedlrSourceGenBootstrap.TryGetProviders(Func<IReadOnlyList<InjectableTypeInfo>>, Func<IReadOnlyList<PluginTypeInfo>>, IReadOnlyList<Type>) Method

Gets the registered providers and generated registry participant types, if any.

public static bool TryGetProviders(out System.Func<System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.Generators.InjectableTypeInfo>> injectableTypeProvider, out System.Func<System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.Generators.PluginTypeInfo>> pluginTypeProvider, out System.Collections.Generic.IReadOnlyList<System.Type> registryParticipantTypes);

Parameters

injectableTypeProvider System.Func<System.Collections.Generic.IReadOnlyList<InjectableTypeInfo>>

The combined injectable type provider.

pluginTypeProvider System.Func<System.Collections.Generic.IReadOnlyList<PluginTypeInfo>>

The combined plugin type provider.

registryParticipantTypes System.Collections.Generic.IReadOnlyList<System.Type>

Generated types whose assemblies identify every registered TypeRegistry participant.

Returns

System.Boolean
true when at least one source-generated registration exists; otherwise, false.

Example

if (NeedlrSourceGenBootstrap.TryGetProviders(
    out var injectableTypes,
    out var pluginTypes,
    out var registryParticipants))
{
    // Configure the source-generated runtime from the returned metadata.
}

Remarks

Participant types are returned in registration order and deduplicated by type. Consumers can derive assembly identity from them without scanning the current AppDomain.