IoCTools.Generator 1.2.0

IoCTools

A Roslyn source generator that lets each service declare its own lifetime, dependencies, and registration intent with small attributes. IoCTools emits constructors, service registrations, and analyzers at build time—no reflection, no runtime scanning.

Highlights

• Self-describing services – [Scoped], [DependsOn<T>], [RegisterAs<…>], [ConditionalService], and [InjectConfiguration] live on the class, so intent never leaves the type.
• Accurate registrations – The generator produces Add<YourAssembly>RegisteredServices() extensions that register concrete types, interfaces, options bindings, conditional services, and background workers.
• Analyzer coverage – 30+ diagnostics (IOC001–IOC040) keep registrations honest: missing lifetimes, redundant RegisterAs, conflicting [SkipRegistration], invalid config keys, singleton/ scoped mismatches, etc.
• Zero reflection – Everything happens at compile time. Startup cost stays flat, and generated code is plain C# you can inspect.

IoCTools treats each service class as the single source of truth for its registration story. Lifetimes, interface exposure, configuration needs, and conditional flags live beside the implementation, so setup code isn’t forced to guess or duplicate those concerns. This separation keeps startup/bootstrap files lean while ensuring services are designed with the lifetime/registration model they actually require.

Installation

dotnet add package IoCTools.Abstractions
dotnet add package IoCTools.Generator --prerelease

Or directly in your project file:

<ItemGroup>
  <PackageReference Include="IoCTools.Abstractions" Version="*" />
  <PackageReference Include="IoCTools.Generator" Version="*" PrivateAssets="all" />
</ItemGroup>

Getting Started in Three Steps

1. Annotate a partial service

   [DependsOn<ILogger<EmailService>>] // Scoped implied when DependsOn/Inject/etc. are present (IOC033 otherwise)
   public partial class EmailService : IEmailService
   {
       public Task SendAsync(string to, string subject, string body) => Task.CompletedTask;
   }
   

   Tip: Any partial class that implements at least one interface is treated as a scoped service even without [Scoped]. Add [Singleton]/[Transient] (or [Scoped] when you truly need to override diagnostics) only when you want to change that default. You can change the implicit lifetime globally via build_property.IoCToolsDefaultServiceLifetime, and both the generated registrations and IOC012/IOC013 diagnostics honor whatever value you pick.

2. Build – IoCTools emits Add<YourAssembly>RegisteredServices() into <AssemblyName>.Extensions.Generated.

3. Call the extension during startup

   using YourAssembly.Extensions.Generated;
   
   var builder = WebApplication.CreateBuilder(args);
   builder.Services.AddYourAssemblyRegisteredServices(builder.Configuration);
   

Before & After: Replacing DI Smells

Legacy BillingService (manual, brittle)

public class LegacyBillingService : IBillingService, ILegacyDiagnostics
{
    private readonly ILogger<LegacyBillingService> _logger;
    private readonly IHttpClientFactory _httpClients;
    private readonly BillingOptions _options;
    private readonly IConfiguration _config;

    public LegacyBillingService(
        ILogger<LegacyBillingService> logger,
        IHttpClientFactory httpClients,
        IOptionsMonitor<BillingOptions> options,
        IConfiguration config)
    {
        _logger = logger;
        _httpClients = httpClients;
        _options = options.CurrentValue;
        _config = config;
    }

    public async Task ChargeAsync(BillingRequest request)
    {
        var baseUrl = _config["Billing:BaseUrl"] ?? throw new InvalidOperationException("Billing options missing");
        // ... manual retry logic based on _options.RetryCount ...
    }
}

services.AddHttpClient();
services.AddSingleton<IOptionsMonitor<BillingOptions>, BillingOptionsMonitor>();
services.Configure<BillingOptions>(configuration.GetSection("Billing"));
services.AddScoped<IBillingService, LegacyBillingService>();
services.AddScoped<ILegacyDiagnostics, LegacyBillingService>();

Problems: duplicated registrations, runtime config lookups every call, manual interface wiring, no analyzer guardrails.

IoCTools BillingService (attributes, analyzers, generated DI)

using IoCTools.Abstractions.Annotations;
using IoCTools.Abstractions.Enumerations;

[Scoped]
[RegisterAs<IBillingService, IBillingDiagnostics>(InstanceSharing.Shared)]
[ConditionalService(Environment = "Production,Staging")]
[DependsOn<ILogger<BillingService>, IHttpClientFactory, IClock>]
[SkipRegistration<ILegacyDiagnostics>] // Keep internal interface private to DI
public partial class BillingService : IBillingService, IBillingDiagnostics, ILegacyDiagnostics
{
    [InjectConfiguration("Billing:BaseUrl", Required = true)] private readonly string _baseUrl;
    [InjectConfiguration("Billing:RetryCount", DefaultValue = "3")] private readonly int _retryCount;
    [Inject] private readonly IMeter<BillingService> _meter; // field genuinely reused across methods

    public async Task ChargeAsync(BillingRequest request)
    {
        using var client = _httpClientFactory.CreateClient("billing");
        // Generated constructor supplies _logger, _httpClientFactory, _clock, and configuration fields.
    }
}

Generated code now:

• Creates a constructor that accepts ILogger<BillingService> logger, IHttpClientFactory httpClientFactory, and IClock clock (from [DependsOn<…>]).
• Injects _meter, _baseUrl, and _retryCount per attribute metadata.
• Registers the service once via builder.Services.AddYourAssemblyRegisteredServices(configuration); – IoCTools emits services.AddScoped<IBillingService, BillingService>() plus shared-instance factory wiring for IBillingDiagnostics.
• Emits diagnostics if [Scoped] becomes redundant (IOC033), if [SkipRegistration<ILegacyDiagnostics>] can never trigger (IOC009/IOC038), or if configuration keys are invalid (IOC016–IOC017).

Naming & Generated Surface

Dependency name derivation

IoCTools strips a leading I from interface names, applies the configured naming style, and prefixes fields with _ by default. When SnakeCase is enabled it uses:

Regex.Replace(fieldBaseName, "(?<!^)([A-Z])", "_$1").ToLowerInvariant();

So IEmailService → _emailService, IDetailedInvoiceAuditor → _detailedInvoiceAuditor, and with snake_case _detailed_invoice_auditor. Diagnostics IOC035 fire when an [Inject] field matches this auto-generated pattern, nudging you back to [DependsOn<…>] when a field isn’t required.

Generated registration extension

For assembly IoCTools.Sample the generator emits:

namespace IoCTools.Sample.Extensions.Generated;

public static class GeneratedServiceCollectionExtensions
{
    public static IServiceCollection AddIoCToolsSampleRegisteredServices(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        // registrations, configuration bindings, AddHostedService calls, etc.
        return services;
    }
}

• Namespace: <AssemblyNameWithoutInvalidChars>.Extensions.Generated.
• Method name: Add<SafeAssemblyName>RegisteredServices (periods removed, hyphens/spaces replaced with _).
• Bring the namespace into scope (using YourAssembly.Extensions.Generated;) and call the method from Program.cs. Background services, conditional registrations, and configuration bindings flow through that single call.
• The generator adds the IConfiguration parameter only when a project actually uses [InjectConfiguration] or [ConditionalService]—otherwise the extension is AddYourAssemblyRegisteredServices(this IServiceCollection services).

Attribute Reference

Analyzer (Diagnostic) Reference

Each diagnostic includes a remediation tip in Visual Studio / Rider / CLI build output. Treat them as code reviews from the generator.

Key Workflows

• Dependency hygiene – IOC039 warns when [Inject] or [DependsOn] declarations never get referenced, and IOC040 catches redundant combinations of [Inject] fields and [DependsOn] attributes before they reach generated constructors.
• Configuration injection: [InjectConfiguration] supports complex objects, primitives, and arrays. Pair with diagnostics IOC016–IOC019 to stay honest.
• Conditional services: Use Environment/NotEnvironment for environment-specific registrations and ConfigValue + Equals/NotEquals for feature toggles.
• Background workers: Any partial BackgroundService is registered through AddHostedService<T>(); analyzers enforce singleton lifetimes.
• Lifetime validation: IOC012/IOC013 warn when a singleton captures scoped or transient services; IOC015 watches inheritance chains so longer-lived services never depend on shorter-lived implementations.
• Inheritance chains: Partial base/derived services share the same constructor graph. The generator walks the hierarchy so lifetimes stay consistent (IOC015 protects you) and dependencies from base classes are included automatically.
• Manual/External services: Mark services you register yourself with [ManualService] or [ExternalService] to satisfy the analyzers without disabling them globally.
• Collections: The generator produces IEnumerable<T>/IReadOnlyList<T> wrappers when multiple implementations exist—no manual services.AddSingleton<IEnumerable<T>> needed.

Future Ideas

The current roadmap builds on IOC039/IOC040 by surfacing more of the generator’s work directly in source, so developers rarely need to open .g.cs files:

• IDE quick fixes – ship Roslyn light-bulb actions for IOC039/IOC040 so you can convert [Inject] → [DependsOn], drop redundant declarations, or remove dead dependencies with a click.
• CLI parity for fixes – pair the IDE actions with a dotnet ioc fix/report/describe tool so console and CI workflows can apply the same quick fixes, view redundancy reports, and inspect generated members without opening .g.cs.
• Structured warning aggregates – add a low-severity diagnostic summarizing the dependency hygiene status per class (e.g., “2 unused dependencies, 1 redundant”) to make large refactors easier to triage.
• Fine-grained analyzer knobs – expose MSBuild properties (e.g., IoCToolsUnusedDependencySeverity, IoCToolsRedundantDependencyScope) so teams can tune these warnings per project or per configuration.
• Rich XML documentation & metadata – have generated fields/constructors emit <summary>/<param> details noting which attribute produced them, and optionally tag them with [GeneratedDependency(Attribute = …, DeclaredAt = …)] so Go-To-Definition jumps back to the originating partial.
• Analyzer-assisted navigation – provide info diagnostics/code actions that list generated constructor signatures inline or open a preview window, eliminating the need to browse generated files.
• Partial-class alignment hints – warn (info) when another partial already defines a conflicting field or when [DependsOn] output is unused, including the generated signature in the message for quick fixes.
• Debugger-friendly instrumentation – optionally register a lightweight inspector in DEBUG builds so you can inspect the generated dependency graph at runtime without touching the .g.cs output.
• Service graph dumps – behind an MSBuild flag (e.g., IoCToolsDumpServiceGraph=true), emit a compact JSON summary of each service, its generated fields, and registrations to simplify reviews and CI audits.
• Partial-type mapping guidance – extend analyzers to suggest relocating [DependsOn] declarations to the partial that actually consumes the dependency, preventing future IOC039 hits.

Configuration

IoCTools reads configuration from MSBuild properties/.editorconfig and from an optional IoCTools.Generator.Configuration.GeneratorOptions class. Common knobs:

All properties can live in Directory.Build.props, .editorconfig, or project files. The generator merges “base list + add/remove + exceptions” so you can set organization-wide defaults then fine-tune per project.

Samples & License

• IoCTools.Sample demonstrates every attribute, diagnostic, and configuration scenario (background services, RegisterAs vs RegisterAsAll, shared instances, options binding, etc.).
• Licensed under MIT. See LICENSE.