IoCTools.Abstractions 1.0.0-alpha

IoCTools

Eliminate dependency injection boilerplate and scattered service registrations. IoCTools is a .NET source generator that lets services declare their own dependencies and lifetime directly in their implementation, turning verbose DI configuration into simple, maintainable code.

// Before: Verbose constructor + separate registration
public class OrderService(IPaymentService payment, IEmailService email, 
    ILogger<OrderService> logger) : IOrderService 
{
    private readonly IPaymentService _payment = payment;
    private readonly IEmailService _email = email;
    private readonly ILogger<OrderService> _logger = logger;
}

// Program.cs
builder.Services.AddScoped<IOrderService, OrderService>();
builder.Services.AddScoped<IPaymentService, PaymentService>();
// ... many more lines

// After: Clean service with co-located registration
[Service] 
public partial class OrderService : IOrderService
{
    [Inject] private readonly IPaymentService _payment;
    [Inject] private readonly IEmailService _email;
    [Inject] private readonly ILogger<OrderService> _logger;
}

// Program.cs
builder.Services.AddIoCTools[ProjectName]RegisteredServices(); // All services discovered automatically

🚀 Quick Start

1. Install the packages:

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

2. Mark your service with [Service] and use [Inject] for dependencies:

[Service]
public partial class EmailService : IEmailService
{
    [Inject] private readonly ILogger<EmailService> _logger;
    
    public async Task SendEmailAsync(string to, string subject, string body)
    {
        _logger.LogInformation("Sending email to {To}", to);
        // Implementation here
    }
}

3. Register all services automatically:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddIoCTools[ProjectName]RegisteredServices();
var app = builder.Build();

That's it! 🎉 Your service is now automatically registered with the correct lifetime and all dependencies are injected.

🔧 Optional: Configure Diagnostics

Add these MSBuild properties to your project file to customize diagnostic behavior:

<PropertyGroup>
  
  <IoCToolsNoImplementationSeverity>Error</IoCToolsNoImplementationSeverity>
  
  
  <IoCToolsUnregisteredSeverity>Info</IoCToolsUnregisteredSeverity>
  
  
  <IoCToolsDisableDiagnostics>true</IoCToolsDisableDiagnostics>
</PropertyGroup>

Severity Options: Error, Warning, Info, Hidden

✨ Key Benefits

🔥 Co-located Registration

Service registration happens right where the service is defined, eliminating the hunt through Program.cs

⚡ Zero Boilerplate

No more verbose constructors, parameter assignments, or manual registration calls

🛡️ Compile-Time Safety

Comprehensive diagnostics catch missing implementations, circular dependencies, and lifetime mismatches at build time

🎯 IntelliSense Friendly

Full IDE support with code completion, refactoring, and go-to-definition for generated code

📦 Comprehensive Testing

Extensive sample application with 59 comprehensive examples covering all features and edge cases

🎯 Feature Highlights

Core Features:

• Service Declaration - Mark services with [Service] for automatic registration
• Dependency Injection - Use [Inject] for clean, declarative dependencies
• Lifetime Management - Singleton, Scoped, Transient with validation
• Inheritance Support - Full inheritance hierarchy support with automatic base constructor generation

Advanced Features:

• Configuration Injection - Inject configuration values directly with [InjectConfiguration]
• Conditional Services - Environment and configuration-based service registration
• Multi-Interface Registration - Register services for multiple interfaces with instance sharing control
• Background Services - Simplified background service registration and lifetime validation

Developer Experience:

• Diagnostics - 25+ diagnostic codes for comprehensive validation
• MSBuild Integration - Configure diagnostic behavior and feature toggles
• Namespace Management - Automatic using statement generation for clean generated code
• Advanced Generics - Full support for complex generic scenarios and constraints

📚 Documentation

Getting Started

• Installation - Setup and configuration
• Basic Usage - Your first IoCTools service
• Migration Guide - Migrating from manual DI registration

Core Features

• Service Declaration - [Service] attribute and lifetime options
• Dependency Injection - [Inject] and [DependsOn] patterns
• Constructor Generation - How constructors are generated and customized
• Service Registration - Automatic registration and discovery
• Diagnostics Configuration - MSBuild properties for diagnostic severity control

Advanced Features

• Configuration Injection - [InjectConfiguration] for direct config binding
• Conditional Services - Environment and configuration-based registration
• Multi-Interface Registration - [RegisterAsAll] and instance sharing
• Inheritance - Complex inheritance scenarios and base constructor calls
• Background Services - [BackgroundService] attribute and validation
• Advanced Generics - Complex generic patterns and constraints

Developer Tools

• Diagnostics - Complete diagnostic reference (IOC001-IOC026+)
• MSBuild Configuration - Customizing diagnostic behavior
• Namespace Management - Understanding generated using statements
• Performance - Optimization for large codebases
• Architectural Limits - Understanding design boundaries and workarounds
• Troubleshooting - Common issues and solutions

Integration Guides

• ASP.NET Core - Web application patterns
• Worker Services - Background service applications
• Testing - Testing strategies with IoCTools
• Microservices - Patterns for distributed applications

🔥 Real-World Example

Here's a complete e-commerce service showcasing multiple IoCTools features:

[Service(Lifetime.Scoped)]
[ConditionalService(Environment = "Production")]
[RegisterAsAll(RegistrationMode.All, InstanceSharing.Shared)]
public partial class OrderService : IOrderService, IOrderValidator
{
    [Inject] private readonly IPaymentService _paymentService;
    [Inject] private readonly IEmailService _emailService;
    [Inject] private readonly ILogger<OrderService> _logger;
    
    [InjectConfiguration("OrderProcessing:MaxRetries")] 
    private readonly int _maxRetries;
    
    [InjectConfiguration] 
    private readonly ShippingOptions _shippingOptions;

    public async Task<OrderResult> ProcessOrderAsync(Order order)
    {
        _logger.LogInformation("Processing order {OrderId}", order.Id);
        
        // Use injected configuration
        for (int i = 0; i < _maxRetries; i++)
        {
            var paymentResult = await _paymentService.ProcessPaymentAsync(order.Payment);
            if (paymentResult.Success) break;
        }
        
        // Generated constructor handles all dependencies automatically:
        // public OrderService(IPaymentService paymentService, IEmailService emailService, 
        //     ILogger<OrderService> logger, IConfiguration configuration)
    }
}

Generated registration code:

// Only registers in Production environment
if (Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "Production")
{
    services.AddScoped<IOrderService>(provider => provider.GetRequiredService<OrderService>());
    services.AddScoped<IOrderValidator>(provider => provider.GetRequiredService<OrderService>());
    services.AddScoped<OrderService>();
}

📋 Comprehensive Sample Application

The IoCTools.Sample project provides 59 comprehensive examples demonstrating every feature:

• Basic Services (BasicUsageExamples.cs) - Field injection and lifecycle management
• Advanced Patterns (AdvancedPatternsDemo.cs) - Complex scenarios and edge cases
• Configuration Injection (ConfigurationInjectionExamples.cs) - All configuration binding patterns
• Multi-Interface Registration (MultiInterfaceExamples.cs) - Different modes and instance sharing
• Background Services (BackgroundServiceExamples.cs) - Hosted service integration
• Conditional Services (ConditionalServiceExamples.cs) - Environment and configuration-based registration
• Diagnostic Examples (DiagnosticExamples.cs) - All 26 diagnostic scenarios
• Generic Services (GenericServiceExamples.cs) - Complex generic patterns
• DependsOn Patterns (DependsOnExamples.cs) - All naming conventions and configurations

Run the sample application to see all features in action:

dotnet run --project IoCTools.Sample

🛠️ Development Status

• ✅ Core Features: Stable and feature-complete with comprehensive sample coverage
• ⚠️ Advanced Features: Stable with extensive examples, some edge cases documented as architectural limits
• 🚀 v1.0.0-alpha: Feature-complete alpha release with production-ready architecture and comprehensive validation
• 🏗️ Architectural Limits: Intentional design boundaries with documented workarounds

Sample Coverage: 59 comprehensive examples covering all features, diagnostics, and integration patterns with 100% test success rate

Note: Some advanced scenarios (complex access modifiers, extreme generic constraints) are intentional architectural limits. See Architectural Limits for details and workarounds.

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Found a bug? Open an issue Have a feature idea? Start a discussion

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Why Choose IoCTools?

For Teams: Eliminates DI configuration drift and makes service dependencies explicit and maintainable

For Performance: Zero runtime overhead - all resolution happens at compile time with build-time validation

For Developers: IntelliSense-friendly generated code that integrates seamlessly with existing .NET patterns

For Architecture: Supports sophisticated patterns like conditional services, multi-interface registration, and configuration injection while maintaining simplicity

Built with ❤️ for the .NET community