Skip to content

Commit 9962ff7

Browse files
Clifftech123Clifftech123
committed
Revise README.md for clarity and structure; update feature descriptions, enhance design goals, and add contributing guidelines to improve user understanding and engagement.
1 parent 9b8c0be commit 9962ff7

1 file changed

Lines changed: 78 additions & 41 deletions

File tree

‎README.md‎

Lines changed: 78 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,53 @@
1+
<div align="center">
2+
13
# EfCoreKit
24

3-
A free, MIT-licensed EF Core extensions library that eliminates boilerplate so you can focus on building features.
5+
**EF Core extensions that eliminate boilerplate — so you can focus on building features.**
6+
7+
[![NuGet](https://img.shields.io/nuget/v/EfCoreKit?logo=nuget&label=NuGet)](https://www.nuget.org/packages/EfCoreKit)
8+
[![NuGet Downloads](https://img.shields.io/nuget/dt/EfCoreKit?logo=nuget&label=Downloads)](https://www.nuget.org/packages/EfCoreKit)
9+
[![Build](https://img.shields.io/github/actions/workflow/status/Clifftech123/EfCoreKit/ci.yml?branch=develop&logo=github&label=Build)](https://github.com/Clifftech123/EfCoreKit/actions)
10+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
11+
12+
**.NET 8 / 9 / 10** · **EF Core 8.x / 9.x / 10.x** · **Works with any EF Core-supported database**
13+
14+
</div>
15+
16+
---
417

5-
## What It Does
18+
## Why EfCoreKit?
619

7-
EfCoreKit plugs into your existing `DbContext` and adds capabilities that most .NET projects need but have to rewrite every time:
20+
Every .NET project with EF Core ends up writing the same plumbing: soft delete filters, audit timestamps, tenant isolation, pagination helpers, bulk imports. EfCoreKit packages all of that into a single `AddEfCoreKit()` call.
821

9-
- **Bulk Operations** — Insert, update, delete, or upsert thousands of records in one fast database call instead of N round trips
10-
- **Soft Delete** — Mark records as deleted instead of removing them, with automatic global query filters so deleted rows are invisible by default
11-
- **Audit Trail** — Auto-stamp `CreatedAt`, `CreatedBy`, `UpdatedAt`, `UpdatedBy` on every save, no manual code required
12-
- **Pagination** — Offset-based and keyset/cursor-based pagination with a built-in `PagedResult<T>` model
13-
- **Query Helpers** — `ExistsAsync`, `GetByIdAsync`, `GetByIdOrThrowAsync`, `WhereIf`, `OrderByDynamic` and more
14-
- **Multi-Tenancy** — Automatic tenant filtering via global query filters so each tenant only sees their own data
15-
- **Specification Pattern** — Reusable, composable query logic encapsulated in strongly-typed specification classes
22+
**Design goals:**
1623

17-
## Supported Databases
24+
- **Zero lock-in** — EfCoreKit uses standard EF Core interceptors and global query filters. Your entities stay plain C# classes, your `DbContext` stays a normal `DbContext`, and you can remove EfCoreKit at any time without rewriting your data layer.
25+
- **Opt-in everything** — Enable only the features you need. Nothing runs unless you turn it on.
26+
- **No custom ORM** — This is not a repository layer or a replacement for EF Core. It's a set of extensions that plug into the pipeline you already use.
1827

19-
| Database | Version |
20-
|------------|---------|
21-
| SQL Server | 2016+ |
22-
| PostgreSQL | 12+ |
23-
| MySQL | 8.0+ |
24-
| SQLite | 3.x |
28+
---
2529

26-
## Supported Platforms
30+
## Features
2731

28-
| Platform | Version |
29-
|----------|---------------|
30-
| .NET | 8.0, 9.0, 10.0 |
31-
| EF Core | 8.x, 9.x, 10.x |
32+
All core features use EF Core interceptors and global query filters — they work with **any database** EF Core supports.
33+
34+
| Feature | Status | Description |
35+
|---------|--------|-------------|
36+
| **Soft Delete** | ✅ | Mark records as deleted with automatic global query filters |
37+
| **Audit Trail** | ✅ | Auto-stamp `CreatedAt`, `CreatedBy`, `UpdatedAt`, `UpdatedBy` on every save |
38+
| **Multi-Tenancy** | ✅ | Automatic tenant filtering so each tenant only sees their own data |
39+
| **Pagination** | ✅ | Offset-based and keyset/cursor-based pagination with `PagedResult<T>` |
40+
| **Query Helpers** | ✅ | `ExistsAsync`, `GetByIdOrThrowAsync`, `WhereIf`, `OrderByDynamic`, and more |
41+
| **Specification Pattern** | ✅ | Reusable, composable query logic in strongly-typed classes |
42+
| **Slow Query Logging** | ✅ | Logs warnings for queries exceeding a configurable threshold |
43+
| **Bulk Operations** | 🚧 | Insert, update, delete, or upsert thousands of rows in one call *(coming soon)* |
44+
45+
---
3246

3347
## Quick Look
3448

3549
```csharp
36-
// Setup
50+
// One-line setup — pick only what you need
3751
builder.Services.AddEfCoreKit<AppDbContext>(
3852
options => options.UseSqlServer(connectionString),
3953
kit => kit
@@ -42,47 +56,58 @@ builder.Services.AddEfCoreKit<AppDbContext>(
4256
.EnableMultiTenancy()
4357
.UseUserProvider<HttpContextUserProvider>()
4458
);
59+
```
4560

46-
// Bulk insert 10,000 rows in one call
47-
await context.BulkInsertAsync(customers);
48-
61+
```csharp
4962
// Query helpers
50-
var exists = await context.Customers.ExistsAsync(x => x.Email == email);
63+
var exists = await context.Customers.ExistsAsync(x => x.Email == email);
5164
var customer = await context.Customers.GetByIdOrThrowAsync(id);
5265

5366
// Pagination
5467
var page = await context.Customers
5568
.Where(c => c.IsActive)
5669
.ToPagedAsync(page: 1, pageSize: 20);
5770

58-
// Conditional filtering
71+
// Conditional filtering + dynamic sort
5972
var results = await context.Orders
6073
.WhereIf(hasStatus, x => x.Status == status)
6174
.OrderByDynamic("CreatedAt", ascending: false)
6275
.ToListAsync();
6376
```
6477

65-
## Packages
78+
### What happens behind the scenes
6679

67-
| Package | Description |
68-
|---------------------------|------------------------------------|
69-
| `EfCoreKit` | Everything — all providers included |
70-
| `EfCoreKit.Abstractions` | Interfaces and models only |
71-
| `EfCoreKit.Core` | Core implementation |
72-
| `EfCoreKit.SqlServer` | SQL Server bulk operations |
73-
| `EfCoreKit.PostgreSql` | PostgreSQL bulk operations |
74-
| `EfCoreKit.MySql` | MySQL bulk operations |
75-
| `EfCoreKit.Sqlite` | SQLite bulk operations |
80+
Once configured, EfCoreKit hooks into EF Core's pipeline automatically:
7681

77-
Install just what you need, or grab the umbrella package:
82+
| You do this | EfCoreKit does this |
83+
|-------------|---------------------|
84+
| Call `SaveChangesAsync()` | Stamps `CreatedAt`/`UpdatedAt`, sets `CreatedBy`/`UpdatedBy` from your user provider |
85+
| Delete an entity | Converts to a soft delete — sets `IsDeleted`, `DeletedAt`, `DeletedBy` instead of removing the row |
86+
| Query any `DbSet` | Automatically filters out soft-deleted rows and scopes to the current tenant |
87+
| Add a new tenant entity | Auto-assigns `TenantId` from your tenant provider |
88+
| Modify a tenant entity you don't own | Throws `TenantMismatchException` before hitting the database |
89+
| Run a slow query | Logs a warning with the SQL and duration so you can catch performance issues early |
90+
91+
---
92+
93+
## Installation
7894

7995
```bash
8096
dotnet add package EfCoreKit
8197
```
8298

99+
Or install only what you need:
100+
101+
| Package | Description |
102+
|---------|-------------|
103+
| `EfCoreKit.Core` | Core implementation (interceptors, filters, extensions) |
104+
| `EfCoreKit.Abstractions` | Interfaces and models only |
105+
106+
---
107+
83108
## Documentation
84109

85-
Each feature has a dedicated guide with full examples, configuration options, and best practices:
110+
Each feature has a dedicated guide with full examples and configuration options:
86111

87112
| Guide | What You'll Learn |
88113
|-------|-------------------|
@@ -94,6 +119,18 @@ Each feature has a dedicated guide with full examples, configuration options, an
94119
| [Query Helpers](docs/query-helpers.md) | WhereIf, OrderByDynamic, specifications, DbSet extensions |
95120
| [Bulk Operations](docs/bulk-operations.md) | BulkInsert/Update/Delete/Upsert, BulkConfig tuning |
96121

122+
---
123+
124+
## Contributing
125+
126+
Contributions are welcome! Check out the [Contributing Guide](CONTRIBUTING.md) to get started.
127+
128+
- [Open an issue](https://github.com/Clifftech123/EfCoreKit/issues) to report a bug or suggest a feature
129+
- [Start a discussion](https://github.com/Clifftech123/EfCoreKit/discussions) for questions or ideas
130+
- [Submit a pull request](https://github.com/Clifftech123/EfCoreKit/pulls) — all PRs target the `develop` branch
131+
132+
---
133+
97134
## License
98135

99-
MIT — free for personal and commercial use, forever.
136+
[MIT](LICENSE) — free for personal and commercial use, forever.

0 commit comments

Comments
 (0)