IoCTools.Abstractions 1.9.1

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<…>], and [ConditionalService] live on the class, so intent never leaves the type
• Dependency sets – Implement IDependencySet to reuse dependency bundles across services
• Inheritance-aware – Derived services inherit base class lifetime; diagnostics validate across the full chain
• 100+ diagnostics – Build-time validation catches missing lifetimes, circular dependencies, lifetime mismatches, open-generic edge cases, and FluentValidation anti-patterns
• Zero reflection – Everything happens at compile time; generated code is plain C# you can inspect

Authoring Posture

• [Inject] is deprecated in 1.6.0 and emits IOC095. A Roslyn code fix plus ioc-tools migrate-inject migrate in bulk. Scheduled for removal in 2.0.
• [DependsOn<T>] is the source-of-truth for explicit service dependencies.
• [DependsOnConfiguration<T>] / [DependsOnOptions<T>] for config dependencies. InjectConfiguration stays supported but is not preferred.
• Auto-deps (1.6.0+) declare ambient dependencies once per assembly: [assembly: AutoDep<T>], [assembly: AutoDepOpen(typeof(ILogger<>))], plus Microsoft.Extensions.Logging.ILogger<T> is auto-detected with zero configuration. See docs/auto-deps.md.

Installation

dotnet add package IoCTools.Abstractions
dotnet add package IoCTools.Generator

Or directly in your project file:

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

What's New in v1.9.0

See CHANGELOG.md for the full history.

Added in 1.9.0

• [Cover<T>(ConcreteHandling = ConcreteHandling.ForceMock)] — opt-out for the auto-concrete promotion path. Previously, every concrete-class constructor dependency with an accessible parameterless constructor was silently materialized as a real instance (ParameterRole.ConcreteInstance) with a Configure{Dep}(Action<T>) helper, which lost depth-2/3 mock coverage when the SUT composed a concrete collaborator from port mocks. The new ConcreteHandling named argument (enum: Auto (default, preserves prior behavior), ForceMock) lets a test opt every non-special concrete dependency into the standard Mock<T> substitution. Existing fixtures are unchanged.
  • Constraint: ForceMock requires virtual (or abstract) public methods on the concrete target type. Moq can only intercept virtual instance methods on classes; concretes with sealed-by-default methods (the C# default) compile cleanly but Setup(...) silently no-ops and the real method body runs against default backing fields. See docs/testing.md § "Concrete Handling Modes" and the XML doc comments on CoverAttribute<>.ConcreteHandling for the interface-extraction recommendation.

Changed in 1.9.0

• TestFixturePipeline syntax predicate tightened — the pipeline now syntactically pre-filters to types whose attribute lists name Cover / CoverAttribute before invoking the semantic model. IDE responsiveness improvement; no consumer-visible behavior change.
• TestFixturePipeline namespace match is now exact — previously a Contains("IoCTools.Testing") substring check false-positived on consumer namespaces like MyCorp.IoCTools.Testing.Extensions.CoverAttribute<T>, emitting a duplicate fixture under the wrong attribute resolution. The check is now an exact comparison against IoCTools.Testing.Annotations.
• Cover<T>.Logger named argument now parsed by enum-member symbol name rather than raw int value, so future reorderings of FixtureLoggerProfile enum members cannot silently misclassify. Falls back to the prior integer comparison defensively.

Fixed in 1.9.0

• FixtureEmitter.CurrentOptionsProfile mutable-static state removed — Roslyn incremental generators must be pure functions of their inputs; a mutable static property breaks the generator cache and can race when multiple compilations run concurrently in the same generator-host AppDomain. The property was unread outside its own declaration; it has been deleted. No consumer-visible behavior change.

Changed in 1.8.0

• [InjectConfiguration] / [DependsOnConfiguration<T>] optional complex-type sections now fall back to new T() when the section is absent — instead of forwarding null through the null-forgiving operator. Previously the generator emitted configuration.GetSection("X").Get<T>()!, which silently assigned null when the section was missing and NPE'd on first dereference. The generator now emits configuration.GetSection("X").Get<T>() ?? new T() for complex-type fields whose type has an accessible parameterless constructor. Required sections (Required = true, the default) still throw fast. Interfaces, abstract classes, and types without a parameterless constructor continue to emit the ! suppression. Collection bindings and primitive GetValue<T> bindings are unchanged. Behavior change — consumers who relied on _field == null to detect an absent optional section will now observe a default-constructed instance instead; this drove the minor-version bump rather than a patch.

Earlier — 1.7.x highlights

• AnalysisScope model + DiagnosticGate — production-only diagnostics (IOC081/IOC082/IOC086) auto-exempt test projects via the IsTestProject MSBuild property forwarded from Microsoft.NET.Test.Sdk. No naming heuristics.
• IOC110 (Warning, configurable) — deterministic multi-impl lifetime diagnostic; replaces the previous non-deterministic single-impl selection that caused IOC012 to fire in Rider but pass silently in CLI.
• [RegisterAs<T>] + [RegisterAsAll] compose with IHostedService — concrete registered once at the declared lifetime, companion interfaces bridged via GetRequiredService<TImpl>(), and IHostedService bridged to the same instance.
• Test fixture generator v2 (IoCTools.Testing) — FixtureMemberPlanner separates planning from emission; generated fixtures enable nullable context, emit new modifier on derived hidden members, support GetRequiredSection/binder-style configuration reads, and treat IClock as fixture-provided.
• Multitarget CLI — IoCTools.Tools.Cli ships for both net9.0 and net10.0.

Getting Started in Three Steps

1. Annotate a partial service

   [DependsOn<ILogger<EmailService>>]
   public partial class EmailService : IEmailService
   {
       public Task SendAsync(string to, string subject, string body) => Task.CompletedTask;
   }
   

   Tip: [Scoped] is implied for partial classes implementing interfaces. Add [Singleton]/[Transient] only when you want to change that default.

   Full getting started guide

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);
   

Common Open-Generic Pattern

[Scoped]
[RegisterAsAll]
public partial class Repository<T> : IRepository<T> where T : class
{
}

That common open-generic path is supported. If you ask for InstanceSharing.Shared across open-generic interface aliases, IoCTools emits the secondary IOC095 descriptor and falls back to valid direct registrations because Microsoft.Extensions.DependencyInjection does not support open-generic factory aliases. (In 1.6.0+, the primary IOC095 descriptor is the [Inject] deprecation diagnostic — both ship under the same ID; see diagnostics.md.)

Platform Support

IoCTools works with .NET Framework 4.6.1+, .NET Core 2.0+, and .NET 5+. The generator targets netstandard2.0 internally, but your service code can use any C# features your framework supports. See platform constraints for details.

Testing with IoCTools

The IoCTools.Testing package auto-generates test fixtures, eliminating mock declaration boilerplate.

using IoCTools.Testing.Annotations;

[Cover<UserService>]
public partial class UserServiceTests
{
    [Fact]
    public void Test() {
        var result = Sut.GetById(1); // Lazy auto-generated SUT
    }
}

Full testing guide

The CLI includes test scaffold and fixture-aware evidence --test-fixtures paths for downstream adoption:

dotnet ioc-tools test scaffold --project src/App.csproj --type MyApp.Services.UserService --dry-run
dotnet ioc-tools evidence --project tests/App.Tests.csproj --production-project src/App.csproj --test-fixtures

IoCTools CLI

IoCTools.Tools.Cli ships as a dotnet global/local tool (dotnet ioc-tools …). It interrogates your project with the real IoCTools generator.

Installation

dotnet pack IoCTools.Tools.Cli/IoCTools.Tools.Cli.csproj -c Release -o ./artifacts
dotnet tool install --global --add-source ./artifacts IoCTools.Tools.Cli

Commands

Full CLI reference

Before & After: Replacing DI Smells

Legacy (manual, brittle)

public class LegacyBillingService : IBillingService
{
    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;
    }
}

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

Problems: duplicated registrations, runtime config lookups, no analyzer guardrails.

IoCTools (attributes, analyzers, generated DI)

using IoCTools.Abstractions.Annotations;

[Scoped]
[DependsOn<ILogger<BillingService>, IHttpClientFactory, IClock>]
[DependsOnConfiguration<string>("Billing:BaseUrl", Required = true)]
[DependsOnConfiguration<int>("Billing:RetryCount", DefaultValue = "3")]
public partial class BillingService : IBillingService
{
    public async Task ChargeAsync(BillingRequest request)
    {
        using var client = _httpClientFactory.CreateClient("billing");
        // _logger, _httpClientFactory, _clock, _baseUrl, _retryCount all available
    }
}

Generated code creates the constructor, binds configuration, and registers everything via builder.Services.AddYourAssemblyRegisteredServices(configuration).

Attribute Reference

Complete attribute reference: docs/attributes.md

Key attributes: [Scoped], [Singleton], [Transient], [DependsOn<T>], [DependsOnConfiguration<T>], [DependsOnOptions<T>], [RegisterAs<T>], [ConditionalService], and the 1.6.0 auto-deps surface ([assembly: AutoDep<T>], [assembly: AutoDepOpen(...)], [AutoDeps<TProfile>], [NoAutoDeps], …)

Diagnostics Reference

IoCTools provides core diagnostics through IOC110, plus testing diagnostics (TDIAG01 through TDIAG08) and FluentValidation diagnostics (IOC100-IOC102). See diagnostics.md for the full list.

Error-Severity Diagnostics

View all diagnostics including warnings and info

Configuration

IoCTools reads configuration from MSBuild properties/.editorconfig. Common knobs:

See configuration reference

Samples & License

• IoCTools.Sample demonstrates every attribute, diagnostic, and configuration scenario
• Licensed under MIT. See LICENSE