Immediate.Injections 1.2.0

Immediate.Injections

Immediate.Injections is a support package for Microsoft.Extensions.DependencyInjection which allows declaring registrations through attributes. This package supports multiple registration strategies, duplicate-handling strategies, tagging, and much more.

Installation

dotnet add package Immediate.Injections

Basic Usage

Declaring a registration

Apply one of the three lifetime attributes to a class or record:

[RegisterSingleton]
public class MyService;

[RegisterScoped]
public class MyScopedService;

[RegisterTransient]
public class MyTransientService<T>;

By default (when no RegistrationStrategy is set at the attribute or assembly level), a class is registered as itself. Generic classes will be registered using open-generics.

Adding declared registrations to the IServiceCollection collection

In your Program.cs, add a call to services.AddXxxServices(), where Xxx is the application identifier. By default, this is the short form of the assembly name. For example:

• For a project named Web, it will be services.AddWebServices()
• For a project named Application.Web, it will be services.AddApplicationWebServices()

However, this name can be overridden using [assembly: ImmediateAssemblyIdentifierAttribute("SomeIdentifier")].

Tags

Tags can be passed to selectively register only tagged services:

[RegisterSingleton(Tags = ["tag-a"])]
public class MyService;

builder.Services.AddMyProjectServices("tag-a", "tag-b");

Attribute Reference

All three lifetime attributes — RegisterSingleton, RegisterScoped, RegisterTransient — share the same properties.

ServiceType

Registers the class as the specified service type. The class must be assignable to it.

[RegisterSingleton(ServiceType = typeof(IMyService))]
public class MyService : IMyService { }

Alternatively, a concrete registration may be declared using generic attributes.

[RegisterSingleton<IMyService>]
public class MyService : IMyService { }

[RegisterScoped<IService<string>>]
public class MyService<T> : IMyService<string>

RegistrationStrategy

Controls which service types are generated. Mutually exclusive with ServiceType.

[RegisterSingleton(RegistrationStrategy = RegistrationStrategy.ImplementedInterfaces)]
public class MyService : IMyService { }

DuplicateStrategy

Controls what happens when a registration for the same service type already exists.

ServiceKey

Registers the service as a keyed service.

[RegisterSingleton(ServiceKey = "my-key")]
public class MyService { }

Factory

Name of a static factory method on the class to use as ImplementationFactory. The method must be static, return the class type, and accept (IServiceProvider) for non-keyed or (IServiceProvider, object) for keyed registrations. Cannot be combined with UseProxyFactory or used on open generic types. Factories cannot be used with generic target classes.

[RegisterSingleton(Factory = nameof(Create))]
public class MyService
{
    public static MyService Create(IServiceProvider sp) => new MyService();
}

UseProxyFactory

When true, the registration uses ServiceProviderServiceExtensions.GetRequiredService<T> (or the keyed equivalent) as the factory. This produces a proxy registration — it does not register the implementation itself, but resolves it from the container.

UseProxyFactory = true be combined with the following:

• A provided Factory,
• RegistrationStrategy = Self, or
• Generic target classes

[RegisterSingleton(ServiceType = typeof(IMyService), UseProxyFactory = true)]
public class MyService : IMyService { }

Tags

Assigns string tags to the registration. When AddXxxServices is called with tag arguments, only registrations that share at least one tag (or registrations with no tags) are included.

[RegisterSingleton(Tags = ["worker", "background"])]
public class BackgroundWorker { }

Global Configuration

ServiceKey and DuplicationStrategy can be configured globally with [RegistrationDefaults] attribute applied to the assembly.

[assembly: RegistrationDefaults(
	RegistrationStrategy = RegistrationStrategy.SelfAndImplementedInterfaces,
	DuplicateStrategy = DuplicateStrategy.Replace,
	UseProxyFactory = true
)]

Per-attribute values take precedence over assembly defaults.

[RegisterServices]

Apply this attribute to a static void method to have it called as part of AddXxxServices. The method must accept IServiceCollection as its first parameter, and optionally ReadOnlySpan<string> as its second parameter to receive the tags passed to AddXxxServices.

public static class ManualRegistrations
{
    [RegisterServices]
    public static void Register(IServiceCollection services) { ... }

    // or, to receive tags:
    [RegisterServices]
    public static void RegisterWithTags(IServiceCollection services, ReadOnlySpan<string> tags) { ... }
}

[RegisterHostedService]

Apply [RegisterHostedService] to a concrete, non-generic class implementing IHostedService (or deriving from BackgroundService) to include it in AddXxxServices as a singleton hosted service. Reference Microsoft.Extensions.Hosting.Abstractions in the consuming project.

[RegisterHostedService(Tags = ["background"])]
public sealed class Worker : BackgroundService
{
    protected override Task ExecuteAsync(CancellationToken stoppingToken) => Task.CompletedTask;
}

Like AddHostedService<T>(), this registers IHostedService and ignores repeated registrations of the same implementation. Tags filters registrations using the usual AddXxxServices tags. The concrete class is not registered separately.

Set Order to control registration order, for example [RegisterHostedService(Order = 10)]. Services without an explicit order are registered first, followed by ordered services in ascending order. Omitting the order means that initialization before or after any other hosted service is assumed not to matter. Explicit orders must be unique across the assembly, including services with different tags (INJ0019).

[RegisterOptions]

Apply this attribute to a class or record to register it as an options type bound to a configuration section, as part of AddXxxServices.

[RegisterOptions]
public sealed class PositionOptions
{
    public string Title { get; set; } = string.Empty;
}

Validation

A validator can be registered alongside the options using the generic attribute. The validator must implement IValidateOptions<TOptions> for the options type.

[Validate]
[RegisterOptions(ValidateOnStart = true)]
public sealed partial class PositionOptions : IValidationTarget<PositionOptions>
{
    [NotEmpty]
    public string Title { get; set; } = string.Empty;
}

Migration

From Injectio

• The Tags parameter receives a string[] instead of a comma-separated string. Example: Tags = "foo,bar" becomes Tags = ["foo", "bar"]
• The RegistrationStrategy.SelfWithInterfaces enum value changes to RegistrationStrategy.SelfAndImplementedInterfaces
• The Registration parameter changes to RegistrationStrategy
• The Duplicate parameter becomes DuplicateStrategy
• Assembly name override moves from MSBuild property to [ImmediateAssemblyIdentifier] attribute

From AutoRegisterInject

• The [TryRegisterXxx] attributes are removed; but the behavior is implemented using a parameter. Example: DuplicateStrategy = DuplicateStrategy.Skip