Lagoon.DependencyInjection
2.0.1
dotnet add package Lagoon.DependencyInjection --version 2.0.1
NuGet\Install-Package Lagoon.DependencyInjection -Version 2.0.1
<PackageReference Include="Lagoon.DependencyInjection" Version="2.0.1" />
<PackageVersion Include="Lagoon.DependencyInjection" Version="2.0.1" />
<PackageReference Include="Lagoon.DependencyInjection" />
paket add Lagoon.DependencyInjection --version 2.0.1
#r "nuget: Lagoon.DependencyInjection, 2.0.1"
#:package Lagoon.DependencyInjection@2.0.1
#addin nuget:?package=Lagoon.DependencyInjection&version=2.0.1
#tool nuget:?package=Lagoon.DependencyInjection&version=2.0.1
Lagoon
Lagoon is an object pool for .NET. It pools objects that are expensive to initialize. Think database connections or network connections in general.
Installation
Lagoon targets net10.0. Install via NuGet:
dotnet add package Lagoon
If you want the IServiceCollection integration, also install:
dotnet add package Lagoon.DependencyInjection
Usage
Objects you want to pool must implement IDisposable, and you provide an IObjectPoolFactory<TObject> that knows how to create and (optionally) activate them:
TObject must be an interface, not a concrete class. GetObjectAsync doesn't hand you the raw
object -- it wraps it in a Castle DynamicProxy
interface proxy so that calling Dispose() on it can be intercepted and redirected back into the
pool instead of actually destroying the object (see Architecture below). Castle's
CreateInterfaceProxyWithTarget requires an interface to proxy against; passing a concrete class as
TObject compiles fine (the only constraint is class, IDisposable) but fails at runtime with
ArgumentException: Specified type is not an interface the first time the pool tries to create an
object -- pool through an interface your class implements instead.
public interface IObjectPoolFactory<TObject>
where TObject : class, IDisposable
{
TObject Create();
Task ActivateAsync(TObject obj, CancellationToken token = default);
}
using Lagoon;
var factory = new MyFactory(); // implements IObjectPoolFactory<MyObject>
var pool = new DefaultObjectPool<MyObject>(factory);
using (var obj = await pool.GetObjectAsync())
{
// do something with the object
} // obj is not actually disposed here -- Dispose() returns it to the pool instead
pool.Dispose(); // disposes the pool, and every object still in it
Get an object with pool.GetObjectAsync(). Disposing the returned object doesn't dispose the underlying instance -- it returns it to the pool for reuse. pool.Dispose() disposes the pool itself along with every object currently sitting idle in it. Disposing the pool while objects are still checked out throws an InvalidOperationException, so make sure everything you've borrowed has been returned first.
Options
Pass an ObjectPoolOptions to DefaultObjectPool<TObject> to control pool sizing and timeouts:
var options = new ObjectPoolOptions
{
MinObjects = 3, // pool tries to keep at least this many objects on hand
MaxObjects = 10, // GetObjectAsync blocks (up to AcquisitionTimeout) once this many are checked out
SweepFrequency = TimeSpan.FromSeconds(10), // how often the pool grows/prunes toward MinObjects
AcquisitionTimeout = TimeSpan.FromSeconds(30), // how long GetObjectAsync waits before throwing PoolExhaustedException
};
var pool = new DefaultObjectPool<MyObject>(factory, options);
Activation and passivation
You can also pass predicates that gate whether your factory's ActivateAsync runs when an object is created, and whether an idle object actually gets disposed when the pool prunes or shuts down:
var pool = new DefaultObjectPool<MyObject>(
factory,
options,
objectActivator: obj => obj.NeedsActivation,
objectPassivator: obj => obj.CanBeDisposed);
Both default to always returning true if omitted.
Dependency injection
Lagoon.DependencyInjection adds an AddObjectPool<TObject> extension for IServiceCollection. Register your IObjectPoolFactory<TObject> implementation separately -- AddObjectPool resolves it from the container:
using Lagoon.DependencyInjection;
services.AddSingleton<IObjectPoolFactory<MyObject>, MyFactory>();
services.AddObjectPool<MyObject>(options =>
{
options.MaxObjects = 20;
});
This registers IObjectPool<TObject> as a singleton (via TryAddSingleton, so it won't override a registration you've already made).
Architecture
IObjectPoolFactory<TObject>-- you implement this. It creates objects and, optionally, activates them.DefaultObjectPool<TObject>-- the pool implementation. Idle objects live in aConcurrentStack; checked-out objects are tracked in aConcurrentDictionaryuntil returned.PooledObjectWrapper<TObject>-- whatGetObjectAsyncactually hands you is a Castle DynamicProxy interface proxy wrapping your object (which is whyTObjectmust be an interface -- see the note under Usage). CallingDispose()on it is intercepted and redirected to return the object to the pool rather than disposing it; only the pool itself disposes the underlying instance, when pruning or duringpool.Dispose().- Background maintenance -- two timers run for the lifetime of the pool, on the interval set by
SweepFrequency: one prunes idle objects back towardMinObjects(respectingobjectPassivator), the other grows the pool back up towardMinObjectswhen it's below that count. - Exhaustion -- if the pool is at
MaxObjectsand all objects are checked out,GetObjectAsyncwaits for one to be returned (woken via a signal rather than polling), up toAcquisitionTimeout, after which it throwsPoolExhaustedException. Errors thrown by your factory during creation or activation are wrapped inPoolException.
Notes on Usage
- The objects to be pooled must implement
IDisposable, andTObjectmust be an interface (not a concrete class) -- see the note under Usage. - The pool itself is meant to be used throughout your application.
This repo is a companion to a blog series about object pool patterns.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Castle.Core (>= 5.2.1)
- Lagoon (>= 2.0.1)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.10)
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 |
|---|---|---|
| 2.0.1 | 139 | 8/3/2026 |
| 2.0.1-beta.20260803083449 | 73 | 8/3/2026 |
| 2.0.1-beta.20260803081923 | 71 | 8/3/2026 |
| 2.0.1-beta.20260803073200 | 78 | 8/3/2026 |
| 2.0.0 | 127 | 7/18/2026 |
| 2.0.0-beta.20260723214620 | 69 | 7/23/2026 |
| 2.0.0-beta.20260718094140 | 78 | 7/18/2026 |
| 2.0.0-beta.20260718083259 | 65 | 7/18/2026 |
| 1.2.0-beta.20260718081558 | 72 | 7/18/2026 |
| 1.1.0 | 282 | 9/30/2023 |
| 1.1.0-beta.20211202023705 | 281 | 12/2/2021 |
| 1.1.0-beta.20211202023153 | 282 | 12/2/2021 |
| 1.1.0-beta.20201111113301 | 371 | 11/11/2020 |
| 1.0.0 | 671 | 10/29/2020 |
| 1.0.0-beta.20201029045223 | 394 | 10/29/2020 |
| 1.0.0-beta.20201029043813 | 434 | 10/29/2020 |