efcore-patterns by aaronontheweb/dotnet-skills
npx skills add https://github.com/aaronontheweb/dotnet-skills --skill efcore-patterns在以下情况时使用此技能:
配置你的 DbContext 以默认禁用变更跟踪。这提高了读取密集型工作负载的性能。
public class ApplicationDbContext : DbContext
{
public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
: base(options)
{
// 默认禁用变更跟踪以提高只读查询的性能
// 对于需要跟踪变更的查询,请显式使用 .AsTracking()
ChangeTracker.QueryTrackingBehavior = QueryTrackingBehavior.NoTracking;
}
public DbSet<Order> Orders => Set<Order>();
public DbSet<Customer> Customers => Set<Customer>();
}
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
// ✅ 快速读取 - 无跟踪开销
var orders = await dbContext.Orders
.Where(o => o.Status == OrderStatus.Pending)
.ToListAsync();
写入操作需要显式处理:
// ❌ 错误 - 实体未被跟踪,SaveChanges 不执行任何操作
var order = await dbContext.Orders.FirstOrDefaultAsync(o => o.Id == orderId);
order.Status = OrderStatus.Shipped;
await dbContext.SaveChangesAsync(); // 什么都没发生!
// ✅ 正确 - 显式标记实体以进行更新
var order = await dbContext.Orders.FirstOrDefaultAsync(o => o.Id == orderId);
order.Status = OrderStatus.Shipped;
dbContext.Orders.Update(order); // 将整个实体标记为已修改
await dbContext.SaveChangesAsync();
// ✅ 也正确 - 查询时使用 AsTracking()
var order = await dbContext.Orders
.AsTracking()
.FirstOrDefaultAsync(o => o.Id == orderId);
order.Status = OrderStatus.Shipped;
await dbContext.SaveChangesAsync(); // 有效!
| 场景 | 使用跟踪? | 原因 |
|---|---|---|
| 在 UI 中显示数据 | 否 | 只读,无需更新 |
| API GET 端点 | 否 | 返回数据,无变更 |
| 更新单个实体 | 是 或 显式 Update() | 需要保存更改 |
| 具有导航属性的复杂更新 | 是 | 跟踪处理关系 |
| 批量操作 | 否 + ExecuteUpdate | 更高效 |
public class OrderService
{
private readonly ApplicationDbContext _db;
// 创建 - 始终使用 Add(无论跟踪状态如何都有效)
public async Task<Order> CreateOrderAsync(Order order)
{
_db.Orders.Add(order);
await _db.SaveChangesAsync();
return order;
}
// 更新 - 显式标记为已修改
public async Task UpdateOrderStatusAsync(Guid orderId, OrderStatus newStatus)
{
var order = await _db.Orders.FirstOrDefaultAsync(o => o.Id == orderId)
?? throw new NotFoundException($"Order {orderId} not found");
order.Status = newStatus;
order.UpdatedAt = DateTimeOffset.UtcNow;
// 由于 DbContext 默认使用 NoTracking,因此显式标记为已修改
_db.Orders.Update(order);
await _db.SaveChangesAsync();
}
// 删除 - 附加并移除
public async Task DeleteOrderAsync(Guid orderId)
{
var order = new Order { Id = orderId };
_db.Orders.Remove(order);
await _db.SaveChangesAsync();
}
}
关键提示: 始终使用 EF Core CLI 命令来管理迁移。切勿:
Up()/Down() 中的自定义 SQL)# 创建新迁移
dotnet ef migrations add AddCustomerTable \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api
# 使用特定的 DbContext(如果你有多个)
dotnet ef migrations add AddCustomerTable \
--context ApplicationDbContext \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api
# 移除最后一个迁移(如果尚未应用)
dotnet ef migrations remove \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api
# 切勿这样做:
# rm Migrations/20240101_AddCustomerTable.cs # ❌ 错误!
# 应用所有挂起的迁移
dotnet ef database update \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api
# 应用到特定迁移
dotnet ef database update AddCustomerTable \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api
# 回滚到之前的迁移
dotnet ef database update PreviousMigrationName \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api
# 为所有迁移生成 SQL 脚本
dotnet ef migrations script \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api \
--output migrations.sql
# 生成幂等脚本(可安全运行多次)
dotnet ef migrations script \
--idempotent \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api
使用专用迁移服务将迁移执行与主应用程序分离。这确保了:
src/
├── MyApp.AppHost/ # Aspire 编排
├── MyApp.Api/ # 主应用程序
├── MyApp.Infrastructure/ # DbContext 和迁移
└── MyApp.MigrationService/ # 专用迁移运行器
using MyApp.Infrastructure.Data;
using MyApp.MigrationService;
using Microsoft.EntityFrameworkCore;
var builder = Host.CreateApplicationBuilder(args);
// 添加 Aspire 服务默认值
builder.AddServiceDefaults();
// 添加 PostgreSQL DbContext
var connectionString = builder.Configuration.GetConnectionString("appdb")
?? throw new InvalidOperationException("Connection string 'appdb' not found.");
builder.Services.AddDbContext<ApplicationDbContext>(options =>
options.UseNpgsql(connectionString, npgsqlOptions =>
npgsqlOptions.MigrationsAssembly("MyApp.Infrastructure")));
// 添加迁移工作器
builder.Services.AddHostedService<MigrationWorker>();
var host = builder.Build();
host.Run();
public class MigrationWorker : BackgroundService
{
private readonly IServiceProvider _serviceProvider;
private readonly IHostApplicationLifetime _hostApplicationLifetime;
private readonly ILogger<MigrationWorker> _logger;
public MigrationWorker(
IServiceProvider serviceProvider,
IHostApplicationLifetime hostApplicationLifetime,
ILogger<MigrationWorker> logger)
{
_serviceProvider = serviceProvider;
_hostApplicationLifetime = hostApplicationLifetime;
_logger = logger;
}
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
_logger.LogInformation("迁移服务启动中...");
try
{
using var scope = _serviceProvider.CreateScope();
var dbContext = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
await RunMigrationsAsync(dbContext, stoppingToken);
_logger.LogInformation("迁移服务成功完成。");
}
catch (Exception ex)
{
_logger.LogError(ex, "迁移服务失败: {Error}", ex.Message);
throw;
}
finally
{
// 迁移完成后停止应用程序
_hostApplicationLifetime.StopApplication();
}
}
private async Task RunMigrationsAsync(ApplicationDbContext dbContext, CancellationToken ct)
{
// 使用执行策略处理暂时性故障
var strategy = dbContext.Database.CreateExecutionStrategy();
await strategy.ExecuteAsync(async () =>
{
var pendingMigrations = await dbContext.Database.GetPendingMigrationsAsync(ct);
if (pendingMigrations.Any())
{
_logger.LogInformation("正在应用 {Count} 个挂起的迁移...",
pendingMigrations.Count());
await dbContext.Database.MigrateAsync(ct);
_logger.LogInformation("迁移已成功应用。");
}
else
{
_logger.LogInformation("没有挂起的迁移。数据库是最新的。");
}
});
}
}
var builder = DistributedApplication.CreateBuilder(args);
var postgres = builder.AddPostgres("postgres");
var db = postgres.AddDatabase("appdb");
// 迁移首先运行,然后退出
var migrations = builder.AddProject<Projects.MyApp_MigrationService>("migrations")
.WaitFor(db)
.WithReference(db);
// API 等待迁移完成
var api = builder.AddProject<Projects.MyApp_Api>("api")
.WaitForCompletion(migrations) // 关键:等待迁移完成
.WithReference(db);
对于可能暂时失败的操作,始终使用 CreateExecutionStrategy():
public async Task UpdateWithRetryAsync(Guid id, Action<Order> update)
{
var strategy = _dbContext.Database.CreateExecutionStrategy();
await strategy.ExecuteAsync(async () =>
{
var order = await _dbContext.Orders
.AsTracking()
.FirstOrDefaultAsync(o => o.Id == id);
if (order is null) return;
update(order);
await _dbContext.SaveChangesAsync();
});
}
重要提示: 你不能将 CreateExecutionStrategy() 与用户启动的事务一起使用。如果你需要具有重试功能的事务:
var strategy = _dbContext.Database.CreateExecutionStrategy();
await strategy.ExecuteAsync(async () =>
{
// 事务必须在策略回调内部
await using var transaction = await _dbContext.Database.BeginTransactionAsync();
try
{
// ... 你的操作 ...
await _dbContext.SaveChangesAsync();
await transaction.CommitAsync();
}
catch
{
await transaction.RollbackAsync();
throw;
}
});
对于批量操作,使用 EF Core 7+ 的 ExecuteUpdateAsync 和 ExecuteDeleteAsync 而不是加载实体:
// ❌ 慢 - 将所有实体加载到内存中
var expiredOrders = await _db.Orders
.Where(o => o.ExpiresAt < DateTimeOffset.UtcNow)
.ToListAsync();
foreach (var order in expiredOrders)
{
order.Status = OrderStatus.Expired;
}
await _db.SaveChangesAsync();
// ✅ 快 - 单个 SQL UPDATE 语句
await _db.Orders
.Where(o => o.ExpiresAt < DateTimeOffset.UtcNow)
.ExecuteUpdateAsync(setters => setters
.SetProperty(o => o.Status, OrderStatus.Expired)
.SetProperty(o => o.UpdatedAt, DateTimeOffset.UtcNow));
// ✅ 快 - 单个 SQL DELETE 语句
await _db.Orders
.Where(o => o.Status == OrderStatus.Cancelled && o.CreatedAt < cutoffDate)
.ExecuteDeleteAsync();
// ❌ 静默失败 - 实体未被跟踪
var customer = await _db.Customers.FindAsync(id);
customer.Name = "New Name";
await _db.SaveChangesAsync(); // 什么都不做!
// ✅ 显式更新
var customer = await _db.Customers.FindAsync(id);
customer.Name = "New Name";
_db.Customers.Update(customer);
await _db.SaveChangesAsync();
// ❌ N+1 查询 - 每个订单一个查询
var customers = await _db.Customers.ToListAsync();
foreach (var customer in customers)
{
var orders = customer.Orders; // 延迟加载触发查询
}
// ✅ 预先加载 - 单个查询
var customers = await _db.Customers
.Include(c => c.Orders)
.ToListAsync();
// ❌ 跟踪冲突 - 实体被不同上下文跟踪
var order1 = await _db1.Orders.AsTracking().FindAsync(id);
var order2 = await _db2.Orders.AsTracking().FindAsync(id);
order2.Status = OrderStatus.Shipped;
await _db2.SaveChangesAsync(); // 可能抛出异常或行为异常
// ✅ 使用单个上下文或先分离
_db1.Entry(order1).State = EntityState.Detached;
// ❌ 异步上下文中的阻塞调用
var orders = _db.Orders.ToList(); // 阻塞线程
// ✅ 全程异步
var orders = await _db.Orders.ToListAsync();
// ❌ 每次迭代都查询
foreach (var orderId in orderIds)
{
var order = await _db.Orders.FindAsync(orderId);
// 处理订单
}
// ✅ 单个查询
var orders = await _db.Orders
.Where(o => orderIds.Contains(o.Id))
.ToListAsync();
// Scoped = 每个 HTTP 请求一个实例
builder.Services.AddDbContext<ApplicationDbContext>(options =>
options.UseNpgsql(connectionString));
public class MyBackgroundService : BackgroundService
{
private readonly IServiceProvider _serviceProvider;
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
// ✅ 为每个工作单元创建作用域
using var scope = _serviceProvider.CreateScope();
var dbContext = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
// ... 使用 dbContext ...
}
}
public class OrderActor : ReceiveActor
{
private readonly IDbContextFactory<ApplicationDbContext> _dbFactory;
public OrderActor(IDbContextFactory<ApplicationDbContext> dbFactory)
{
_dbFactory = dbFactory;
ReceiveAsync<GetOrder>(async msg =>
{
// 为每个操作创建新的上下文
await using var db = await _dbFactory.CreateDbContextAsync();
var order = await db.Orders.FindAsync(msg.OrderId);
Sender.Tell(order);
});
}
}
// 注册
builder.Services.AddDbContextFactory<ApplicationDbContext>(options =>
options.UseNpgsql(connectionString));
当你通过 Include() 加载多个导航集合时,EF Core 会生成单个查询,这可能导致笛卡尔积爆炸。如果你有 10 个订单,每个订单有 10 个商品,你会得到 100 行而不是 10 + 10。
在你的 DbContext 配置中全局启用查询拆分:
services.AddDbContext<ApplicationDbContext>(options =>
options.UseNpgsql(connectionString, npgsqlOptions =>
{
npgsqlOptions.UseQuerySplittingBehavior(QuerySplittingBehavior.SplitQuery);
}));
当你知道单查询更高效时使用:
// 当你知道结构清晰明了时使用单查询
var orders = await dbContext.Orders
.Include(o => o.Items)
.Include(o => o.Payments)
.AsSingleQuery() // 覆盖全局拆分行为
.ToListAsync();
| 行为 | 优点 | 缺点 |
|---|---|---|
| SplitQuery | 无笛卡尔积爆炸,更适合大型集合 | 多次往返,潜在的一致性问题 |
| SingleQuery | 单次往返,事务一致性 | 多个集合时的笛卡尔积爆炸 |
建议: 默认全局使用 SplitQuery,对于已知单查询更好的特定查询,使用 AsSingleQuery() 覆盖。
// 仅用于简单的单元测试 - 不匹配真实数据库行为
var options = new DbContextOptionsBuilder<ApplicationDbContext>()
.UseInMemoryDatabase(databaseName: Guid.NewGuid().ToString())
.Options;
using var context = new ApplicationDbContext(options);
有关正确的数据库测试,请参阅 testcontainers-integration-tests 技能。
// 在容器中使用真实的 PostgreSQL
var container = new PostgreSqlBuilder()
.WithImage("postgres:16-alpine")
.Build();
await container.StartAsync();
var options = new DbContextOptionsBuilder<ApplicationDbContext>()
.UseNpgsql(container.GetConnectionString())
.Options;
每周安装次数
341
仓库
GitHub 星标数
488
首次出现
2026 年 1 月 28 日
安全审计
安装于
codex293
claude-code280
opencode146
github-copilot139
gemini-cli135
kimi-cli121
Use this skill when:
Configure your DbContext to disable change tracking by default. This improves performance for read-heavy workloads.
public class ApplicationDbContext : DbContext
{
public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
: base(options)
{
// Disable change tracking by default for better performance on read-only queries
// Use .AsTracking() explicitly for queries that need to track changes
ChangeTracker.QueryTrackingBehavior = QueryTrackingBehavior.NoTracking;
}
public DbSet<Order> Orders => Set<Order>();
public DbSet<Customer> Customers => Set<Customer>();
}
Read-only queries work normally:
// ✅ Fast read - no tracking overhead
var orders = await dbContext.Orders
.Where(o => o.Status == OrderStatus.Pending)
.ToListAsync();
Writes require explicit handling:
// ❌ WRONG - Entity not tracked, SaveChanges does nothing
var order = await dbContext.Orders.FirstOrDefaultAsync(o => o.Id == orderId);
order.Status = OrderStatus.Shipped;
await dbContext.SaveChangesAsync(); // Nothing happens!
// ✅ CORRECT - Explicitly mark entity for update
var order = await dbContext.Orders.FirstOrDefaultAsync(o => o.Id == orderId);
order.Status = OrderStatus.Shipped;
dbContext.Orders.Update(order); // Marks entire entity as modified
await dbContext.SaveChangesAsync();
// ✅ ALSO CORRECT - Use AsTracking() for the query
var order = await dbContext.Orders
.AsTracking()
.FirstOrDefaultAsync(o => o.Id == orderId);
order.Status = OrderStatus.Shipped;
await dbContext.SaveChangesAsync(); // Works!
| Scenario | Use Tracking? | Why |
|---|---|---|
| Display data in UI | No | Read-only, no updates |
| API GET endpoints | No | Returning data, no mutations |
| Update single entity | Yes or explicit Update() | Need to save changes |
| Complex update with navigation | Yes | Tracking handles relationships |
| Batch operations | No + ExecuteUpdate | More efficient |
public class OrderService
{
private readonly ApplicationDbContext _db;
// CREATE - Always use Add (works regardless of tracking)
public async Task<Order> CreateOrderAsync(Order order)
{
_db.Orders.Add(order);
await _db.SaveChangesAsync();
return order;
}
// UPDATE - Explicitly mark as modified
public async Task UpdateOrderStatusAsync(Guid orderId, OrderStatus newStatus)
{
var order = await _db.Orders.FirstOrDefaultAsync(o => o.Id == orderId)
?? throw new NotFoundException($"Order {orderId} not found");
order.Status = newStatus;
order.UpdatedAt = DateTimeOffset.UtcNow;
// Explicitly mark as modified since DbContext uses NoTracking by default
_db.Orders.Update(order);
await _db.SaveChangesAsync();
}
// DELETE - Attach and remove
public async Task DeleteOrderAsync(Guid orderId)
{
var order = new Order { Id = orderId };
_db.Orders.Remove(order);
await _db.SaveChangesAsync();
}
}
CRITICAL: Always use EF Core CLI commands to manage migrations. Never:
Up()/Down())# Create a new migration
dotnet ef migrations add AddCustomerTable \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api
# With a specific DbContext (if you have multiple)
dotnet ef migrations add AddCustomerTable \
--context ApplicationDbContext \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api
# Remove the last migration (if not yet applied)
dotnet ef migrations remove \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api
# NEVER do this:
# rm Migrations/20240101_AddCustomerTable.cs # ❌ BAD!
# Apply all pending migrations
dotnet ef database update \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api
# Apply to a specific migration
dotnet ef database update AddCustomerTable \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api
# Rollback to a previous migration
dotnet ef database update PreviousMigrationName \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api
# Generate SQL script for all migrations
dotnet ef migrations script \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api \
--output migrations.sql
# Generate idempotent script (safe to run multiple times)
dotnet ef migrations script \
--idempotent \
--project src/MyApp.Infrastructure \
--startup-project src/MyApp.Api
Separate migration execution from your main application using a dedicated migration service. This ensures:
src/
├── MyApp.AppHost/ # Aspire orchestration
├── MyApp.Api/ # Main application
├── MyApp.Infrastructure/ # DbContext and migrations
└── MyApp.MigrationService/ # Dedicated migration runner
using MyApp.Infrastructure.Data;
using MyApp.MigrationService;
using Microsoft.EntityFrameworkCore;
var builder = Host.CreateApplicationBuilder(args);
// Add Aspire service defaults
builder.AddServiceDefaults();
// Add PostgreSQL DbContext
var connectionString = builder.Configuration.GetConnectionString("appdb")
?? throw new InvalidOperationException("Connection string 'appdb' not found.");
builder.Services.AddDbContext<ApplicationDbContext>(options =>
options.UseNpgsql(connectionString, npgsqlOptions =>
npgsqlOptions.MigrationsAssembly("MyApp.Infrastructure")));
// Add the migration worker
builder.Services.AddHostedService<MigrationWorker>();
var host = builder.Build();
host.Run();
public class MigrationWorker : BackgroundService
{
private readonly IServiceProvider _serviceProvider;
private readonly IHostApplicationLifetime _hostApplicationLifetime;
private readonly ILogger<MigrationWorker> _logger;
public MigrationWorker(
IServiceProvider serviceProvider,
IHostApplicationLifetime hostApplicationLifetime,
ILogger<MigrationWorker> logger)
{
_serviceProvider = serviceProvider;
_hostApplicationLifetime = hostApplicationLifetime;
_logger = logger;
}
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
_logger.LogInformation("Migration service starting...");
try
{
using var scope = _serviceProvider.CreateScope();
var dbContext = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
await RunMigrationsAsync(dbContext, stoppingToken);
_logger.LogInformation("Migration service completed successfully.");
}
catch (Exception ex)
{
_logger.LogError(ex, "Migration service failed: {Error}", ex.Message);
throw;
}
finally
{
// Stop the application after migrations complete
_hostApplicationLifetime.StopApplication();
}
}
private async Task RunMigrationsAsync(ApplicationDbContext dbContext, CancellationToken ct)
{
// Use execution strategy for transient failure handling
var strategy = dbContext.Database.CreateExecutionStrategy();
await strategy.ExecuteAsync(async () =>
{
var pendingMigrations = await dbContext.Database.GetPendingMigrationsAsync(ct);
if (pendingMigrations.Any())
{
_logger.LogInformation("Applying {Count} pending migrations...",
pendingMigrations.Count());
await dbContext.Database.MigrateAsync(ct);
_logger.LogInformation("Migrations applied successfully.");
}
else
{
_logger.LogInformation("No pending migrations. Database is up to date.");
}
});
}
}
var builder = DistributedApplication.CreateBuilder(args);
var postgres = builder.AddPostgres("postgres");
var db = postgres.AddDatabase("appdb");
// Migrations run first, then exit
var migrations = builder.AddProject<Projects.MyApp_MigrationService>("migrations")
.WaitFor(db)
.WithReference(db);
// API waits for migrations to complete
var api = builder.AddProject<Projects.MyApp_Api>("api")
.WaitForCompletion(migrations) // Key: waits for migrations to finish
.WithReference(db);
Always use CreateExecutionStrategy() for operations that might fail transiently:
public async Task UpdateWithRetryAsync(Guid id, Action<Order> update)
{
var strategy = _dbContext.Database.CreateExecutionStrategy();
await strategy.ExecuteAsync(async () =>
{
var order = await _dbContext.Orders
.AsTracking()
.FirstOrDefaultAsync(o => o.Id == id);
if (order is null) return;
update(order);
await _dbContext.SaveChangesAsync();
});
}
Important: You cannot use CreateExecutionStrategy() with user-initiated transactions. If you need transactions with retry:
var strategy = _dbContext.Database.CreateExecutionStrategy();
await strategy.ExecuteAsync(async () =>
{
// Transaction must be INSIDE the strategy callback
await using var transaction = await _dbContext.Database.BeginTransactionAsync();
try
{
// ... your operations ...
await _dbContext.SaveChangesAsync();
await transaction.CommitAsync();
}
catch
{
await transaction.RollbackAsync();
throw;
}
});
For bulk operations, use EF Core 7+ ExecuteUpdateAsync and ExecuteDeleteAsync instead of loading entities:
// ❌ SLOW - Loads all entities into memory
var expiredOrders = await _db.Orders
.Where(o => o.ExpiresAt < DateTimeOffset.UtcNow)
.ToListAsync();
foreach (var order in expiredOrders)
{
order.Status = OrderStatus.Expired;
}
await _db.SaveChangesAsync();
// ✅ FAST - Single SQL UPDATE statement
await _db.Orders
.Where(o => o.ExpiresAt < DateTimeOffset.UtcNow)
.ExecuteUpdateAsync(setters => setters
.SetProperty(o => o.Status, OrderStatus.Expired)
.SetProperty(o => o.UpdatedAt, DateTimeOffset.UtcNow));
// ✅ FAST - Single SQL DELETE statement
await _db.Orders
.Where(o => o.Status == OrderStatus.Cancelled && o.CreatedAt < cutoffDate)
.ExecuteDeleteAsync();
// ❌ Silent failure - entity not tracked
var customer = await _db.Customers.FindAsync(id);
customer.Name = "New Name";
await _db.SaveChangesAsync(); // Does nothing!
// ✅ Explicit update
var customer = await _db.Customers.FindAsync(id);
customer.Name = "New Name";
_db.Customers.Update(customer);
await _db.SaveChangesAsync();
// ❌ N+1 queries - one query per order
var customers = await _db.Customers.ToListAsync();
foreach (var customer in customers)
{
var orders = customer.Orders; // Lazy load triggers query
}
// ✅ Eager loading - single query
var customers = await _db.Customers
.Include(c => c.Orders)
.ToListAsync();
// ❌ Tracking conflict - entity tracked by different context
var order1 = await _db1.Orders.AsTracking().FindAsync(id);
var order2 = await _db2.Orders.AsTracking().FindAsync(id);
order2.Status = OrderStatus.Shipped;
await _db2.SaveChangesAsync(); // May throw or behave unexpectedly
// ✅ Use single context or detach first
_db1.Entry(order1).State = EntityState.Detached;
// ❌ Blocking call in async context
var orders = _db.Orders.ToList(); // Blocks thread
// ✅ Async all the way
var orders = await _db.Orders.ToListAsync();
// ❌ Query per iteration
foreach (var orderId in orderIds)
{
var order = await _db.Orders.FindAsync(orderId);
// process order
}
// ✅ Single query
var orders = await _db.Orders
.Where(o => orderIds.Contains(o.Id))
.ToListAsync();
// Scoped = one instance per HTTP request
builder.Services.AddDbContext<ApplicationDbContext>(options =>
options.UseNpgsql(connectionString));
public class MyBackgroundService : BackgroundService
{
private readonly IServiceProvider _serviceProvider;
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
// ✅ Create scope for each unit of work
using var scope = _serviceProvider.CreateScope();
var dbContext = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
// ... use dbContext ...
}
}
public class OrderActor : ReceiveActor
{
private readonly IDbContextFactory<ApplicationDbContext> _dbFactory;
public OrderActor(IDbContextFactory<ApplicationDbContext> dbFactory)
{
_dbFactory = dbFactory;
ReceiveAsync<GetOrder>(async msg =>
{
// Create fresh context for each operation
await using var db = await _dbFactory.CreateDbContextAsync();
var order = await db.Orders.FindAsync(msg.OrderId);
Sender.Tell(order);
});
}
}
// Registration
builder.Services.AddDbContextFactory<ApplicationDbContext>(options =>
options.UseNpgsql(connectionString));
When you load multiple navigation collections via Include(), EF Core generates a single query that can cause cartesian explosion. If you have 10 orders with 10 items each, you get 100 rows instead of 10 + 10.
Enable query splitting globally in your DbContext configuration:
services.AddDbContext<ApplicationDbContext>(options =>
options.UseNpgsql(connectionString, npgsqlOptions =>
{
npgsqlOptions.UseQuerySplittingBehavior(QuerySplittingBehavior.SplitQuery);
}));
Use single query when you know it's more efficient:
// Use single query when you know the structure is well-understood
var orders = await dbContext.Orders
.Include(o => o.Items)
.Include(o => o.Payments)
.AsSingleQuery() // Override global split behavior
.ToListAsync();
| Behavior | Pros | Cons |
|---|---|---|
| SplitQuery | No cartesian explosion, better for large collections | Multiple round-trips, potential consistency issues |
| SingleQuery | Single round-trip, transactional consistency | Cartesian explosion with multiple collections |
Recommendation : Default to SplitQuery globally, override with AsSingleQuery() for specific queries where single-query is known to be better.
// Only for simple unit tests - doesn't match real database behavior
var options = new DbContextOptionsBuilder<ApplicationDbContext>()
.UseInMemoryDatabase(databaseName: Guid.NewGuid().ToString())
.Options;
using var context = new ApplicationDbContext(options);
See the testcontainers-integration-tests skill for proper database testing.
// Use real PostgreSQL in container
var container = new PostgreSqlBuilder()
.WithImage("postgres:16-alpine")
.Build();
await container.StartAsync();
var options = new DbContextOptionsBuilder<ApplicationDbContext>()
.UseNpgsql(container.GetConnectionString())
.Options;
Weekly Installs
341
Repository
GitHub Stars
488
First Seen
Jan 28, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex293
claude-code280
opencode146
github-copilot139
gemini-cli135
kimi-cli121
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
103,800 周安装