efcore
Data access code with Entity Framework Core 10 on SQL Server or PostgreSQL. Use when code or a review touches DbContext, DbSet, LINQ queries, Include, SaveChanges, ExecuteUpdate, raw SQL through EF, transactions, concurrency tokens, value objects, query filters, interceptors, migrations (dotnet ef, Migrations folder), seed data, or migration deployment in CI. Not for Dapper or plain ADO.NET code, T-SQL or PostgreSQL engine work (indexes, isolation, locks), or EF6 on .NET Framework.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- efcore
- metadata
- { "verified": "2026-10-27", "versions": "EF Core 10.0 (LTS), EFCore.PG 10.0, SQL Server 2025, PostgreSQL 18, .NET 10. EF Core 11 RC 3 in references/ef11.md" }
- description
- Data access code with Entity Framework Core 10 on SQL Server or PostgreSQL. Use when code or a review touches DbContext, DbSet, LINQ queries, Include, SaveChanges, ExecuteUpdate, raw SQL through EF, transactions, concurrency tokens, value objects, query filters, interceptors, migrations (dotnet ef, Migrations folder), seed data, or migration deployment in CI. Not for Dapper or plain ADO.NET code, T-SQL or PostgreSQL engine work (indexes, isolation, locks), or EF6 on .NET Framework.
02 资源文件 17
- 参考文档references/decisions.md19.7 KB
- 参考文档references/ef11.md4.4 KB
- 参考文档references/language.md4.7 KB
- 参考文档references/migrations.md7.6 KB
- 参考文档references/modeling.md10.1 KB
- 参考文档references/provider-postgresql.md7.3 KB
- 参考文档references/provider-sqlserver.md6.0 KB
- 参考文档references/queries.md9.4 KB
- 参考文档references/review-checklist.md6.6 KB
- 参考文档references/sources.md7.9 KB
- 参考文档references/stack-rules.md7.6 KB
- 参考文档references/testing.md4.4 KB
- 参考文档references/writes.md8.8 KB
- 参考文档rules.json19.4 KB
- 脚本scripts/convert.py2.9 KB
- 脚本scripts/doccheck.py28.8 KB
- 脚本scripts/stackcheck.py11.9 KB
03 SKILL.md 正文
EF Core
How to use EF Core well, with any relational provider. Engine rules (T-SQL, indexes, isolation, locks) are in dev-stack:sqlserver and dev-stack:postgresql. Test database setup is in dev-stack:dotnet-testing.
First
- Read
references/stack-rules.md. - Find the EF version: the
Microsoft.EntityFrameworkCore*package in*.csprojorDirectory.Packages.props.- EF Core 10: use this file.
- EF Core 11: use this file and read
references/ef11.md. - EF Core 8 or 9: support ends on 2026-11-10. These rules apply, except the EF 10 APIs: complex type JSON, named query filters,
LeftJoin, and the block lambda inExecuteUpdateAsync. Tell the human about the upgrade. Do not upgrade unless the task asks for it.
- Find the provider:
UseSqlServer,UseAzureSql, orUseNpgsql. Readreferences/provider-sqlserver.mdorreferences/provider-postgresql.md.
Done when you can name the EF version, the provider, and the provider version setting.
Defaults for new code
Ask the human before you apply a default that has no accepted decision (stack rule 4). The full entries are in references/decisions.md.
| Area | Default | ID |
|---|---|---|
| Library | EF Core only. Select projections for reads, SqlQuery<T> for the rare query that LINQ cannot express. |
DATA-02 |
| Context | One DbContext per service. One per module in a modular monolith, with its own schema. | DATA-03, DATA-04 |
| Data access | The DbContext directly in handlers. No generic repository, no IUnitOfWork. |
DATA-05, DATA-06 |
| Keys | Guid keys that the provider generates. Do not set them in code. |
DATA-07 |
| Names | SQL Server: PascalCase. PostgreSQL: snake_case with EFCore.NamingConventions. |
DATA-09 |
| Time | DateTimeOffset (UTC) for instants, DateOnly and TimeOnly, TimeProvider for now. |
DATA-10 |
| Decimals | Properties<decimal>().HavePrecision(18, 4). Money as a complex type when there are two or more currencies. |
DATA-11 |
| Enums | Strings, set in ConfigureConventions. |
DATA-12 |
| Audit | CreatedAt and UpdatedAt from one SaveChangesInterceptor. |
DATA-14 |
| Concurrency | rowversion (SQL Server) or xmin (PostgreSQL) on edited aggregates. |
DATA-15 |
| Migrations | EF migrations. Deploy with a bundle job. No Migrate at startup. |
DATA-17, DATA-18 |
| Bulk | ExecuteUpdateAsync and ExecuteDeleteAsync. SqlBulkCopy or Npgsql COPY for big inserts. |
DATA-22 |
Existing code keeps its style (stack rule 3).
Rules
Context and setup
- Register the context with
AddDbContext(scoped, one per request). UseAddDbContextPoolonly when profiling shows that setup cost matters and the context has no state per request. A pooled context keeps fields such as a tenant ID from the last request. - In background services, singletons, Blazor Server, and parallel work, inject
IDbContextFactory<T>. Create and dispose one context for each unit of work. A singleton that holds a scoped context keeps it alive forever. - Run one operation at a time on a context. Do not use
Task.WhenAllon queries of one context, because EF throws "A second operation started on this context". - Put the model in
IEntityTypeConfiguration<T>classes withApplyConfigurationsFromAssembly. Put type-wide defaults inConfigureConventions. Then a new property gets the correct precision, length, and enum mapping without extra code. - Set the provider version to the real server version. SQL Server 2025:
UseCompatibilityLevel(170). PostgreSQL 18:SetPostgresVersion(18, 0). EF writes SQL for the version that it assumes, and the defaults are older. - Turn on
EnableRetryOnFailurefor cloud and container databases. Then follow rule 20.
services.AddDbContext<AppDbContext>((sp, options) =>
{
options.UseSqlServer(connectionString, sql =>
{
sql.UseCompatibilityLevel(170); // SQL Server 2025: native json type
sql.EnableRetryOnFailure();
});
options.AddInterceptors(sp.GetRequiredService<AuditInterceptor>());
options.EnableSensitiveDataLogging(env.IsDevelopment());
});
Queries
- Project read endpoints to DTOs with
Select. EF reads only the columns that you need, and it tracks nothing. - Add
AsNoTracking()only to read-only queries that return entities. A projection without entities has nothing to track. EF tracks an entity inside a DTO. - Load related data in the same query, with a projection or
Include. Do not read a navigation inside a loop (N+1). Do not turn on lazy loading. - Add
AsSplitQuery()to a query that includes two or more sibling collections. Keep single queries as the default. A split query sends more statements and can read data that changed between them. - Give each paged query a unique, stable order (
OrderBy(...).ThenBy(o => o.Id)). Use keyset paging for deep pages, becauseSkipreads and discards each skipped row. - Compare the bare column:
o.CreatedAt >= start && o.CreatedAt < end, noto.CreatedAt.Year == year. Do not useToLower()for case-insensitive search. Use a collation (see the provider reference). - Use the async methods (
ToListAsync,SingleAsync,SaveChangesAsync) and pass theCancellationToken. Stream large results withAsAsyncEnumerable(). - Use
EF.CompileAsyncQueryonly for a hot query with a fixed shape that runs many times each second. EF already caches the translation of each query shape. - For a
Containswith a large list, writeEF.Parameter(ids).Contains(o.Id). EF 10 sends one parameter for each element by default, and SQL Server allows at most 2100 parameters.
Detail, evidence rules, and examples: references/queries.md.
Writes
- Call
SaveChangesAsyncone time per request or message. It sends all changes in one transaction. - Use
ExecuteUpdateAsyncandExecuteDeleteAsyncfor set-based changes without logic per entity. They run at once and skip the change tracker, concurrency tokens, andSaveChangesinterceptors. Do not change the same rows through tracked entities in the same unit of work. - Put a concurrency token on each aggregate that two users or two messages can change (DATA-15). Catch
DbUpdateConcurrencyExceptionand return 409, or retry the message. - Put a unique index on a unique column and catch the violation. A check before the insert does not stop two inserts at the same time.
- When retries are on, run each explicit transaction inside
CreateExecutionStrategy().ExecuteAsync. Clear the change tracker at the start, because the strategy can run the delegate again. Without the strategy, EF throws. - Keep a transaction short. Do not call an HTTP service or wait for a user inside it.
- When a cache holds the data, save first, then remove the cache key. Do not write the new value into the cache from the write path (
dev-stack:redis).
var strategy = db.Database.CreateExecutionStrategy();
await strategy.ExecuteAsync(async token =>
{
db.ChangeTracker.Clear(); // the delegate can run again: start clean
await using var tx = await db.Database.BeginTransactionAsync(token);
var order = await db.Orders.SingleAsync(o => o.Id == id, token);
order.Status = OrderStatus.Shipped;
await db.SaveChangesAsync(token);
await db.Orders
.Where(o => o.CustomerId == order.CustomerId && o.Status == OrderStatus.Draft)
.ExecuteDeleteAsync(token);
await tx.CommitAsync(token);
}, ct);
Detail on bulk, concurrency, transactions, and cache invalidation: references/writes.md.
Raw SQL
- Use
FromSql,SqlQuery<T>, andExecuteSqlAsyncwith an interpolated string. EF sends each value as a parameter. UseFromSqlRawonly for an identifier that you check against an allow list, and pass the values as{0}parameters.
db.Customers.FromSql($"SELECT * FROM Customers WHERE Email LIKE {"%@" + domain}")
Model
- Map value objects as complex types:
ComplexProperty(o => o.Address)for columns,ComplexProperty(o => o.Details, b => b.ToJson())for a JSON column,ComplexCollection(..., b => b.ToJson())for a list. Owned types are entity types with a hidden key. - Let the provider generate
Guidkeys (sequential on SQL Server, UUIDv7 on EFCore.PG 9+). Do not setId = Guid.NewGuid(). - Store instants as
DateTimeOffsetin UTC. Read the time fromTimeProvider. UseDateOnlyandTimeOnlyfor calendar values. - Register an interceptor one time as a singleton and add that instance. A new instance for each context makes EF build a new internal service provider each time.
- Give each query filter a name (
HasQueryFilter("Tenant", ...)). Then a query can switch off one filter withIgnoreQueryFilters(["SoftDelete"])and keep the tenant filter.
Detail on conventions, converters, interceptors, filters, seed data, and time: references/modeling.md.
Migrations
- Read each generated migration before you commit it. EF writes a column rename as a drop and an add, and that deletes the data.
- Run
dotnet ef migrations has-pending-model-changesin CI. EF 9+ also throws atMigratewhen the model has changes without a migration. - Deploy migrations with a bundle job or an idempotent script (DATA-18). Do not call
Database.Migrateat startup without an accepted decision. Do not callEnsureCreatedoutside tests. - On a merge conflict in the model snapshot, remove your migration, merge, and add your migration again. Do not edit the snapshot by hand.
32a. Some teams deploy with one idempotent script (
migrations script --idempotent). When a PostgreSQL index must not block writes there, keep that one script. Do not useIsCreatedConcurrently(): PostgreSQL rejectsCREATE INDEX CONCURRENTLYin theDOblock of the script (SQLSTATE 25001). Do these three steps:- Add a pre-deploy SQL file that the DBA runs with psql before the script, outside a transaction. It drops an INVALID index with the same name, then runs
CREATE INDEX CONCURRENTLY IF NOT EXISTS. - In the migration, replace the generated
CreateIndexwithmigrationBuilder.Sql("CREATE INDEX IF NOT EXISTS ...")with the same index name. KeepHasIndexin the model, so the snapshot stays correct. - Run the idempotent script after the pre-deploy file, and on a new database. Both runs must end without an error.
- Add a pre-deploy SQL file that the DBA runs with psql before the script, outside a transaction. It drops an INVALID index with the same name, then runs
Detail on teams, CI, bundles, scripts, seed data, and expand-contract: references/migrations.md.
Logging
- Turn on
EnableSensitiveDataLoggingonly in development. It writes parameter values to the log.
Never write
| Wrong | Correct |
|---|---|
FromSqlRaw($"... {name}") or "... " + name |
FromSql($"... {name}") |
FromSqlInterpolated(...) |
FromSql(...) |
options.UseInMemoryDatabase("test") |
Testcontainers with the production engine (dev-stack:dotnet-testing) |
new Mock<DbSet<Order>>() |
A query test against the real engine |
db.Database.EnsureCreated() in app code |
Migrations, deployed by a bundle or a script |
app.Services...Database.Migrate() in Program.cs |
Bundle job (dotnet ef migrations bundle), or a startup call with a reason (DATA-18) |
OwnsOne(o => o.Address), OwnsMany(..., b => b.ToJson()) |
ComplexProperty(o => o.Address), ComplexCollection(..., b => b.ToJson()) |
UseXminAsConcurrencyToken() |
[Timestamp] public uint Version { get; set; } |
public Guid Id { get; set; } = Guid.NewGuid(); |
public Guid Id { get; set; } (the provider generates it) |
Guid.CreateVersion7() for a SQL Server clustered key |
The EF sequential GUID generator (default) |
CreatedAt = DateTime.Now |
CreatedAt = clock.GetUtcNow() |
AppContext.SetSwitch("Npgsql.EnableLegacyTimestampBehavior", true) |
UTC values |
Where(u => u.Email.ToLower() == email.ToLower()) |
A case-insensitive collation, or EF.Functions.ILike on PostgreSQL |
await Task.WhenAll(QueryA(db), QueryB(db)) |
Two awaits, or one context per task from IDbContextFactory<T> |
BeginTransactionAsync() with retries on, outside a strategy |
CreateExecutionStrategy().ExecuteAsync(...) |
Expression.Lambda<...> to build SetPropertyCalls |
Block lambda: ExecuteUpdateAsync(s => { if (x) s.SetProperty(...); }) |
GroupJoin(...).SelectMany(... DefaultIfEmpty()) |
LeftJoin(...) (.NET 10) |
.AsNoTracking().Select(o => new Dto(...)) |
.Select(o => new Dto(...)) |
UseQuerySplittingBehavior(QuerySplittingBehavior.SplitQuery) for all queries |
AsSplitQuery() on the query that needs it |
IRepository<T> over DbSet<T> |
The DbContext directly (DATA-05) |
db.Orders.BulkInsertAsync(rows) |
SqlBulkCopy or Npgsql COPY. The BulkExtensions package has a dual license. |
ToAsyncEnumerable() on an EF query |
AsAsyncEnumerable() |
Package System.Linq.Async on .NET 10 |
Nothing: async LINQ is in the base library |
| "Npgsql 10 generates UUIDv7 keys" | The EF provider EFCore.PG 9+ generates them. Npgsql (ADO.NET) does not. |
Check
-
Build with the analyzers as errors. EF1002 and EF1003 (Raw SQL with interpolation or concatenation) come with the EF package.
dotnet build -warnaserrorPass:
Build succeededwith 0 warnings. -
Check that the model has no changes without a migration:
dotnet ef migrations has-pending-model-changes --project <data project> --startup-project <app project>Pass: exit code 0. Exit code 1 means that a migration is missing.
-
Run the rules of this skill:
python3 <skill folder>/scripts/stackcheck.py --root <repo>Pass: 0 errors. For each warning, fix it or add
// stackcheck: ignore <RULE-ID> <reason>. -
Run the tests with
ConfigureWarnings(w => w.Throw(...))forSqlServerEventId.DecimalTypeDefaultWarningandRelationalEventId.MultipleCollectionIncludeWarning. Pass: all tests green.
Review checklist
The full list is in references/review-checklist.md.
- No interpolation or concatenation in
FromSqlRaw,SqlQueryRaw, orExecuteSqlRaw. tool (EF1002, EF1003, EF-RAW-SQL-INTERP, EF-RAW-SQL-CONCAT) - No InMemory provider and no mocked
DbSet. tool (EF-INMEMORY, EF-PKG-INMEMORY, EF-MOCK-DBSET) - No
EnsureCreatedin app code, no startupMigratewithout a decision. tool (EF-ENSURE-CREATED, EF-STARTUP-MIGRATE) - CI runs
has-pending-model-changes, and each new migration has no drop and add for a rename. tool (pipeline), judge - Each
decimalhas a precision. tool (DecimalTypeDefaultWarningthrows in tests) - A query with two or more sibling collection
Includes usesAsSplitQuery()or a projection. tool (MultipleCollectionIncludeWarning), judge - No navigation access in a loop, no lazy loading. tool (EF-LAZY-PROXIES, EF-PKG-PROXIES), judge
- Async EF calls in async code, with the
CancellationToken. tool (CA1849, CA2016) - No two operations at the same time on one context. Background services use
IDbContextFactory<T>. judge - Read endpoints project to DTOs.
AsNoTrackingonly on entity reads. judge - Paged queries have a unique order. judge
- Edited aggregates have a concurrency token, and the code handles
DbUpdateConcurrencyException. judge - Explicit transactions run inside the execution strategy when retries are on. judge
ExecuteUpdateandExecuteDeletecallers do not need tracked state, tokens, or interceptors. judge- Value objects are complex types. GUID keys come from the provider. tool (EF-OWNED-TYPE, EF-GUID-KEY)
Report
End with the report of stack rule 8 (references/stack-rules.md): the same headings in the same order on each run.
References
references/decisions.md: read before new code needs a DATA decision. It has the question, the options, and the recommendation.references/queries.md: read when you write or review a query (projections, N+1, split queries, paging,Containslists).references/writes.md: read when you writeSaveChanges,ExecuteUpdate, a transaction, a concurrency token, bulk work, or cache invalidation.references/modeling.md: read when you add an entity, a value object, a converter, an interceptor, a query filter, seed data, or a date column.references/migrations.md: read before you add, merge, review, or deploy a migration.references/testing.md: read before you write a test that uses a DbContext.references/provider-sqlserver.md: read when the project usesUseSqlServerorUseAzureSql.references/provider-postgresql.md: read when the project usesUseNpgsql.references/ef11.md: read only when the project uses EF Core 11.references/review-checklist.md: read for a full review.references/sources.md: the primary sources and the credits.references/stack-rules.mdandreferences/language.md: the common rules and the output language.scripts/stackcheck.py: the rule check of this skill.
04 同仓库更多 Skills
web-accessibility
Web accessibility to WCAG 2.2 AA - a checklist for the design, the tool checks (axe-core, the Tab walk, reduced motion), and the manual checks that no tool does (screen reader, zoom, status messages) - with the EAA and EN 301 549 status. Use when a design, mockup, or built feature must be checked for accessibility, when a review must cover keyboard and screen reader use, when the user asks about focus, a focus trap, contrast, or a screen reader on a page, or when the user asks which accessibility rules apply.
ux-states
State inventory for each screen - default, empty, loading, partial, error, success, disabled, overflow, offline, and the business states (no permission, stale data, locked by another user, waiting on an external system, bulk result with failures, read only) - with what the user sees, can do, and how the user recovers. Use when a screen or flow needs its states designed or checked, or when a design shows only the happy path.
ux-setup
Set up a project for UX work - finds the design tools, the design-system source, the brand files, the languages, and the run command, asks the human one round of questions, and writes the "## Design" section of .claude/rules/delivery.md that the ux-design commands and the ux-designer agent read. Moves an older "## Design" section out of CLAUDE.md. Use when /setup, /ux-design, or /ux-review needs the design facts, when the ux-designer agent returns NEEDS_HUMAN because the "## Design" section is missing, or when the user wants to set up or change the design tools of a project.
ux-review
UX review of a built feature against its approved design - Playwright walks each flow and state at 390, 820, and 1440 px, axe-core and the tell checks run on each state, and each heuristic gets a verdict - with findings by owner, severity, and origin, and a verdict in ux-review.md in the work folder of the item. Use when a built feature or screen must be checked against its design, mockups, or prototype, in each state or at each screen size, when built screens need findings by severity, when the build of an item with a UX design is done, or when existing screens need a UX audit.
ux-prototype
Clickable prototype of a designed story in the proto-shell standard, with variants for an A/B test, all states in scope, three sizes, and a test plan with tasks. Use when a design or mockups exist and the team must test the flow or compare variants with users before the build.
ux-practice
The method of the ux-designer agent for the UX design of a story, a feature, or a screen - Double Diamond phases, a design spec with a source for each decision, the UX decision log, evidence tags, severity, and the modes light, full, and new-direction. Preloaded by the ux-designer agent. Use when the ux-designer agent or another UX skill names this method. For the design of an item, a person starts ux-design:ux-design.