Faactory.DbContext.Core
0.7.0
dotnet add package Faactory.DbContext.Core --version 0.7.0
NuGet\Install-Package Faactory.DbContext.Core -Version 0.7.0
<PackageReference Include="Faactory.DbContext.Core" Version="0.7.0" />
paket add Faactory.DbContext.Core --version 0.7.0
#r "nuget: Faactory.DbContext.Core, 0.7.0"
// Install Faactory.DbContext.Core as a Cake Addin
#addin nuget:?package=Faactory.DbContext.Core&version=0.7.0
// Install Faactory.DbContext.Core as a Cake Tool
#tool nuget:?package=Faactory.DbContext.Core&version=0.7.0
ADO.NET Extensions
This project contains a set of extensions to help with managing multiple data sources, more specifically, inside a DI scenario.
Getting started
Before we can use the extensions, we need to register the context provider with our DI container. We'll have to install the appropriate package, depending on the provider we want to use; the following are currently supported
Provider | Package | Description |
---|---|---|
PostgreSql | Faactory.DbContext.Npgsql | PostgreSQL driver; uses Npgsql |
SqlServer | Faactory.DbContext.SqlClient | SQL Server driver; uses Microsoft.Data.SqlClient |
SqlServer | Faactory.DbContext.RestSql | SQL Server via restSQL; still experimental |
We'll use SqlServer as an example
dotnet add package Faactory.DbContext.SqlClient
We'll then register the provider and configure our databases; we can add as many contexts as we need.
IServiceCollection services = ...;
services.AddSqlDbContextProvider()
.AddDbContext( "my-db", "connection_string" )
.AddDbContext( "my-other-db", "connection_string" );
Wherever we need to get access to our database context, we'll use the injected IDbContextFactory
instance to retrieve an IDbContext
instance.
public class Example
{
private readonly IDbContext mydb;
public Example( IDbContextFactory dbContextFactory )
{
mydb = dbContextFactory.GetDbContext( "my-db" );
}
// ...
}
To construct a new connection, we'll retrieve it from the IDbContext
instance.
public class Example
{
private readonly IDbContext mydb;
// ...
public async Task DoSomethingAsync()
{
using ( var connection = mydb.GetDbConnection() )
{
await connection.OpenAsync();
// ...
}
}
}
We can also construct the connection and open it all in one go.
public async Task DoSomethingAsync()
{
using ( var connection = await mydb.OpenAsync() )
{
// ...
}
}
From this point forward, we'll have a DbConnection
instance ready to use. Please note that all DbConnection
instances should be properly disposed after use. Most of the ADO implementations will pool connections and not properly disposing them can lead to exceeding the number of open connections (connection leaks).
NOTICE: Starting with version 0.6, the library has switched to use the
DbConnection
class instead of theIDbConnection
interface. This was done mostly because the interface doesn't expose the async methods. SinceDbConnection
should be the base class for most (if not all) ADO.NET providers, this transition shouldn't cause any braking changes. Nonetheless, if you're using theIDbConnection
interface, you'll have to update your code to use theDbConnection
class instead.
Transactions
As an alternative to the DbConnection.BeginTransaction[Async]
methods, there are extensions available to shorten the amount of code written. The UseTransaction[Async]
methods take care of opening/reusing a connection, creating a transaction and gracefully disposing of it all when finished.
public async Task DoSomethingAsync()
{
await mydb.UseTransactionAsync( async t =>
{
var sqlCommand = t.Connection.CreateCommand();
// ...
await t.CommitAsync();
} );
}
If an exception is thrown, the transaction is automatically rolled back. We can also provide additional behaviour to when this happens.
public async Task DoSomethingAsync()
{
await mydb.UseTransactionAsync( async t =>
{
var sqlCommand = t.Connection.CreateCommand();
// ...
await t.CommitAsync();
}, ex =>
{
// handle exception
} );
}
Health checks
The library also provides a set of health checks that verify the status of the database contexts. These health checks can be used with the ASP.NET Core health checks middleware.
IServiceCollection services = ...;
services.AddHealthChecks()
.AddDbContext( "my-db" )
.AddDbContext( "my-other-db" );
Command builder
The command builder is a helper class that can be used to build SQL commands. It provides a fluent interface to build a DbCommand
instance. The builder can be accessed by calling the BuildCommand
extension method on IDbContext
or DbConnection
instances.
private readonly IDbContext mydb;
// ...
/*
This example creates a command builder from the connection instance.
This is probably the most straightforward way to use the builder.
*/
public async Task UseBuilderFromConnectionAsync()
{
using ( var connection = await mydb.OpenAsync() )
{
var command = connection.BuildCommand()
.SetText( "SELECT * FROM table WHERE id = @id" )
.AddParameter( "@id", 1 )
.Build();
using ( var reader = await command.ExecuteReaderAsync() )
{
// ...
}
}
}
/*
This example creates a command builder directly from the context instance.
Please note that in this caase, the command builder will ask for a connection
instance from the context, which means that you'll have to properly dispose of it after use.
*/
public async Task UseBuilderFromContextAsync()
{
var command = mydb.BuildCommand()
.SetText( "SELECT * FROM table WHERE id = @id" )
.AddParameter( "@id", 1 )
.Build();
// ensure that the connection is properly disposed of after use
using ( command.Connection )
{
await command.Connection.OpenAsync();
using ( var reader = await command.ExecuteReaderAsync() )
{
// ...
}
}
}
Compatibility with Object Mappers
The library is compatible with most object mappers that use DbConnection
or IDbConnection
instances, such as Dapper, PetaPoco or Norm.net.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | 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. |
-
net6.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.1)
- Microsoft.Extensions.Diagnostics.HealthChecks (>= 8.0.6)
- Microsoft.Extensions.Options (>= 8.0.2)
-
net7.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.1)
- Microsoft.Extensions.Diagnostics.HealthChecks (>= 8.0.6)
- Microsoft.Extensions.Options (>= 8.0.2)
-
net8.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.1)
- Microsoft.Extensions.Diagnostics.HealthChecks (>= 8.0.6)
- Microsoft.Extensions.Options (>= 8.0.2)
NuGet packages (3)
Showing the top 3 NuGet packages that depend on Faactory.DbContext.Core:
Package | Downloads |
---|---|
Faactory.DbContext.SqlClient
DbContext SqlServer provider |
|
Faactory.DbContext.Npgsql
DbContext PostgreSql provider |
|
Faactory.DbContext.RestSql
DbContext RestSql provider |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
0.7.0 | 80 | 5/31/2024 |
0.6.1 | 126 | 3/8/2024 |
0.6.0 | 278 | 10/23/2023 |
0.6.0-preview-1 | 90 | 9/27/2023 |
0.5.2-preview-2 | 112 | 9/26/2023 |
0.5.2-preview-1 | 90 | 9/25/2023 |
0.5.1 | 197 | 7/7/2023 |
0.5.0 | 207 | 4/27/2023 |
0.4.0 | 624 | 8/9/2022 |
0.3.5 | 724 | 3/23/2022 |
0.3.4 | 697 | 3/18/2022 |
0.3.3 | 710 | 3/18/2022 |
0.3.2 | 712 | 3/18/2022 |
0.3.1 | 707 | 3/18/2022 |
0.3.0 | 702 | 3/17/2022 |
0.2.2 | 699 | 3/16/2022 |
0.2.1 | 448 | 10/4/2021 |
0.1.0 | 449 | 9/29/2021 |