Add IServiceCollectionValidator for optional DI validation at BuildServiceProvider

[iatsuta]

Background and motivation

The default .NET DI container (Microsoft.Extensions.DependencyInjection) provides minimal validation during BuildServiceProvider, such as ValidateScopes and ValidateOnBuild. However, it lacks a standardized, extensible mechanism for developers to validate service registrations at build time.

Currently, developers must implement custom validation and invoke it manually after configuring services. This approach is error-prone and easy to forget, leading to runtime errors from misconfigured dependencies, such as:

Duplicate singleton services used in constructors expecting a single instance.

Missing required services for dependent constructors.

Other potential DI misconfigurations.

By introducing a standard IServiceCollectionValidator interface, the container could optionally:

Aggregate all validation errors during BuildServiceProvider.

Support multiple custom validators.

Maintain full backward compatibility: projects that do not use validators remain unaffected.

This would provide early feedback on misconfigurations, reduce runtime errors, and align with the existing philosophy of optional validation in the DI container.

API Proposal

namespace Microsoft.Extensions.DependencyInjection;

public interface IServiceCollectionValidator
{
    ValidationResult Validate(IServiceCollection services, object? options);
}

public static class ServiceCollectionValidationExtensions
{
    public static IServiceCollection AddValidator<TValidator>(this IServiceCollection services)
        where TValidator : IServiceCollectionValidator, new();

    public static IServiceCollection AddValidator(this IServiceCollection services, IServiceCollectionValidator validator);
}

public record ValidationResult(IReadOnlyList<string> Errors)
{
    bool IsSuccess { get; }
    static ValidationResult Success { get; }
    static ValidationResult operator +(ValidationResult left, ValidationResult right);
}

API Usage

var services = new ServiceCollection();

// Register services
services.AddSingleton<IService, ServiceImpl>();
services.AddSingleton<Consumer>();

// Register validators
services.AddValidator<DuplicateServiceUsageValidator>();

// Build the provider — validators run automatically
var provider = services.BuildServiceProvider();

// If validation fails, BuildServiceProvider throws with aggregated errors

Alternative Designs

using Xunit;
using FluentAssertions;
using Microsoft.Extensions.DependencyInjection;
using System;

namespace CommonFramework.DependencyInjection.Tests
{
    public interface IService { }
    public class ServiceImpl : IService { }

    public class Consumer
    {
        public Consumer(IService service) { }
    }

    public class DuplicateServiceUsageValidatorTests
    {
        [Fact]
        public void BuildServiceProvider_ShouldThrow_WhenDuplicateSingletonUsedInConstructor()
        {
            // Arrange
            var services = new ServiceCollection();

            // Duplicate singleton
            services.AddSingleton<IService, ServiceImpl>();
            services.AddSingleton<IService, ServiceImpl>();

            // Consumer depends on single IService
            services.AddSingleton<Consumer>();

            // Register validator
            services.AddValidator<DuplicateServiceUsageValidator>();

            // Act
            Action act = () => 
            {
                // Instead of manually calling Validate, we simulate 
                // a "BuildServiceProvider" step that internally calls Validate
                services.Validate();
                var provider = services.BuildServiceProvider();
            };

            // Assert
            act.Should().Throw<InvalidOperationException>()
            .Where(ex => ex.Message.Contains("has been registered many times"));
        }
    }
}

Currently, developers must manually implement and invoke custom validators after configuring services, which is error-prone and scattered. A reference implementation with unit tests is available here: DuplicateServiceUsageValidatorTests

Risks

Backward compatibility: Fully preserved. Projects that do not register any IServiceCollectionValidator continue to work exactly as before.

Breaking changes: None. No existing APIs are modified.

Performance: Minimal impact. Validators are only invoked if explicitly registered, before BuildServiceProvider.

Error reporting: Any exceptions are limited to scenarios where custom validators detect misconfigurations. They do not affect projects that do not use validators.

This ensures that the proposal introduces optional, safe, and isolated functionality without breaking existing applications.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-extensions-dependencyinjection
See info in area-owners.md if you want to be subscribed.

[rosebyte]

Triage: it feels useful, we will consider implementing it in the future.

[rosebyte]

@iatsuta, do you think we can change the IServiceCollectionValidator interface? My concern is that exposing IServiceCollection could be abused to register services after the fact, making any earlier validators inconclusive. Besides, do we need the object?options parameter?

public interface IServiceCollectionValidator
{
    ValidationResult Validate(IReadOnlyList<ServiceDescriptor> services);
}

[iatsuta]

@rosebyte

Yes, the collection should ideally be locked against modifications; IServiceCollection was used only for demonstration purposes.

Having options, even in an untyped form, would still be useful as an alternative configuration source for validators. Since the container implementation may vary, using an untyped object here seemed more appropriate.

Currently, the only way to pass configuration is through the validator constructor:

public class DuplicateServiceUsageValidator(Type[] exceptServices) : IServiceCollectionValidator
{
    public ValidationResult Validate(IServiceCollection services, object? _)
    {
        // ... using exceptServices ...
    }
}

However, in practice the validator registration and its configuration may happen in different parts of the application.

An alternative approach would be to configure it through ServiceProviderOptions:

public interface IDuplicateServiceUsageValidatorOptions
{
    ImmutableArray<Type> ExceptServices { get; }
}

public class DuplicateServiceUsageValidator() : IServiceCollectionValidator
{
    /// <inheritdoc />
    public ValidationResult Validate(IServiceCollection services, object? options)
    {
        var typedOptions = options as IDuplicateServiceUsageValidatorOptions;
    }
}

public class MyServiceProviderOptions : ServiceProviderOptions, IDuplicateServiceUsageValidatorOptions
{
    public ImmutableArray<Type> ExceptServices { get; set; }
}

Usage example:

var sp = new ServiceCollection()
    .AddValidator<DuplicateServiceUsageValidator>()
    .BuildServiceProvider(new MyServiceProviderOptions
    {
        ValidateScopes = true,
        ValidateOnBuild = true,
        ExceptServices = [typeof(ILoggerFactory)]
    });

It might also make sense to change the ServiceProviderOptions signature to something like this:

public class ServiceProviderOptions
{
    public bool ValidateScopes { get; set; }

    public bool ValidateOnBuild { get; set; }

    public ImmutableDictionary<object, object> Parameters { get; set; } = [];
}

But that would likely be a separate discussion.