TinyNeedle 1.0.0

💉 TinyNeedle

A super minimalistic but very capable Auto-DI framework for DotNet applications.

Usage

To create a container, create a new instance of a ServiceContainer class. This class lets you register new types and resolve type instances on the fly.

To register a new type, preferably call container.Register<MyService>() with an optional lifetime and constructor parameters.

To resolve a type manually, call container.Resolve<MyService>() or container.ResolveRequired<MyService>(). This method simply searches the container for registered types and returns a matching instance.

var root = new ServiceContainer()
    .Register<NetworkService>(Lifetime.Singleton)
    .Register<DatabaseService>(Lifetime.Scoped, new object[] { "my_db;user;password;" });

var network = root.Resolve<NetworkService>();
network.Initialize(); // => Calls Db.Connect();

To inject other services into a class, create a property (readonly or with setter) and give it a [Inject] attribute.

public class NetworkService
{
    [Inject] private DatabaseService Db { get; }
    
    public void Initialize() => Db.Connect();
}

It's also possible to automatically register types by adding the [Dependency(Lifetime = ...)] attribute to a class definition and calling container.AutoRegister()

Child containers are also supported. Create one by calling container.Scope() This returns a new ServiceContainer instance. When resolving types, the lifetime of a given type is crucial for where to search for available instances.

Lifetime

Currently, three different lifetimes are supported.

1. Singleton: Types with this lifetime exist only once per container group.

   Container Parent registers a singleton, and scoped container Child tries to resolve this type. Child does not find a matching instance, but instead of creating a new one, the container recursively searches the type up the container tree. Parent has that type registered, but creates a new instance and adds it to its pool of instances because it does not yet have an available instance to return.

2. Scoped: This lifetime is similar to a singleton, but is limited to scoped containers.

   Container Parent registers a scoped type and has an available instance ready. If Child resolves this type, it's the same as with singletons. However, if Parent does not have an instance of the required type, Child will instantiate that type and add the instance to its own pool of instances. This way, scoped instances will be isolated from each concurrent container.

3. Transient: Transient types are always instantiated as soon as they're resolved (with one exception, see Circular Dependencies)

   A service container registers a transient type and resolves it. The resolution will not store the new instance in a list, but rather immediately returns it. If it's requested again, a new instance would be created.

Circular Dependencies

Different from other Auto-DI frameworks, TinyNeedle is capable enough to understand circular dependencies and handles them properly.

For example, if a container has a service registered, but that service has an injected reference to itself, TinyNeedle understands that the requested service was already instantiated before (one recursive call earlier) and uses this instance instead. This way, the resolution of the service will not crash, but rather create a successful circular reference. Behind the scenes, it would basically be a pointer that simply points to itself.

Fluent design by default

Most methods of the ServiceContainer return the container itself that allows for convenient method chaining. This makes especially registering new types manually a breeze. But keep it mind that there's also support for auto registering types!

var root = new ServiceContainer()
    .Register<NetworkService>()
    .Register<DatabaseService>()
    .Register<EmailService>()
    .Register<AuthenticationService>()
    .Register<HttpService>()...;