SteroidsDI.AspNetCore
1.4.2
dotnet add package SteroidsDI.AspNetCore --version 1.4.2
NuGet\Install-Package SteroidsDI.AspNetCore -Version 1.4.2
<PackageReference Include="SteroidsDI.AspNetCore" Version="1.4.2" />
paket add SteroidsDI.AspNetCore --version 1.4.2
#r "nuget: SteroidsDI.AspNetCore, 1.4.2"
// Install SteroidsDI.AspNetCore as a Cake Addin #addin nuget:?package=SteroidsDI.AspNetCore&version=1.4.2 // Install SteroidsDI.AspNetCore as a Cake Tool #tool nuget:?package=SteroidsDI.AspNetCore&version=1.4.2
SteroidsDI
<a href="https://www.buymeacoffee.com/sungam3r" target="_blank"><img src="https://bmc-cdn.nyc3.digitaloceanspaces.com/BMC-button-images/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: auto !important;width: auto !important;" ></a>
Advanced Dependency Injection to use every day.
Installation
This repository provides the following packages:
You can install the latest stable version via NuGet:
> dotnet add package SteroidsDI
> dotnet add package SteroidsDI.Core
> dotnet add package SteroidsDI.AspNetCore
What is it ? Why do I need it ?
.NET Core has built-in support for Dependency Injection. It works and works quite well. We can use the dependencies of the three main lifetimes: singleton, scoped, transient. There are rules that specify possible combinations of passing objects with one lifetime in objects with another lifetime. For example, you may encounter such an error message:
Error while validating the service descriptor 'ServiceType: I_XXX Lifetime: Singleton ImplementationType: XXX': Cannot consume scoped service 'YYY' from singleton 'I_XXX'.
The error says that you cannot pass an object with a shorter lifetime to the constructor of a long-living object. Well that's right! The problem is clear. But how to solve it? Obviously, when using constructor dependency injection (.NET Core has built-in support only for constructor DI), we must follow these rules. So we have at least 3 options:
- Lengthen lifetime for injected object.
- Shorten lifetime for an object that injects a dependency.
- Remove such a dependency.
- Change the design of dependencies so as to satisfy the rules.
The first method is far from always possible. The second method is much easier to implement, although this will lead to a decrease in performance due to the repeated creation of objects that were previously created once. The third way... well, you understand, life will not become easier. So it remains to somehow change the design. This project just offers such a way to solve the problem, introducing a number of auxiliary abstractions. As many already know
Any programming problem can be solved by introducing an additional level of abstraction with the exception of the problem of an excessive number of abstractions.
The project provides three such abstractions:
- Well known
Func<T>
delegate. Defer<T>
/IDefer<T>
abstractions which look likeLazy<T>
but have a significant difference -Defer<T>
/IDefer<T>
do not cache the value.- A named factory interface, when implementation type is generated at runtime.
All these abstractions solve the same problem, approaching the design of their API from different angles. The challenge is to provide a dependency T through some intermediary object X where an explicit dependency on T is either not possible or not desirable. Important! No implementation in this package caches dependency T.
As mentioned above an example of impossibility is a dependency on a scoped lifetime in an object with a singleton lifetime. And an example of non-desirability is creating dependency is expensive and not always required.
There is one important point to make - injecting dependency is not the same as using dependency. In fact, in the case of constructor injection, the injection of the dependency in the constructor leads (in most cases) to storing a reference to the passed value in the some field. The dependency will be used later when calling the methods of "parent" object.
Func<T>
This method is the easiest and offers to inject Func<T>
instead of T
:
Before:
class MyObject
{
private IRepository _repo;
public MyObject(IRepository repo) { _repo = repo; }
public void DoSomething() { _repo.DoMagic(); }
}
After:
class MyObject
{
private Func<IRepository> _repo;
public MyObject(Func<IRepository> repo) { _repo = repo; }
public void DoSomething() { _repo().DoMagic(); }
}
How to configure in DI:
public void ConfigureServices(IServiceCollection services)
{
// First register your IRepository and then call
services.AddFunc<IRepository>();
}
Note that you should call AddFunc
for each dependency T
which you want to inject as Func<T>
.
IDefer<T> and Defer<T>
This method suggests more explicit API - inject IDefer<T>
or Defer<T>
instead of T
:
Before:
class MyObject
{
private IRepository _repo;
public MyObject(IRepository repo) { _repo = repo; }
public void DoSomething() { _repo.DoMagic(); }
}
After:
class MyObject
{
private Defer<IRepository> _repo;
public MyObject(Defer<IRepository> repo) { _repo = repo; }
public void DoSomething() { _repo.Value.DoMagic(); }
}
How to configure in DI:
public void ConfigureServices(IServiceCollection services)
{
// First register your IRepository and then call
services.AddDefer();
}
Note that unlike AddFunc<T>
, the AddDefer
method needs to be called only once. Use IDefer<T>
interface if you
need covariance.
Named factory
This method is the most difficult to implement, but from the public API point of view it is just as simple as previous two. It assumes that you declare a factory interface with one or more methods without parameters. Method name does not matter. Each factory method should return some dependency type configured in DI container:
public interface IRepositoryFactory
{
IRepository GetPersonsRepo();
}
And inject this factory into your "parent" type:
class MyObject
{
private IRepositoryFactory _factory;
public MyObject(IRepositoryFactory factory) { _factory = factory; }
public void DoSomething() { _factory.GetPersonsRepo().DoMagic(); }
}
How to configure in DI:
public void ConfigureServices(IServiceCollection services)
{
// First register your IRepository and then call
services.AddFactory<IRepositoryFactory>();
}
Implementation for IRepositoryFactory
will be generated at runtime.
In fact, each factory method can take one parameter of an arbitrary type - string, enum, custom class, whatever. In this case, a named binding should be specified. Then you may resolve required services passing the name of the binding into factory methods. If you want to provide a default implementation then you may configure default binding. Default binding is such a binding used in the absence of a named one. A user should set default binding explicitly to be able to resolve services for unregistered names.
public interface IRepositoryFactory
{
IRepository GetPersonsRepo(string mode);
}
public interface IRepository
{
void Save(Person person);
}
public class DemoRepository : IRepository
{
...
}
public class ProductionRepository : IRepository
{
...
}
public class RandomRepository : IRepository
{
...
}
public class DefaultRepository : IRepository
{
...
}
public void ConfigureServices(IServiceCollection services)
{
services.AddTransient<IRepository, DemoRepository>()
.AddTransient<IRepository, ProductionRepository>()
.AddTransient<IRepository, RandomRepository>()
.AddFactory<IRepositoryFactory>()
.For<IRepository>()
.Named<DemoRepository>("demo")
.Named<ProductionRepository>("prod")
.Named<RandomRepository>("rnd")
.Default<DefaultRepository>();
}
public class Person
{
public string Name { get; set; }
}
public class SomeClassWithDependency
{
private readonly IRepositoryFactory _factory;
public SomeClassWithDependency(IRepositoryFactory factory)
{
_factory = factory;
}
private bool SomeInterestingCondition => ...
public void DoSomething(Person person)
{
if (person.Name == "demoUser")
_factory.GetPersonsRepo("demo").Save(person); // DemoRepository
else if (person.Name.StartsWith("tester"))
_factory.GetPersonsRepo("rnd").Save(person); // RandomRepository
else if (SomeInterestingCondition)
_factory.GetPersonsRepo("prod").Save(person); // ProductionRepository
else
_factory.GetPersonsRepo(person.Name).Save(person); // DefaultRepository
}
}
In the example above, the GetPersonsRepo
method will return the corresponding implementation of the IRepository
interface, configured for the provided name. For all unregistered names (including null) it will return DefaultRepository
.
How it works?
Everything is simple here. All three methods come down to delegating dependency resolution to
the appropriate IServiceProvider
. What does appropriate mean? As a rule, in a ASP.NET Core application, everyone
is used to working with one (scoped) provider obtained from IHttpContextAccessor
- HttpContext.RequestServices
.
But in the general case, there can be many such providers. In addition, dependency-consuming code is not aware of their
existence. This code may be a general purpose library no tightly coupled with application specific environment. Therefore
abstraction for obtaining the appropriate IServiceProvider
is introduced. Yes,
one more abstraction again!
This project provides two built-in providers:
AspNetCoreHttpScopeProvider
for ASP.NET Core apps.GenericScopeProvider<T>
for general purpose libraries.
How to configure in DI:
public void ConfigureServices(IServiceCollection services)
{
services.AddHttpScope();
services.AddGenericScope<SomeClass>();
}
And of course you can always write your own provider:
public class MyScopeProvider : IScopeProvider
{
public IServiceProvider? GetScopedServiceProvider(IServiceProvider rootProvider) => rootProvider.ReturnSomeMagic();
}
And provide its registration in DI:
public static class ServiceCollectionExtensions
{
public static IServiceCollection AddMyScope(this IServiceCollection services)
{
services.TryAddEnumerable(ServiceDescriptor.Singleton<IScopeProvider, MyScopeProvider>());
return services;
}
}
Advanced behavior
You can customize the behavior of AddFunc
/AddDefer
/AddFactory
APIs via ServiceProviderAdvancedOptions:
Just use standard extension methods from Microsoft.Extensions.Options/Microsoft.Extensions.Options.ConfigurationExtensions
packages.
public void ConfigureServices(IServiceCollection services)
{
services.Configure<ServiceProviderAdvancedOptions>(options => options.AllowRootProviderResolve = true)
services.Configure<ServiceProviderAdvancedOptions>(Configuration.GetSection("Steroids"));
}
Examples
You can see how to use all the aforementioned APIs in the example project.
FAQ
Q. Wait a moment. Doesn't Microsoft.Extensions.DependencyInjection
have support for this out of the box?
A. Unfortunately no. I myself would rather be able to use the existing feature than to write my own package.
<br/>
Q. Isn't what you offer is a ServiceLocator? I heard that the ServiceLocator is anti-pattern.
A. Yes, ServiceLocator is a known antipattern.
The fundamental difference with the proposed solutions is that ServiceLocator allows you to resolve
any dependency in runtime while Func<T>
, Defer<T>
and Named Factory are designed to resolve
only known dependencies specified at the compile-time. Thus, the principal difference is that all
the dependences of the class are declared explicitly and are injected into it. The class itself does
not pull these dependencies secretly within its implementation. This is so called Explicit Dependencies Principle.
<br/>
Q. Is this some kind of new dependency injection approach?
A. Actually not. A description of this approach can be found in articles/blogs many years ago, for example here.
<br/>
Q. What should I prefer - Func<>
or [I]Defer<>
?
A. The main thing is they all work equally under the hood. The difference is in which context you are going to use these APIs.
There are two main differences:
The advantage of
Func<>
is that the code in which you injectFunc<>
does not require any new dependency, it is well-known .NET delegate type. On the contrary[I]Defer<>
requires a reference toSteroidsDI.Core
package.You should call
AddFunc
for each dependencyT
which you want to inject asFunc<T>
. On the contrary theAddDefer
method needs to be called only once.
<br/>
Q. What if I want to create my own scope to work with, i.e. not only consume it but also provide?
A. First you should somehow get an instance of root IServiceProvider
.
Then create scope by calling CreateScope()
method on it and set it into GenericScope
:
var rootProvider = ...;
using var scope = rootProvider.CreateScope();
GenericScope<SomeClass>.CurrentScope = scope;
...
... Some code here that works with scopes.
... All registered Func<T>, [I]Defer<T> and
... factories use created scope.
...
GenericScope<T>.CurrentScope = null;
Or you can use a bit simpler approach with Scoped<T>
struct.
IScopeFactory scopeFactory = ...; // can be obtained from DI, see AddMicrosoftScopeFactory extension method
using (new Scoped<SomeClass>(scopeFactory))
or
await using (new Scoped<SomeClass>(scopeFactory)) // Scoped class supports IAsyncDisposable as well
{
...
... Some code here that works with scopes.
... All registered Func<T>, [I]Defer<T> and
... factories use created scope.
...
}
Also see ScopedTestBase and ScopedTestDerived for more info. This example shows how you can add scope support to all unit tests.
Benchmarks
The results are available here.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 is compatible. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 is compatible. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETCoreApp 3.1
- SteroidsDI.Core (>= 1.4.2)
-
.NETStandard 2.0
- Microsoft.AspNetCore.Http (>= 2.2.2)
- SteroidsDI.Core (>= 1.4.2)
-
net5.0
- SteroidsDI.Core (>= 1.4.2)
-
net6.0
- SteroidsDI.Core (>= 1.4.2)
-
net7.0
- SteroidsDI.Core (>= 1.4.2)
-
net8.0
- SteroidsDI.Core (>= 1.4.2)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
1.4.2 | 4,456 | 3/18/2024 |
1.4.1 | 2,103 | 1/20/2024 |
1.4.0 | 506 | 1/4/2024 |
1.3.0 | 804 | 11/18/2023 |
1.2.0 | 9,568 | 12/29/2022 |
1.1.1 | 2,402 | 12/1/2022 |
1.1.0 | 6,840 | 5/2/2022 |
1.0.3 | 885 | 4/15/2022 |
1.0.2 | 1,287 | 3/31/2022 |
1.0.1 | 7,960 | 10/16/2021 |
1.0.0 | 13,577 | 2/26/2021 |
0.0.7 | 4,358 | 11/24/2020 |
0.0.6 | 797 | 11/24/2020 |
0.0.5 | 1,823 | 10/26/2020 |
0.0.4 | 19,056 | 6/25/2020 |
0.0.3 | 993 | 3/10/2020 |
0.0.2 | 894 | 3/9/2020 |
0.0.1 | 955 | 3/8/2020 |