SharpServiceCollection 1.0.0

SharpServiceCollection

SharpServiceCollection is a lightweight C# package that provides a declarative, comipile-time and AOT-friendly way to work with IServiceCollection.

Table of contents

• Installation
• How it works
• Your first registration
  • Register a class by itself
  • Register by interface
  • Register an explicit service type
• Registration options
  • Lifetimes
  • Registration target
  • Keys, enumerable services, and ordering
• Choose how services are discovered
  • Source-generated registration
  • Reflection-based registration
• Register services from multiple projects
  • Create a module registration
  • Enable the host project
  • Use a registration context
• Opt out of source generation
• Diagnostics
• Package contents

Installation

Install one package. You do not need to install separate packages for the runtime library, dependency types, or source generator:

dotnet add package SharpServiceCollection

You can also install it from NuGet.

The package contains:

• The runtime library and public attributes
• The dependency types used by the attributes
• The Roslyn source generator under analyzers/dotnet/cs

The source generator runs automatically when you build a project that references the package.

How it works

The basic workflow is:

1. Install SharpServiceCollection.
2. Add an InjectableDependency attribute to each service implementation.
3. Call the generated AddAttributedServices() extension method.
4. Resolve the service through the normal .NET dependency injection APIs.

For example:

using Microsoft.Extensions.DependencyInjection;
using SharpServiceCollection;
using SharpServiceCollection.Attributes;
using SharpServiceCollection.Enums;
using SharpServiceCollection.Generated;

public interface IEmailSender
{
    Task SendAsync(string address, string message);
}

[InjectableDependency(InstanceLifetime.Scoped, ResolveBy.MatchingInterface)]
public sealed class EmailSender : IEmailSender
{
    public Task SendAsync(string address, string message)
    {
        Console.WriteLine($"Sending to {address}: {message}");
        return Task.CompletedTask;
    }
}

var builder = WebApplication.CreateBuilder(args);

// The source generator creates this method for the current assembly.
builder.Services.AddAttributedServices();

var app = builder.Build();
app.MapGet("/email", async (IEmailSender sender) =>
{
    await sender.SendAsync("user@example.com", "Welcome!");
    return Results.Ok();
});

app.Run();

EmailSender is registered as IEmailSender, and its lifetime is scoped. The generated code uses the normal Microsoft.Extensions.DependencyInjection registration APIs; there is no runtime type scanning for source-generated registration.

Your first registration

Register a class by itself

Use ResolveBy.Self when consumers should resolve the concrete class:

[InjectableDependency(InstanceLifetime.Transient, ResolveBy.Self)]
public sealed class TokenGenerator
{
    public string Create() => Guid.NewGuid().ToString("N");
}

This is equivalent to:

services.TryAddTransient<TokenGenerator>();

Register by interface

Use ResolveBy.MatchingInterface when the class follows the I{ClassName} naming convention:

public interface IOrderService
{
    Task PlaceAsync(int orderId);
}

[InjectableDependency(InstanceLifetime.Scoped, ResolveBy.MatchingInterface)]
public sealed class OrderService : IOrderService
{
    public Task PlaceAsync(int orderId) => Task.CompletedTask;
}

This registers:

services.TryAddScoped<IOrderService, OrderService>();

The class must implement the matching interface. For example, OrderService must implement IOrderService.

Register an explicit service type

Use the generic attribute when the service type does not follow a naming convention:

public interface IMessageHandler
{
    Task HandleAsync(string message);
}

[InjectableDependency<IMessageHandler>(InstanceLifetime.Singleton)]
public sealed class WelcomeMessageHandler : IMessageHandler
{
    public Task HandleAsync(string message) => Task.CompletedTask;
}

This registers WelcomeMessageHandler as IMessageHandler.

Registration options

Lifetimes

InstanceLifetime supports the standard dependency injection lifetimes:

Example:

[InjectableDependency(InstanceLifetime.Singleton, ResolveBy.Self)]
public sealed class ApplicationClock
{
    public DateTimeOffset Now => DateTimeOffset.UtcNow;
}

Registration target

ResolveBy determines which service type is registered:

For example:

[InjectableDependency(
    InstanceLifetime.Scoped,
    ResolveBy.ImplementedInterface)]
public sealed class PaymentService : ICardPayment, IRefunds
{
    // Registered for both ICardPayment and IRefunds.
}

Keys, enumerable services, and ordering

All registration attributes support these options:

Keyed services

[InjectableDependency<IMessageHandler>(
    InstanceLifetime.Transient,
    Key = "welcome")]
public sealed class WelcomeMessageHandler : IMessageHandler
{
    public Task HandleAsync(string message) => Task.CompletedTask;
}

The service can then be resolved using the standard keyed-service APIs:

var handler = serviceProvider.GetRequiredKeyedService<IMessageHandler>("welcome");

Multiple implementations

Set Enumerable = true when you want all matching implementations available through IEnumerable<T>:

public interface IValidator<T>
{
    bool IsValid(T value);
}

public sealed record Order(int Id);

[InjectableDependency<IValidator<Order>>(
    InstanceLifetime.Singleton,
    Enumerable = true)]
public sealed class PaymentValidator : IValidator<Order>
{
}

[InjectableDependency<IValidator<Order>>(
    InstanceLifetime.Singleton,
    Enumerable = true)]
public sealed class AddressValidator : IValidator<Order>
{
}

Inject them together:

public sealed class OrderService(IEnumerable<IValidator<Order>> validators)
{
    public bool IsValid(Order order) => validators.All(v => v.IsValid(order));
}

Enumerable = true requires TryAdd = true.

Duplicate registrations and Order

Registrations are processed by Order ascending, followed by class name ascending.

• With TryAdd = true, the first matching registration wins.
• With TryAdd = false, the regular Add* method is used, so later registrations can replace the default service resolution.

[InjectableDependency<IWorker>(InstanceLifetime.Scoped, Order = 1)]
public sealed class PrimaryWorker : IWorker
{
}

[InjectableDependency<IWorker>(InstanceLifetime.Scoped, Order = 2)]
public sealed class BackupWorker : IWorker
{
}

Choose how services are discovered

Source-generated registration

Source generation is the recommended option when the assemblies are known at build time. It is fast, avoids runtime assembly scanning, and is a good fit for trimming and AOT scenarios.

Add the attribute to your services, then call:

using SharpServiceCollection.Generated;

services.AddAttributedServices();

The generated method is internal, so it is intended for use inside the same assembly that contains the attributed services.

When a host needs to register services from another assembly, the generator also creates a public method based on that assembly name:

// For an assembly named My.Module.Application:
services.AddAttributedServicesFrom_MyModuleApplication();

The complete method name follows this pattern:

AddAttributedServicesFrom_{SanitizedAssemblyName}

For example:

Assembly name:  My.Module.Application
Generated call: services.AddAttributedServicesFrom_MyModuleApplication();

The generator uses the consuming project's AssemblyName, removes dots and other non-alphanumeric characters, and adds the AddAttributedServicesFrom_ prefix. For example, the test project assembly SharpServiceCollection.Tests generates:

services.AddAttributedServicesFrom_SharpServiceCollectionTests();

The generated method is public, so a host project can call the method generated in a referenced module assembly.

Reflection-based registration

Use reflection when an assembly is only known at runtime, when you are loading plugins, or while migrating an existing application to source generation.

using SharpServiceCollection.Extensions;

services.AddServicesFromCurrentAssembly();
services.AddServicesFromAssembly(pluginAssembly);
services.AddServicesFromAssemblyContaining<PluginMarker>();
services.AddServicesFromAssemblyContaining(typeof(PluginMarker));

Reflection scans the selected assembly at runtime. It is more flexible than source generation, but source generation is usually preferable when the set of assemblies is known during the build.

Register services from multiple projects

In a modular solution, each project can own its service registrations. A host project can then discover and execute those registrations through generated code.

This is useful when your solution looks like this:

MyApp.Api                 # host project
MyApp.Orders              # feature module
MyApp.Payments            # feature module

Create a module registration

Mark a sealed class with [ServiceRegistrationItem] and implement IServiceRegistration:

using Microsoft.Extensions.DependencyInjection;
using SharpServiceCollection.Attributes;
using SharpServiceCollection.Generated;
using SharpServiceCollection.Interfaces;

[ServiceRegistrationItem]
public sealed class OrdersRegistration : IServiceRegistration
{
    public Task RegisterAsync(IServiceCollection services)
    {
        services.AddAttributedServices();
        services.AddSingleton<OrderNumberGenerator>();
        return Task.CompletedTask;
    }
}

The generator discovers classes that:

• Have the [ServiceRegistrationItem] attribute
• Are sealed
• Implement IServiceRegistration or IServiceRegistration<TContext>
• Provide the matching RegisterAsync method

The class can have any name. It does not need to be named ServiceRegistration.

Order controls execution order. Lower order values run first. Registrations with the same order are sorted by implementation type name.

Enable the host project

Set ServiceRegistrationRoot in the host project's .csproj file:

<PropertyGroup>
  <ServiceRegistrationRoot>true</ServiceRegistrationRoot>
</PropertyGroup>

The host must reference the module projects or packages. Then execute the generated registrations during startup:

using SharpServiceCollection.Generated;

var builder = WebApplication.CreateBuilder(args);

await builder.Services.ExecuteServiceRegistrationItemsAsync();

var app = builder.Build();
app.Run();

The source generator creates a small public aggregator in every module. The root project finds those aggregators through its project or package references and combines them into ExecuteServiceRegistrationItemsAsync.

Use a registration context

Implement IServiceRegistration<TContext> when a module needs configuration or environment information:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using SharpServiceCollection.Attributes;
using SharpServiceCollection.Interfaces;

public sealed record AppContext(
    IConfiguration Configuration,
    IHostEnvironment Environment);

[ServiceRegistrationItem(Order = 20)]
public sealed class PaymentsRegistration : IServiceRegistration<AppContext>
{
    public Task RegisterAsync(
        IServiceCollection services,
        AppContext context)
    {
        services.AddSingleton(context.Configuration);
        return Task.CompletedTask;
    }
}

Pass the matching context from the host:

var context = new AppContext(
    builder.Configuration,
    builder.Environment);

await builder.Services.ExecuteServiceRegistrationItemsAsync(context);

Opt out of source generation

The package contains two independent source generators. You can disable either one, or both, in a consuming project's .csproj file.

Disable attributed DI generation

Set DisableInjectableDependencyGenerator to true when you want to use the reflection-based registration APIs instead of generated AddAttributedServices() methods:

<PropertyGroup>
  <DisableInjectableDependencyGenerator>true</DisableInjectableDependencyGenerator>
</PropertyGroup>

This disables generated attributed-service registration only. Reflection APIs such as AddServicesFromAssembly(...) remain available.

Disable service-registration orchestration

Set DisableServiceRegistrationGenerator to true when you do not use [ServiceRegistrationItem] and IServiceRegistration:

<PropertyGroup>
  <DisableServiceRegistrationGenerator>true</DisableServiceRegistrationGenerator>
</PropertyGroup>

This disables generated service-registration aggregators and root methods such as ExecuteServiceRegistrationItemsAsync(...).

To disable both generators:

<PropertyGroup>
  <DisableInjectableDependencyGenerator>true</DisableInjectableDependencyGenerator>
  <DisableServiceRegistrationGenerator>true</DisableServiceRegistrationGenerator>
</PropertyGroup>

Diagnostics

The source generator reports clear diagnostics when an attribute or registration class is invalid:

Fix the reported source code and rebuild. The generator will run again automatically.

Package contents

SharpServiceCollection is distributed as a single NuGet package:

SharpServiceCollection.nupkg
├── lib/netstandard2.0/
│   ├── SharpServiceCollection.dll
│   └── SharpServiceCollection.Dependencies.dll
└── analyzers/dotnet/cs/
    ├── SharpServiceCollection.Generators.dll
    └── SharpServiceCollection.Dependencies.dll

The dependency assembly is included in the package so consumers can use the public attribute, enum, and interface types without installing another package. The generator copy is placed in the analyzer folder so it runs automatically during builds.