TailoredApps.Shared.EntityFramework.UnitOfWork.MinimalApi¶
Description¶
A transaction per request for minimal APIs: an endpoint filter that ends an endpoint with a commit or a rollback of the unit of work of
TailoredApps.Shared.EntityFramework. It is the counterpart of the MVC filter in
UnitOfWork.WebApiCore - with the same rules - for applications without controllers. The library is a package
of its own; it changes nothing in the existing ones.
- Commits after the endpoint succeeds (pending changes are saved first) - the endpoint does not call
SaveChanges - Rolls back after an exception, or when the endpoint returned a result with a status of 400 or more (
Results.BadRequest(),Results.Conflict(), …) - An endpoint that returns a plain object, or a result without a status code, counts as a success
- Optionally sets the isolation level for an endpoint or a group
NativeAOT
The filter itself uses no reflection, but the library depends on Entity Framework Core, which is not ready for NativeAOT (see Trimming and NativeAOT). Minimal APIs without AOT work without restrictions.
Installation¶
DI registration¶
// Program.cs
using TailoredApps.Shared.EntityFramework.UnitOfWork.MinimalApi;
builder.Services.AddDbContext<ShopDbContext>(options => options.UseSqlServer(connectionString));
builder.Services.AddUnitOfWorkForMinimalApi<IShopDbContext, ShopDbContext>();
AddUnitOfWorkForMinimalApi registers what AddUnitOfWork of TailoredApps.Shared.EntityFramework does and returns the same builder
(hooks, auditing). An application that already calls AddUnitOfWorkForWebApi for its controllers does not register the unit of work twice.
Usage example¶
using TailoredApps.Shared.EntityFramework.Interfaces.UnitOfWork;
using TailoredApps.Shared.EntityFramework.UnitOfWork.MinimalApi;
// A whole group in a transaction
var products = app.MapGroup("/api/products").WithUnitOfWorkTransaction();
products.MapPost("/", async (NewProduct product, IUnitOfWork<IShopDbContext> unitOfWork, CancellationToken cancellationToken) =>
{
var db = unitOfWork.DataProvider;
db.Products.Add(new Product { Name = product.Name, Price = product.Price });
// The product is already in the context. Answering 409 makes the filter roll it back.
if (await db.Products.AnyAsync(p => p.Name == product.Name, cancellationToken))
return Results.Conflict();
return Results.Created($"/api/products/{product.Name}", product); // commit - no SaveChanges
});
// One endpoint with its own isolation level
app.MapPost("/api/transfers", (Transfer transfer, IUnitOfWork<IShopDbContext> unitOfWork) => { /* ... */ })
.WithUnitOfWorkTransaction(IsolationLevel.Serializable);
Filters run in the order they are added. With ExceptionHandling.MinimalApi add exception handling first, so that it also answers for an exception thrown by the commit:
app.MapGroup("/api/products")
.WithExceptionHandling() // outer: turns an exception into the error response
.WithUnitOfWorkTransaction(); // inner: commit / rollback
API Reference¶
| Type | Kind | Description |
|---|---|---|
UnitOfWorkMinimalApiExtensions.AddUnitOfWorkForMinimalApi<TI, T> |
Ext. method | Registers the unit of work for a minimal-API application |
UnitOfWorkMinimalApiExtensions.WithUnitOfWorkTransaction<TBuilder>(isolationLevel) |
Ext. method | Adds the transaction filter to an endpoint (RouteHandlerBuilder) or a group (RouteGroupBuilder) |
UnitOfWorkTransactionEndpointFilter |
Endpoint filter | Commit after a success, rollback after an exception or a result with a status ≥ 400 |
🔒 Transaction consistency¶
- Rollback on an error response, not only on an exception: partial writes made before
return Results.Conflict()do not stay in the database. - A failed commit is not lost. When the commit fails the transaction is rolled back and the commit exception is thrown; when the
rollback fails too, both end up in an
AggregateException. - The transaction opens lazily - at the first
SaveChanges/SaveChangesAsync(the commit at the end counts) or afterBeginTransactionManually(). CallBeginTransactionManually()before a read that has to be protected by the transaction. - Isolation levels:
ReadCommittedby default;ReadCommitted,ReadUncommittedandSerializableare supported.
🤖 AI Agent Prompt¶
## TailoredApps.Shared.EntityFramework.UnitOfWork.MinimalApi - instructions for an AI agent
You are using a transaction per request in ASP.NET Core minimal APIs through an endpoint filter.
### Registration
```csharp
// Program.cs
builder.Services.AddDbContext<MyDbContext>(...);
builder.Services.AddUnitOfWorkForMinimalApi<IMyDbContext, MyDbContext>();
app.MapGroup("/api/orders").WithUnitOfWorkTransaction(); // a whole group
app.MapPost("/api/transfers", handler).WithUnitOfWorkTransaction(IsolationLevel.Serializable);
```
### What gets configured
- IUnitOfWork and IUnitOfWork<IMyDbContext> (scoped) - inject IUnitOfWork<IMyDbContext> into the endpoint
- The endpoint filter: success -> CommitTransaction() (saves the changes), an exception or a result with a status >= 400 -> RollbackTransaction()
### Configuration
- No configuration keys. The isolation level is passed to WithUnitOfWorkTransaction(isolationLevel)
### Rules
- Do not call SaveChanges, CommitTransaction or RollbackTransaction in an endpoint - the filter does
- Return a business failure as a 4xx result (Results.Conflict(), Results.BadRequest()) - the filter rolls the changes back
- With ExceptionHandling.MinimalApi add WithExceptionHandling() before WithUnitOfWorkTransaction()
- Do not register the unit of work twice: in an application with controllers AddUnitOfWorkForWebApi is enough
- For MVC controllers use the UnitOfWork.WebApiCore package, not this one
- The library depends on EF Core: do not use it in an application published with PublishAot