Pure DI for .NET

Supports .NET starting with .NET Framework 2.0, released 2005-10-27, and all newer versions.

Usage requirements

• .NET SDK 6.0.4 or later is installed
• Using C# 8 or later version

Key features

Pure.DI is not a framework or library, but a source code generator for creating object graphs. To make them accurate, the developer uses a set of intuitive hints from the Pure.DI API. During the compilation phase, Pure.DI determines the optimal graph structure, checks its correctness, and generates partial class code to create object graphs in the Pure DI paradigm using only basic language constructs. The resulting generated code is robust, works everywhere, throws no exceptions, does not depend on .NET library calls or .NET reflections, is efficient in terms of performance and memory consumption, and is subject to all optimizations. This code can be easily integrated into an application because it does not use unnecessary delegates, additional calls to any methods, type conversions, boxing/unboxing, etc.

• [X] DI without any IoC/DI containers, frameworks, dependencies and hence no performance impact or side effects.

  Pure.DI is actually a .NET code generator. It uses basic language constructs to create simple code as well as if you were doing it yourself: de facto it's just a bunch of nested constructor calls. This code can be viewed, analyzed at any time, and debugged.

• [X] A predictable and verified dependency graph is built and validated on the fly while writing code.

  All logic for analyzing the graph of objects, constructors and methods takes place at compile time. Pure.DI notifies the developer at compile time of missing or cyclic dependencies, cases when some dependencies are not suitable for injection, etc. The developer has no chance to get a program that will crash at runtime because of some exception related to incorrect object graph construction. All this magic happens at the same time as the code is written, so you have instant feedback between the fact that you have made changes to your code and the fact that your code is already tested and ready to use.

• [X] Does not add any dependencies to other assemblies.

  When using pure DI, no dependencies are added to assemblies because only basic language constructs and nothing more are used.

• [X] Highest performance, including compiler and JIT optimization and minimal memory consumption.

  All generated code runs as fast as your own, in pure DI style, including compile-time and run-time optimization. As mentioned above, graph analysis is done at compile time, and at runtime there are only a bunch of nested constructors, and that's it. Memory is spent only on the object graph being created.

• [X] It works everywhere.

  Since the pure DI approach does not use any dependencies or .NET reflection at runtime, it does not prevent the code from running as expected on any platform: Full .NET Framework 2.0+, .NET Core, .NET, UWP/XBOX, .NET IoT, Xamarin, Native AOT, etc.

• [X] Ease of Use.

  The Pure.DI API is very similar to the API of most IoC/DI libraries. And this was a conscious decision: the main reason is that programmers don't need to learn a new API.

• [X] Superfine customization of generic types.

  In Pure.DI it is proposed to use special marker types instead of using open generic types. This allows you to build the object graph more accurately and take full advantage of generic types.

• [X] Supports the major .NET BCL types out of the box.

  Pure.DI already supports many of BCL types like Array, IEnumerable<T>, IList<T>, IReadOnlyCollection<T>, IReadOnlyList<T>, ISet<T>, IProducerConsumerCollection<T>, ConcurrentBag<T>, Func<T>, ThreadLocal, ValueTask<T>, Task<T>, MemoryPool<T>, ArrayPool<T>, ReadOnlyMemory<T>, Memory<T>, ReadOnlySpan<T>, Span<T>, IComparer<T>, IEqualityComparer<T> and etc. without any extra effort.

• [X] Good for building libraries or frameworks where resource consumption is particularly critical.

  Its high performance, zero memory consumption/preparation overhead, and lack of dependencies make it ideal for building libraries and frameworks.

Schrödinger's cat will demonstrate how it all works

The reality is

Let's create an abstraction

interface IBox<out T>
{
    T Content { get; }
}

interface ICat
{
    State State { get; }
}

enum State { Alive, Dead }

Here's our implementation

record CardboardBox<T>(T Content): IBox<T>;

class ShroedingersCat(Lazy<State> superposition): ICat
{
    // The decoherence of the superposition
    // at the time of observation via an irreversible process
    public State State => superposition.Value;
}

[!IMPORTANT] Our abstraction and implementation knows nothing about the magic of DI or any frameworks.

Let's glue it all together

Add the Pure.DI package to your project:

Let's bind the abstractions to their implementations and set up the creation of the object graph:

DI.Setup(nameof(Composition))
    // Models a random subatomic event that may or may not occur
    .Bind().As(Singleton).To<Random>()
    // Quantum superposition of two states: Alive or Dead
    .Bind().To((Random random) => (State)random.Next(2))
    .Bind().To<ShroedingersCat>()
    // Cardboard box with any contents
    .Bind().To<CardboardBox<TT>>()
    // Composition Root
    .Root<Program>("Root");

[!NOTE] In fact, the Bind().As(Singleton).To<Random>() binding is unnecessary since Pure.DI supports many .NET BCL types out of the box, including Random. It was added just for the example of using the Singleton lifetime.

The above code specifies the generation of a partial class named Composition, this name is defined in the DI.Setup(nameof(Composition)) call. This class contains a Root property that returns a graph of objects with an object of type Program as the root. The type and name of the property is defined by calling Root<Program>("Root"). The code of the generated class looks as follows:

partial class Composition
{
    private object _lock = new object();
    private Random? _random;

    public Program Root
    {
      get
      {
        var stateFunc = new Func<State>(() => {
              if (_random == null)
                lock (_lock)
                  if (_random == null)
                    _random = new Random();

              return (State)_random.Next(2)
            });

        return new Program(
          new CardboardBox<ICat>(
            new ShroedingersCat(
              new Lazy<Sample.State>(
                stateFunc))));    
      }
    }

    public T Resolve<T>() { ... }

    public object Resolve(Type type) { ... }
}

The public Program Root { get; } property here is a Composition Root, the only place in the application where the composition of the object graph for the application takes place. Each instance is created by only basic language constructs, which compiles with all optimizations with minimal impact on performance and memory consumption. In general, applications may have multiple composition roots and thus such properties. Each composition root must have its own unique name, which is defined when the Root<T>(string name) method is called, as shown in the above code.

Time to open boxes!

class Program(IBox<ICat> box)
{
  // Composition Root, a single place in an application
  // where the composition of the object graphs
  // for an application take place
  static void Main() => new Composition().Root.Run();

  private void Run() => Console.WriteLine(box);
}

[!TIP] Pure.DI creates efficient code in a pure DI paradigm, using only basic language constructs as if you were writing code by hand. This allows you to take full advantage of Dependency Injection everywhere and always, without any compromise!

The full analog of this application with top-level statements can be found here.

Examples

Basics

• Auto-bindings
• Injections of abstractions
• Composition roots
• Resolve methods
• Simplified binding
• Factory
• Simplified factory
• Class arguments
• Root arguments
• Tags
• Field injection
• Method injection
• Property injection
• Default values
• Required properties or fields
• Root binding
• Async Root

  Lifetimes

• Transient
• Singleton
• PerResolve
• PerBlock
• Scope
• Auto scoped
• Default lifetime
• Default lifetime for a type
• Default lifetime for a type and a tag
• Disposable singleton
• Async disposable singleton
• Async disposable scope

  Base Class Library

• Func
• Enumerable
• Enumerable generics
• Array
• Lazy
• Task
• ValueTask
• Manually started tasks
• Span and ReadOnlySpan
• Tuple
• Weak Reference
• Async Enumerable
• Service collection
• Func with arguments
• Func with tag
• Keyed service provider
• Service provider
• Service provider with scope
• Overriding the BCL binding

  Generics

• Generics
• Generic composition roots
• Complex generics
• Generic composition roots with constraints
• Generic async composition roots with constraints
• Custom generic argument

  Attributes

• Constructor ordinal attribute
• Member ordinal attribute
• Tag attribute
• Type attribute
• Inject attribute
• Custom attributes
• Custom universal attribute
• Custom generic argument attribute
• Bind attribute
• Bind attribute with lifetime and tag
• Bind attribute for a generic type

  Interception

• Decorator
• Interception
• Advanced interception

  Hints

• Resolve hint
• ThreadSafe hint
• OnDependencyInjection hint
• OnCannotResolve hint
• OnNewInstance hint
• ToString hint
• Check for a root

  Advanced

• Composition root kinds
• Tag Type
• Tag Unique
• Tag on injection site
• Tag on a constructor argument
• Tag on a member
• Tag on a method argument
• Tag on injection site with wildcards
• Dependent compositions
• Accumulators
• Global compositions
• Partial class
• A few partial classes
• Tracking disposable instances per a composition root
• Tracking disposable instances in delegates
• Tracking async disposable instances per a composition root
• Tracking async disposable instances in delegates
• Exposed roots
• Exposed roots with tags
• Exposed roots via arg
• Exposed roots via root arg
• Exposed generic roots
• Exposed generic roots with args

  Applications

• Console
  • Schrödinger's cat
  • Top level statements
  • Native AOT
• UI
  • MAUI
  • WPF
  • Avalonia
  • Win Forms Net Core
  • Win Forms
• Web
  • Web
  • Minimal Web API
  • Web API
  • gRPC service
  • Blazor Server
  • Blazor WebAssembly
  • https://devteam.github.io/Pure.DI/
• Git repo with examples
  • Schrödinger's cat
  • How to use Pure.DI to create and test libraries

    Generated Code

Each generated class, hereafter called a composition, must be customized. Setup starts with a call to the Setup(string compositionTypeName) method:

DI.Setup("Composition")
    .Bind<IDependency>().To<Dependency>()
    .Bind<IService>().To<Service>()
    .Root<IService>("Root");

The compositionTypeName parameter can be omitted

• if the setup is performed inside a partial class, then the composition will be created for this partial class
• for the case of a class with composition kind CompositionKind.Global, see this example

NuGet packages

Pure.DI		DI Source code generator
Pure.DI.Abstractions		Abstractions for Pure.DI
Pure.DI.Templates		Template Package you can call from the shell/command line.
Pure.DI.MS		Tools for working with Microsoft DI

Project template

Install the DI template Pure.DI.Templates

dotnet new install Pure.DI.Templates

Create a "Sample" console application from the template di

dotnet new di -o ./Sample

And run it

dotnet run --project Sample

For more information about the template, please see this page.

Troubleshooting

Contribution

Thank you for your interest in contributing to the Pure.DI project! First of all, if you are going to make a big change or feature, please open a problem first. That way, we can coordinate and understand if the change you're going to work on fits with current priorities and if we can commit to reviewing and merging it within a reasonable timeframe. We don't want you to waste a lot of your valuable time on something that may not align with what we want for Pure.DI.

The entire build logic is a regular console .NET application. You can use the build.cmd and build.sh files with the appropriate command in the parameters to perform all basic actions on the project, e.g:

For example:

./build.sh pack
./build.cmd benchmarks

If you are using the Rider IDE, it already has a set of configurations to run these commands.

[!TIP] This project uses C# interactive build automation system for .NET

This tool helps to make .NET builds more efficient.

Contribution Prerequisites:

Installed .NET SDK 8.0

Additional resources

RU DotNext video

<img src="http://img.youtube.com/vi/nrp9SH-gLqg/0.jpg" alt="DotNext Pure.DI" width="640" border="10"/>

C# interactive build automation system for .NET

Examples of how to set up a composition

• Pure.DI
• C# interactive
• Immutype
• MSBuild logger

Articles

• RU New in Pure.DI
• RU Pure.DI v2.1
• RU Pure.DI next step
• RU Pure.DI for .NET

Benchmarks

BenchmarkDotNet v0.13.12, Ubuntu 20.04.6 LTS (Focal Fossa)
Intel Xeon Platinum 8259CL CPU 2.50GHz, 1 CPU, 2 logical cores and 1 physical core
.NET SDK 8.0.201
  [Host]     : .NET 8.0.2 (8.0.224.6711), X64 RyuJIT AVX-512F+CD+BW+DQ+VL
  DefaultJob : .NET 8.0.2 (8.0.224.6711), X64 RyuJIT AVX-512F+CD+BW+DQ+VL