Install the DI template Pure.DI.Templates

dotnet new -i Pure.DI.Templates

Create a "Sample" console application from the template di

dotnet new di -o ./Sample

And run it

dotnet run --project Sample

Please see this page for more details about the template.

The first parameter is used to specify the name of the composition class. All setups with the same name will be combined to create one composition class. In addition, this name may contain a namespace, for example for Sample.Composition the composition class is generated:

namespace Sample
{
    partial class Composition
    {
        ...
    }
}

The second optional parameter can have several values to determine the kind of composition.

This is the default value. If this value is specified, a composition class will be created.

If this value is specified, the class will not be generated, but this setup can be used for others as a base. For example:

DI.Setup("BaseComposition", CompositionKind.Internal)
    .Bind<IDependency>().To<Dependency>();

DI.Setup("Composition").DependsOn("BaseComposition")
    .Bind<IService>().To<Service>();    

When the composition CompositionKind.Public flag is set in the composition setup, it can also be the base composition for others like in the example above.

If this value is specified, no composition class will be created, but this setup is the base for all setups in the current project, and DependsOn(...) is not required.

Everything is quite banal, this constructor simply initializes the internal state.

It replaces the default constructor and is only created if at least one argument is provided. For example:

DI.Setup("Composition")
    .Arg<string>("name")
    .Arg<int>("id")
    ...

In this case, the argument constructor looks like this:

public Composition(string name, int id) { ... }

and default constructor is missing.

This constructor is always available and is used to create a child composition based on the parent composition:

var parentComposition = new Composition();
var childComposition = new Composition(parentComposition); 

The child composition inherits the state of the parent composition in the form of arguments and singleton objects. States are copied, and compositions are completely independent, except when calling the Dispose() method on the parent container before disposing of the child container, because the child container can use singleton objects created before it was created.

To be able to quickly and conveniently create an object graph, a set of properties is generated. These properties are called compositions roots here. The type of the property is the type of a root object created by the composition. Accordingly, each access to the property leads to the creation of a composition with the root element of this type.

To be able to use a specific composition root, that root must be explicitly defined by the Root method with a specific name and type:

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

In this case, the property for type IService will be named MyService and will be available for direct use. The result of its use will be the creation of a composition of objects with a root of type IService:

public IService MyService
{
    get
    { 
        ...
        return new Service(...);
    }
}

This is recommended way to create a composition root. A composition class can contain any number of roots.

When the root name is empty, a private composition root is created. This root is used in these Resolve methods in the same way as public roots. For example:

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

private IService Root1ABB3D0
{
    get { ... }
}

These properties have a random name and a private accessor and cannot be used directly from code. Don't try to use them. Private composition roots can be resolved by the Resolve methods.

By default a set of four Resolve methods are generated:

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

public T Resolve<T>(object? tag) { ... }

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

public object Resolve(Type type, object? tag) { ... }

These methods can resolve public composition roots as well as private roots and are useful when using the Service Locator approach when the code resolves composition roots in place:

var composition = new Composition();

composition.Resolve<IService>();

This is not recommended way to create composition roots. To control the generation of these methods, see the Resolve hint.

Provides a mechanism for releasing unmanaged resources. This method is only generated if the composition contains at least one singleton object that implements the IDisposable interface. To dispose of all created singleton objects, call the composition Dispose() method:

using(var composition = new Composition())
{
    ...
}

Setup hints are comments before method Setup in the form hint = value that are used to fine-tune code generation. For example:

// Resolve = Off
// ThreadSafe = Off
// ToString = On
DI.Setup("Composition")
    ...

Determine whether to generate Resolve methods. By default a set of four Resolve methods are generated. Set this hint to Off to disable the generation of resolve methods. This will reduce class composition generation time and no private composition roots will be generated in this case. The composition will be tiny and will only have public roots. When the Resolve hint is disabled, only the public root properties are available, so be sure to define them explicitly with the Root<T>(...) method.

Determine whether to generate partial OnInstanceCreation method. This partial method is not generated by default. This can be useful, for example, for logging:

internal partial class Composition
{
    partial void OnInstanceCreation<T>(ref T value, object? tag, object lifetime)            
    {
        Console.WriteLine($"'{typeof(T)}'('{tag}') created.");            
    }
}

You can also replace the created instance of type T, where T is actually type of created instance. To minimize the performance penalty when calling OnInstanceCreation, use the three related hints below.

It is a regular expression to filter by the instance type name. This hint is useful when OnInstanceCreation is in the On state and you want to limit the set of types for which the method OnInstanceCreation will be called.

It is a regular expression to filter by the tag. This hint is useful also when OnInstanceCreation is in the On state and you want to limit the set of tag for which the method OnInstanceCreation will be called.

It is a regular expression to filter by the lifetime. This hint is useful also when OnInstanceCreation is in the On state and you want to limit the set of lifetime for which the method OnInstanceCreation will be called.

Determine whether to generate partial OnDependencyInjection method to control of dependency injection. This partial method is not generated by default. It cannot have an empty body due to the return value. It must be overridden when generated. This can be useful, for example, for interception.

// OnDependencyInjection = On
// OnDependencyInjectionContractTypeNameRegularExpression = ICalculator[\d]{1}
// OnDependencyInjectionTagRegularExpression = Abc
DI.Setup("Composition")
    ...

To minimize the performance penalty when calling OnDependencyInjection, use the three related hints below.

It is a regular expression to filter by the instance type name. This hint is useful when OnDependencyInjection is in the On state and you want to limit the set of types for which the method OnDependencyInjection will be called.

It is a regular expression to filter by the resolving type name. This hint is useful also when OnDependencyInjection is in the On state and you want to limit the set of resolving types for which the method OnDependencyInjection will be called.

It is a regular expression to filter by the tag. This hint is useful also when OnDependencyInjection is in the On state and you want to limit the set of tag for which the method OnDependencyInjection will be called.

It is a regular expression to filter by the lifetime. This hint is useful also when OnDependencyInjection is in the On state and you want to limit the set of lifetime for which the method OnDependencyInjection will be called.

Determine whether to generate a partial OnCannotResolve<T>(...) method to handle a scenario where an instance which cannot be resolved. This partial method is not generated by default. It cannot have an empty body due to the return value. It must be overridden on creation.

// OnCannotResolve = On
// OnCannotResolveContractTypeNameRegularExpression = string|DateTime
// OnDependencyInjectionTagRegularExpression = null
DI.Setup("Composition")
    ...

To avoid missing bindings by mistake, use the two related hints below.

It is a regular expression to filter by the resolving type name. This hint is useful also when OnCannotResolve is in the On state and you want to limit the set of resolving types for which the method OnCannotResolve will be called.

It is a regular expression to filter by the tag. This hint is useful also when OnCannotResolve is in the On state and you want to limit the set of tag for which the method OnCannotResolve will be called.

It is a regular expression to filter by the lifetime. This hint is useful also when OnCannotResolve is in the On state and you want to limit the set of lifetime for which the method OnCannotResolve will be called.

Determine if the ToString() method should be generated. This method provides a text-based class diagram in the format mermaid. To see this diagram, just call the ToString method and copy the text to this site.

// ToString = On
DI.Setup("Composition")
    .Bind<IService>().To<Service>()
    .Root<IService>("MyService");
    
var composition = new Composition();
string classDiagram = composition.ToString(); 

This hint determines whether object composition will be created in a thread-safe manner. This hint is On by default. It is good practice not to use threads when creating an object graph, in which case this hint can be turned off, which will lead to a slight increase in performance.

// ThreadSafe = Off
DI.Setup("Composition")
    .Bind<IService>().To<Service>()
    .Root<IService>("MyService");

Overrides modifiers of the method public T Resolve<T>().

Overrides name of the method public T Resolve<T>().

Overrides modifiers of the method public T Resolve<T>(object? tag).

Overrides name of the method public T Resolve<T>(object? tag).

Overrides modifiers of the method public object Resolve(Type type).

Overrides name of the method public object Resolve(Type type).

Overrides modifiers of the method public object Resolve(Type type, object? tag).

Overrides name of the method public object Resolve(Type type, object? tag).

Overrides modifiers of the method public void Dispose().

You can set build properties to save the generated file and control where the generated files are stored. In a project file, add the element to a , and set its value to true. Build your project again. Now, the generated files are created under obj/Debug/netX.X/generated/Pure.DI/Pure.DI.SourceGenerator. The components of the path map to the build configuration, target framework, source generator project name, and fully qualified type name of the generator. You can choose a more convenient output folder by adding the element to the application's project file. For example:

<Project Sdk="Microsoft.NET.Sdk">
    
    <PropertyGroup>
        <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
        <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)Generated</CompilerGeneratedFilesOutputPath>
    </PropertyGroup>
    
</Project>

You can set build properties to save the log file. In the project file, add a element to the and set the path to the log directory, and add the related element <CompilerVisibleProperty Include="PureDILogFile" /> to the to make this property visible in the source generator. To change the log level, specify the same with the PureDISeverity property, as in the example below:

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <PureDILogFile>.logs\Pure.DI.log</PureDILogFile>
        <PureDISeverity>Info</PureDISeverity>
    </PropertyGroup>

    <ItemGroup>
        <CompilerVisibleProperty Include="PureDILogFile" />
        <CompilerVisibleProperty Include="PureDISeverity" />
    </ItemGroup>

</Project>

The PureDISeverity property has several options available: