A comprehensive Entity Framework Core library providing Repository pattern, Unit of Work, Specification pattern, dynamic filtering, pagination support, Domain Events, and Fluent Configuration API for .NET applications.
public class MyUserContext : IUserContext
{
public MyUserContext(ICurrentUserService currentUserService)
{
CurrentUser = currentUserService.UserId;
}
public string? CurrentUser { get; }
}
services.AddScoped<IUserContext, MyUserContext>();
services.AddGenericUnitOfWorkWithAudit<YourDbContext, MyUserContext>();
With Domain Events Support (Classic)
Simple Setup - Automatic Handler Registration:
// All-in-one: Domain events + automatic handler registration from calling assembly
services.AddDomainEventsWithHandlers();
// Or from specific assembly
services.AddDomainEventsWithHandlers(typeof(ProductCreatedEvent).Assembly);
public class Product : BaseAuditableEntity<int>
{
public string Name { get; set; } = string.Empty;
public decimal Price { get; set; }
public string Description { get; set; } = string.Empty;
}
// When you save a product, these properties are automatically set:
// - CreatedAt: DateTime.UtcNow (when entity is first created)
// - CreatedBy: Current user ID (from your user context)
// - UpdatedAt: DateTime.UtcNow (when entity is modified)
// - UpdatedBy: Current user ID (when entity is modified)
Entity with Soft Delete Support
// Create a soft deletable entity by implementing ISoftDelete interface
public class Product : BaseAuditableEntity<int>, ISoftDelete
{
public string Name { get; set; } = string.Empty;
public decimal Price { get; set; }
public string Description { get; set; } = string.Empty;
// ISoftDelete properties - automatically handled by AuditInterceptor
public bool IsDeleted { get; set; }
public DateTime? DeletedAt { get; set; }
public string? DeletedBy { get; set; }
}
// When you delete a product:
// - IsDeleted: Set to true (logical deletion)
// - DeletedAt: DateTime.UtcNow (when entity is soft deleted)
// - DeletedBy: Current user ID (who performed the deletion)
Entity with Domain Events
public class Product : BaseAuditableEntity<int>, ISoftDelete
{
public string Name { get; set; } = string.Empty;
public decimal Price { get; set; }
public string Description { get; set; } = string.Empty;
// ISoftDelete properties
public bool IsDeleted { get; set; }
public DateTime? DeletedAt { get; set; }
public string? DeletedBy { get; set; }
// Factory method that raises domain events
public static Product Create(string name, decimal price, string description)
{
var product = new Product
{
Name = name,
Price = price,
Description = description
};
// Raise domain event (completely optional)
product.AddDomainEvent(new ProductCreatedEvent(product.Id, product.Name, product.Price));
return product;
}
public void UpdatePrice(decimal newPrice)
{
var oldPrice = Price;
Price = newPrice;
// Raise domain event for price change
AddDomainEvent(new ProductPriceChangedEvent(Id, oldPrice, newPrice));
}
public void Delete()
{
// Add domain event before deletion
AddDomainEvent(new ProductDeletedEvent(Id, Name));
}
}
Basic CRUD Operations
public class ProductService
{
private readonly IUnitOfWork _unitOfWork;
public ProductService(IUnitOfWork unitOfWork)
{
_unitOfWork = unitOfWork;
}
public async Task<Product> CreateProductAsync(string name, decimal price, string description)
{
// Using factory method that raises domain events
var product = Product.Create(name, price, description);
var repository = _unitOfWork.GetRepository<Product, int>();
await repository.AddAsync(product);
// Domain events are automatically dispatched during SaveChanges
await _unitOfWork.SaveChangesAsync();
return product;
}
public async Task DeleteProductAsync(int productId)
{
var repository = _unitOfWork.GetRepository<Product, int>();
var product = await repository.GetByIdAsync(productId);
if (product != null)
{
product.Delete(); // Raises domain event
// Soft delete (if entity implements ISoftDelete)
await repository.DeleteAsync(product, saveChanges: true);
}
}
public async Task RestoreProductAsync(int productId)
{
var repository = _unitOfWork.GetRepository<Product, int>();
// Restore a soft-deleted product
await repository.RestoreAsync(productId, saveChanges: true);
}
public async Task<IPaginate<Product>> GetProductsAsync(int page, int size)
{
var repository = _unitOfWork.GetRepository<Product, int>();
return await repository.GetPagedAsync(page, size);
}
}
Dynamic Filtering
var filter = new FilterModel
{
SearchTerm = "laptop",
Filters = new List<FilterItem>
{
new() { Field = "Price", Operator = "greaterthan", Value = "100" },
new() { Field = "Name", Operator = "contains", Value = "gaming" }
}
};
var products = await repository.GetPagedWithFilterAsync(filter, 1, 10);
Specification Pattern
public class ExpensiveProductsSpecification : BaseSpecification<Product>
{
public ExpensiveProductsSpecification(decimal minPrice)
{
AddCriteria(p => p.Price >= minPrice);
AddInclude(p => p.Category);
ApplyOrderByDescending(p => p.Price);
}
}
// Usage
var spec = new ExpensiveProductsSpecification(1000);
var expensiveProducts = await repository.GetAsync(spec);
Pagination
// Basic pagination
var pagedProducts = await repository.GetPagedAsync(pageIndex: 1, pageSize: 10);
// Pagination with filtering and ordering
var pagedProducts = await repository.GetPagedAsync(
pageIndex: 1,
pageSize: 10,
predicate: p => p.Price > 100,
orderBy: query => query.OrderBy(p => p.Name),
includes: new List<Expression<Func<Product, object>>> { p => p.Category }
);
// Access pagination metadata
Console.WriteLine($"Total items: {pagedProducts.Count}");
Console.WriteLine($"Total pages: {pagedProducts.Pages}");
Console.WriteLine($"Has next page: {pagedProducts.HasNext}");
Console.WriteLine($"Has previous page: {pagedProducts.HasPrevious}");
✅ User Tracking: CreatedBy, UpdatedBy, DeletedBy user identification
✅ Flexible User Context: Works with any authentication system
✅ Granular Control: Choose which audit features to implement per entity
Repository Features:
✅ Generic Implementation: Works with any entity type
✅ Soft Delete Support: Built-in soft delete and restore operations
✅ Dynamic Filtering: Build complex queries from filter models
✅ Specification Pattern: Reusable and composable query specifications
✅ Pagination: Built-in pagination with metadata
✅ Bulk Operations: Efficient bulk insert, update, and delete operations
Usage Patterns
Soft Delete Entity Creation:
// Option 1: Implement ISoftDelete on existing auditable entity
public class Product : BaseAuditableEntity<int>, ISoftDelete
{
// Entity properties
public string Name { get; set; } = string.Empty;
// ISoftDelete properties (required)
public bool IsDeleted { get; set; }
public DateTime? DeletedAt { get; set; }
public string? DeletedBy { get; set; }
}
// Option 2: Only basic audit (no soft delete)
public class Category : BaseAuditableEntity<int>
{
public string Name { get; set; } = string.Empty;
// No ISoftDelete - hard deletes only
}
// Option 3: Minimal entity (no audit, no soft delete)
public class Tag : BaseEntity<int>
{
public string Name { get; set; } = string.Empty;
// Only basic entity with domain events support
}
Repository Usage with Soft Delete:
// Entities that implement ISoftDelete automatically support:
await repository.DeleteAsync(entity); // Soft delete
await repository.RestoreAsync(entity); // Restore
await repository.RestoreAsync(id); // Restore by ID
// Entities that don't implement ISoftDelete:
await repository.DeleteAsync(entity); // Hard delete only
// repository.RestoreAsync() throws InvalidOperationException
// For entities that need audit + soft delete
public class Product : BaseAuditableEntity<int>, ISoftDelete
// For entities that only need audit
public class Category : BaseAuditableEntity<int>
// For simple entities
public class Tag : BaseEntity<int>
Use factory methods for domain events:
public static Product Create(string name, decimal price)
{
var product = new Product { Name = name, Price = price };
product.AddDomainEvent(new ProductCreatedEvent(product.Id, name));
return product;
}
Repository Usage Best Practices:
Use specifications for complex queries:
public class ActiveExpensiveProductsSpec : BaseSpecification<Product>
{
public ActiveExpensiveProductsSpec(decimal minPrice)
{
AddCriteria(p => p.Price >= minPrice && !p.IsDeleted);
AddInclude(p => p.Category);
ApplyOrderByDescending(p => p.CreatedAt);
}
}
Use Unit of Work for transactions:
public async Task<Order> ProcessOrderAsync(CreateOrderRequest request)
{
return await _unitOfWork.ExecuteInTransactionAsync(async () =>
{
// Multiple repository operations
var order = await CreateOrderAsync(request);
await UpdateInventoryAsync(request.Items);
await SendNotificationAsync(order);
return order;
});
}
Requirements
.NET 9.0 or later
Entity Framework Core 9.0.6 or later
Microsoft.AspNetCore.Http.Abstractions 2.3.0 or later (for HttpContext support)
Performance Considerations
Query Performance:
Use disableTracking: true for read-only operations
Implement proper indexing for filtered properties
Use specification pattern for complex reusable queries
Consider pagination for large datasets
Domain Events Performance:
Events are dispatched synchronously during SaveChanges
Consider async handlers for I/O operations
Use background services for heavy processing
Be mindful of handler execution order
Soft Delete Performance:
Global query filters automatically exclude soft-deleted entities
Use indexes on IsDeleted column for better performance
Consider archiving old soft-deleted records
Troubleshooting
Common Configuration Issues:
DbContext not registered error:
// Ensure DbContext is registered before AddFSEntityFramework
services.AddDbContext<MyDbContext>(options => options.UseSqlServer(connectionString));
services.AddFSEntityFramework<MyDbContext>(); // Then register FS.EntityFramework
Handler not found errors:
// Ensure handlers are in the scanned assembly
services.AddFSEntityFramework<MyDbContext>()
.WithDomainEvents()
.WithAutoHandlerDiscovery(typeof(MyHandler).Assembly) // Specify correct assembly
.Complete()
.Build();
Audit properties not being set:
// Ensure audit is configured and user context is available
services.AddFSEntityFramework<MyDbContext>()
.WithAudit()
.UsingHttpContext() // or other user provider
.Build();
Debugging Tips:
Enable validation in development:
services.AddFSEntityFramework<MyDbContext>()
.ValidateConfiguration() // Will throw helpful errors
.Build();
