24
ThunderboltIoc: .Net Dependency Injection without Reflection!
One of the very first IoC frameworks for .Net that has no reflection. An IoC that casts its services before thunder casts its bolts 😄
The goal is to create a code-generation based IoC container for .Net. Almost all containers today rely on reflection to provide a functioning IoC, which is a costly operation. Regardless of the valued attempts to improve the performance of these containers over the years, these containers would not match the performance of a code-generation based IoC, if that could be achieved. It is quite irritating to witness the cost we pay for trying to clean our code by -among other things- using a reflection-based IoC framework and being able to do nothing about it. The idea is to let the user (the developer) write their code as they please, and let the IoC take care of code generation during compilation to provide a working and performant solution in the target assembly.
I have finally managed to find the time to start working on the solution. Fortunately for me and for the community, I read about source generators in .Net before starting. Having watched the power of source-generators combined with the power of Roslyn, I decided to pick that path over other approaches such as T4 templates and CodeDom for code generation, and I'm glad I made that choice. Mine might not be the first solution to follow this approach, but I like to think of it as the most powerful and flexible one to-date.
Below is a documentation as well as features overview and a quick-start guide to walk you through the framework. If you like my work and are looking forward to supporting me and helping me to continue to improve it, you may do that by:
I'm also open to your suggestions. Feel free to contact me on twitter @aly_elhaddad
p.s. the phrase "if that could be achieved" did exist in my original pretext in March 2021. Even though I managed to make this true today, I decided to keep it here as further motivation for the reader.
ThunderboltIoc's installation is a simple as installing the nuget to the target assemblies. No further configuration is needed. For the sake of registering your services, however, you're going to need to implement (i.e create a class that inherits) ThunderboltRegistration as a partial class in each project where you may want to register services.
You may find the package at Nuget.org:
using dotnet:
dotnet add package ThunderboltIocor using Nuget Package Manager Console:
Install-Package ThunderboltIocThis step is not needed if you don't have any types/services that you would like to register in this assembly. However, if you do (which is likely), you should create a partial class that implements the ThunderboltRegistration abstract class. More on the registration can be found in the relevant section of this document.
After installation, here's a minimal working example:
public partial class FooThunderboltRegistration : ThunderboltRegistration
{
protected override void Register(IThunderboltRegistrar reg)
{
reg.AddSingleton<BazService>();
reg.AddScoped<IBarService, BarService>();
reg.AddTransientFactory<Qux>(() => new Qux());
}
}Where this code may execute before any attempt to resolve/get your services.
ThunderboltActivator.Attach<FooThunderboltRegistration>();The simplemost way to get your services would be as follows:
BazService bazService = ThunderboltActivator.Container.Get<BazService>();- Achieving dependency injection in .Net without reflection, based on roslyn source generators, with a simple and intuitive API.
- Being able to register your services with three different lifetimes: Singleton, Scoped and Transient.
- Explicit registration where you instruct the framework to register a particular service.
- The ability to register services while specifying user-defined factories for their creation while maintaining their lifetimes.
- The ability to register services while specifying user-defined logic to determine the type of the service implementation.
- Attribute-based service registration where you can use attributes to register or exclude types.
- Registration by convention where we can register services by naming convention using regular expressions.
Thunderbolt's service lifetimes are very similar (or in fact, almost identical) to those of Microsoft.Extensions.DependencyInjection that was first introduced with .Net Core.
Specifies that a single instance of the service will be created throughout your program’s lifecycle.
Specifies that a new instance of the service will be created for each scope. If no scope was available at the time of resolving the service (i.e the IThundernoltResolver used was not an IThunderboltScope), a singleton service will be returned.
If a service gets resolved using an IThunderboltScope as the IThunderboltResolver, each and every dependency of that service will be resolved using the same IThunderboltScope.
Specifies that a new instance of the service will be created every time it is requested.
As well as services registered for you by default, here are three ways in which you may register your assemblies:
- Explicit registration
- Attribute registration
- Regex-based attribute registration
All the three of them are valid to use either alone or in conjunction with any other. In fact, the source generator generates explicit registrations for attribute registrations.
- IThunderboltContainer The container itself is registered as a singleton service. In fact, even ThunderboltActivator.Container that you may use to get the container returns the same singleton instance.
- IThunderboltResolver
This is also registered as a singleton instance and returns an
IThunderboltContainer(the same as above). -
IThunderboltScope
This is registered as a transient service, meaning, every time you try to resolve/get anIThunderboltScope, a newIThunderboltScopewill be created. This is the same asIThunderboltContainer.CreateScope().It is worth mentioning that an
IThunderboltScopeis anIDisposable, however, that doesn't mean that disposing anIThunderboltScopewould dispose scoped instances (at least in the current release).
After you have created a partial class that inherits ThunderboltRegistration, you will have to override the abstract void Register. This method gives you a single argument of type IThunderboltRegistrar (reg), which you can use to register your services using the Add{serviceLifetime} methods.
For explicit registration, code generation is going to happen for every Add{serviceLifetime} call that happens inside (except for factory registrations), regardless of whether or not you implement a logic in your Register method (i.e even if you implement a logic where a particular call to an Add method is not reachable, code generation would still consider it anyway).
Explicit registration supports four different scenarios for registering your services.
For this scenario, you may register your services like:
reg.AddSingleton<FooService>();
reg.AddScoped<BarService>();
reg.AddTransient<BazService>();For this scenario, you may register your services like:
reg.AddSingleton<IFooService, FooService>();
reg.AddScoped<IBarService, BarService>();
reg.AddTransient<IBazService, BazService>();For this scenario, you may register your services like:
reg.AddSingletonFactory<FooService>();
reg.AddScopedFactory<BarService>();
reg.AddTransientFactory<BazService>();In this scenario, no code generation happens at all as it is assumed that you are going to provide all the necessary details to get an instance of this service. Service lifetimes however would still apply to service registered using any of the factory signatures.
For this scenario, you may register your services like:
reg.AddSingleton<IYearHalfService>(() =>
{
if (DateTime.UtcNow.Month <= 6)
return typeof(YearFirstHalfService);
else
return typeof(YearSecondHalfService);
});In this scenario, it is important to know that code generation happens for every capture of the statement return typeof(TService) inside the scope. This means that your implementations must be known at the compile time. It is also important to notice that either this:
Type fooType = typeof(FooType);
return fooType;or that:
return someFooVariable.GetType();will not work.
Also, you cannot pass a function pointer to this signature. It will compile but it won't work. The only accepted syntaxes are lambda expressions (e.g () => typeof(TService) or () => { return typeof(TService); }) and anonymous method expressions (e.g delegate { return typeof(TService); }).
This is where you may register your services using attributes. It is important to know that even if you don't have any explicit registrations, you still need to create a partial class that inherits ThunderboltRegistration for attribute registration to work. Attribute registrations are managed via two attributes (+ the regex ones): ThunderboltIncludeAttribute andThunderboltExcludeAttribute.
Define this attribute at the top of the types you want to register. There are few signatures for this attribute but they all come down to three simple arguments.
- serviceLifetime (required) Specifies the service lifetime you want to register for this service.
- implementation (optional) If this service has another type as its implementation, this is how you may specify that.
- applyToDerviedTypes (optional, default: false)
Determines whether derived types should also be registered just like this service.
It is important to note that captured derived types are limited only to the types that are accessible in the assembly that defines the attribute; meaning: if you have an assembly
FooAssemblywhere you useThunderboltIncludeAttribute(with applyToDerivedTypes: true), and another assemblyBarAssemblythat referencesFooAssemblybut also defines some derived types, types inBarAssemblywill not be registered (unless anotherThunderboltIncludeAttributeis defined inBarAssemblyas well).
Specifies that this type will not be registered unless it gets registered explicitly via ThunderboltRegistration.Register (even if ThunderboltIncludeAttribute or ThunderboltRegexIncludeAttribute is present).
This attribute also has the optional parameter (default: false) applyToDerivedTypes which specifies that derived types accessible in this assembly should not be registered via attribute-registration attributes.
This is how you may register several services at once, using their naming convention. Just like non-regex attribute registration, it is important to create a partial class that inherits ThunderboltRegistration for this to work, even if you don't have any explicit registrations. Regex attribute registrations are managed via two attributes: (ThunderboltRegexIncludeAttribute and ThunderboltRegexExcludeAttribute).
Attributes used for regex-based registration are assembly-level attributes (they should be defined on the target assembly [assembly: ThunderboltRegexIncludeAttribute(...)]).
This is where you define your conventions for naming-convention-based registration. The first argument passed to this attribute is the service lifetime for all the services matched by this attribute.
The regex argument passed to the attribute should match all the types that you wish to register. Your pattern is tested against the full names of the types (global::Type.Full.Namespace.TypeName).
Beware that your pattern gets tested against all of the accessible types, meaning that you may want to write a pattern that does not include types defined under the System namespace for instance.
You may have several ThunderboltRegexIncludeAttribute on the same assembly to define different patterns and lifetimes.
Using only the two arguments discussed above is going to be sufficient for this scenario.
For this scenario, two more arguments are going to be needed in addition to the lifetime and the regex.
- implRegex This should be a regular expression that matches all of your implementation types (and only your implementation types).
- joinKeyRegex By now, your regex argument should be matching a number of services, and your implRegex argument should be matching a number of service implementations. This parameter is used to select a particular join key from the results matched by both of your other arguments to determine which implementations correspond to which services. This is also a regular expression.
5.4.1.2.1 IFooService: FooService: For the common scenario where we may want to match IFooService with FooService, we may use the following:
[assembly: ThunderboltRegexInclude(
ThunderboltServiceLifetime.Scoped,
regex: @"(global::)?(MyBaseNamespace)\.I[A-Z][A-z_]+Service",
implRegex: @"(global::)?(MyBaseNamespace)\.[A-Z][a-z][A-z_]+Service",
joinKeyRegex: @"(?<=(global::)?(MyBaseNamespace)\.I?)[A-Z][a-z][A-z_]+Service")]This is where you may specify a regular expression that when matched with any type, does not get registered via attribute registration (and/or regex-based attribute registration).
Getting service instances with respect to their registered lifetimes is as simple as using Get<TService>() on an IThunderboltResolver. An IThunderboltResolver may either be an IThunderboltContainer or an IThunderboltScope.
Provided you have attached at least one partial class that inherits ThunderboltRegistration via ThunderboltActivator.Attach, it is safe to use ThunderboltActivator.Container property to get the singleton IThunderboltContainer instance. If you already have an IThunderboltResolver, you may also get the same container using resolver.Get<IThunderboltContainer>().
Using an IThunderboltContainer, you may create a new scope using container.CreateScope(). If you already have an IThunderboltResolver, you may create a new scope using resolver.Get<IThunderboltScope>().
All project types are inherently supported and your project wouldn't complain about working with ThunderboltIoc. However, up until the moment of writing this, there is no explicit integration with Microsoft.Extensions.DependencyInjection, which to some extent limits our options when working with .Net Core projects if we wanted to utilize Microsoft's DI.
It is intended for ThunderboltIoc to integrate with Microsoft.Extensions.DependencyInjection in the future, but it the meantime, there would be no harm in using both frameworks together side-by-sidy; that however wouldn't let us fully benefit from ThunderboltIoc's superior performance all the time.
It is perfectly safe to use ThunderboltIoc for any .Net C# project as a standalone IoC.
The only services for which code generation can work are services that have exactly one constructor that is public. It is planned to lift this restriction in future versions.
As mentioned in the section above, it is feasible and desired to remove this limitation.
Currently, in the best-case scenario and if you follow the documentation, we shouldn't worry about source generation exceptions. However, upon failing to adhere to the documentation, it is possible that an unhandled exception might arise. In such a case, the source generator might (or might not) fail at the whole process. When that happens, it is possible that no code gets generated at all (you would get a notification in the build output but you might not notice it).
It is planned to provide better exception handling so that failure to generate code for a particular service wouldn't cause the whole process to fail. It would also be nice to generate relevant warnings or errors.
Currently, it is possible to fall into an infinite resolve operation where one (or more) service's dependencies may directly or indirectly depend on the same service.
It would be beneficial to have static code analyzers that show you warnings about failing to adhere to the best practices discussed in the documentation. For instance, generate a warning that tells you that a class you created that inherits ThunderboltRegistration does not have the partial modifier.
As is the case with any feature-rich IoC framework, property injection is a dependency injection style that is not currently supported by this framework.
Disposing an IThunderboltScope should in turn dispose every IDisposable scoped service saved in the corresponding IThunderboltScope.
The goal is to provide an intuitive API to effectively replace the default IServiceProvider of Microsoft's DI. Currently, IThunderboltResolver already implements System.IServiceProvider but no present elegant integration exists.
I hope this first release make it up to your expectations! I'm really looking forward to hearing your feedback and suggestions here or on twitter @aly_elhaddad!
Project link on GitHub: https://github.com/AlyElhaddad/ThunderboltIoc
24