Coder Legion - Recent posts tagged efcore

Put the Concurrency Gate Before the Side Effect

Wed, 21 Oct 2026 05:40:24 +0000

Many concurrency bugs begin with code that looks entirely reasonable:

Read the current row.
Check that the operation is still allowed.
Create something durable elsewhere.
Save the original row as complete.

Run once, the workflow is correct. Run twice at almost the same time, and both callers can pass the check before either caller records completion. If step three is irreversible, the system can create duplicate work even though every individual condition was true when evaluated.

The core lesson is simple: when a state transition guards a side effect, make the database choose the winner before the side effect begins.

Why read-then-check is not ownership

An application-level check answers, “What did I observe?” It does not answer, “Do I exclusively own this transition?”

Imagine a parent record representing an open request. Accepting one option creates a downstream record and closes the parent. Two callers can follow this timeline:

Caller A reads the parent as open.
Caller B reads the same parent as open.
Caller A creates a downstream record.
Caller B creates another downstream record.
Both callers try to close the parent.

Optimistic concurrency on the final save may reject one update, but by then the rejected caller may already have created the duplicate side effect. Detecting a conflict after the irreversible action is too late.

Move the decision forward

A stronger shape puts a conditional write immediately before downstream creation. In generalized SQL, the intention is:

UPDATE WorkItems
SET ClaimToken = @token, ClaimedAt = @now
WHERE Id = @id
  AND Status = 'Open'
  AND ClaimToken IS NULL;

The affected-row count becomes the decision:

One affected row means this caller owns the transition.
Zero affected rows means another caller won, or the operation is no longer valid.

That losing result is not exceptional. It is a normal concurrency outcome and should stop before any downstream creation call.

This is stronger than reading again because the predicate and the update are evaluated atomically by the database. There is no application-level gap between “still open” and “now mine.”

The claim is a state, not a boolean trick

Once a claim exists, the domain has an in-progress state whether or not the schema calls it that. Treating it explicitly improves the design.

The workflow needs to answer:

Can a user retry while a claim is fresh?
Which failures can safely release the claim?
When is a claim considered abandoned?
Can another caller take over an abandoned claim?
What happens if the process fails after downstream creation?

A practical rule is to release ownership only when the system knows that no durable side effect exists. If downstream creation fails before producing a record, clearing the claim can make a retry safe. Once a durable result may exist, blindly clearing the claim risks creating another one.

A timeout is recovery policy, not exactly once

A bounded stale-claim timeout prevents an interrupted process from blocking the workflow forever. A new caller may take over only if the stored claim and timestamp still match what it read, so competing recovery attempts cannot both win.

That solves abandoned ownership before the side effect. It does not solve every crash window.

Suppose the downstream service successfully creates a record and the process dies before the parent records completion. After the timeout, replaying the operation could create a second record. The conditional claim narrowed the risk, but it did not create a distributed transaction.

For that boundary, choose an additional mechanism according to the cost of duplication:

Pass a stable idempotency key to the downstream operation.
Record an outbox message in the same transaction as the claim.
Make downstream creation upsert by the originating command identity.
Reconcile incomplete claims against downstream records before replay.

The honest claim is “one winner during concurrent admission,” not “exactly once under every failure.”

Test the overlap, not two sequential calls

A concurrency fix deserves a test that opens the original race window deliberately.

Hold the first caller inside downstream creation. While it is paused, submit the same command again and also submit a competing choice. Then release the first caller.

The useful assertions are concrete:

The downstream creation service was called once.
One winner completed.
Both competing calls received a clear losing result.
The parent stored one selected result.
Other candidates moved to their expected terminal state.

Add two recovery tests as well. First, make downstream creation fail before producing anything and prove that a retry can acquire the released claim. Second, seed a fresh claim and an expired claim, proving that the fresh claim blocks while the expired one can be reclaimed.

This test shape is more valuable than sending two tasks and hoping their timing overlaps. A controlled pause makes the race deterministic and keeps the assertion focused on the contract.

A compact design checklist

Before shipping a command that crosses a data boundary:

Identify the first irreversible side effect.
Put the ownership decision before it.
Use one conditional database write, not a read-then-write promise.
Treat zero affected rows as a normal loser.
Release only when no durable effect exists.
Define stale ownership and takeover semantics.
Add idempotency or reconciliation for the post-side-effect crash window.
Test with a deliberately paused winner and active losers.

The broader principle is not limited to any framework. Checks describe observations. Conditional writes grant ownership. When a workflow can create something you cannot casually undo, that distinction is part of correctness.

Soft Delete Is a Model Contract, Not a Repository Habit

Sat, 17 Oct 2026 05:45:59 +0000

Soft deletion often begins innocently: add an IsDeleted flag, remember to exclude retained rows, and move on. That works until the application grows into several modules, several DbContext types, and configuration spread across assemblies.

At that point, soft deletion is no longer a local query concern. It is a visibility boundary for the complete EF Core model.

The difference is practical. A repository predicate protects the query paths that remember to use it. A model contract protects ordinary reads by default and makes exceptional reads visible in code review.

The dangerous partial success

Imagine a shared base context that scans the entity types it knows and installs a query filter. Later, a module applies another configuration assembly and adds more entities. The base code is correct for the model it saw, but its timing was wrong. Some retained rows are hidden and others are returned normally.

This failure is uncomfortable because both sides look reasonable in isolation. The entity has the deletion marker. The shared context contains filter code. A few tests pass. Yet the effective model has uneven visibility rules.

The lesson is to configure cross-cutting rules at a lifecycle point where the model is complete. An EF Core model-finalising convention can inspect every registered type after the contexts and configuration assemblies have contributed their mappings.

For each root entity carrying the deletion marker, the convention can add the standard predicate. Owned types follow their owner, and derived types inherit the root filter. Existing filters must be preserved: combine with an anonymous filter, or add a separate named filter when the model uses named filters. Any always-visible audit type should be an explicit, narrow exception rather than an accidental omission.

Test the effective predicate

Checking that a filter exists is too weak.

An entity might have an unrelated visibility filter. It might even mention the deletion marker beneath a logical OR:

not deleted OR visible to this user

That expression can still admit a retained row. The required property is stronger: not deleted must be a mandatory conjunct of the effective filter.

A reusable model audit can enumerate all root entity types with the marker, exclude only documented exceptions, and fail if any type lacks that mandatory predicate. It should have tests against itself: prove that it rejects an unrelated filter and rejects the OR case. Otherwise the audit risks becoming a green check that does not guard the boundary it names.

Provider-backed tests add the next layer of evidence. Insert one active row and one retained row. Show that normal queries return only the active row, while an explicit bypass can retrieve both. This verifies the generated query and provider behaviour rather than only evaluating a compiled expression in memory.

A correct filter changes workflows

When global filtering becomes consistent, previously accidental behaviour may break. That is useful information.

Restoration is the clearest example. Suppose a retained row still owns a unique business slot. A normal lookup cannot see it, so a naive create path tries to insert a replacement and collides with the database constraint.

The solution is not to weaken the global filter. Give the restoration path an explicit way to ignore model filters, then make its intention precise:

creating into a slot held by a retained row restores that same row;
editing a different active row into the reserved slot is refused;
failure leaves both rows unchanged;
historical or restoration reads are the only paths allowed to bypass the boundary.

Putting the bypass on a named specification or dedicated query object is easier to review than scattering IgnoreQueryFilters() through services. The name communicates why the exception exists, and focused tests can pin its scope.

Watch required navigations

Global filters also interact with relationship shape. If a required navigation uses an inner join and the principal is filtered out, the dependent can disappear from a query even when the dependent itself is active.

That may be correct, but it should be a decision.

An inventory of required relationships that cross filtered and unfiltered types gives reviewers a bounded list of hazards. For each one, choose deliberately: align filters on both sides, make the navigation optional, change the query shape, or accept and test the disappearance.

This is one reason metadata-driven verification scales better than a long list of hand-written repository tests. The model can tell you what exists now, including a new entity or relationship added by a future module.

A practical verification stack

A durable soft-delete boundary has four layers:

Apply the convention after the model is complete.
Audit every soft-deletable root for the exact mandatory predicate.
Keep bypasses explicit and limited to restoration or historical use.
Run real-provider tests for visibility, restoration, uniqueness, and required-navigation behaviour.

There is a cost: more model infrastructure, a deliberate exception list, and tests that can expose old assumptions. Some teams may decide that hard deletion or temporal tables better match particular data. The point is not that soft deletion is always right.

The point is that, once chosen, it must behave like one coherent contract.

The most valuable outcome is not the filter itself. It is that a future entity cannot quietly arrive outside the boundary—and that exceptional access reads like an exception.

When the Tool Cannot See the Whole Model

Sun, 11 Oct 2026 06:55:17 +0000

Modular architecture creates an uncomfortable class of failure: the application can understand its complete model while design-time tooling sees only a legitimate subset.

That difference is easy to misread as drift. It is also dangerous to dismiss. The useful engineering move is to identify exactly what the tool cannot observe, then relocate each safety check to a boundary with enough context to answer the question correctly.

The warning was real, but its conclusion was wrong

Consider a shared EF Core context that can be extended by optional runtime modules. Each module contributes mappings without forcing the lower-level persistence package to reference every higher-level feature package. That dependency direction is valuable: the shared module remains reusable, and optional features remain optional.

At runtime, the host loads the contributing modules and the complete model is assembled. At design time, the tooling process starts from a narrower package. Loading one contributor directly would create a dependency cycle, so that contributor is absent.

The migration snapshot still represents the complete model. The design-time model does not. A comparison therefore reports a difference and may propose removing an object that is not obsolete at all; it is merely invisible from that process.

The warning accurately says, “these two views differ.” It cannot establish why they differ.

Separate database update from migration authoring

The first mistake would be treating every operation as though it asks the same question.

A database update applies migrations that have already passed review and validation. If a known model subset causes a framework warning to block that operation, a narrowly scoped suppression can be reasonable. The important word is narrowly. The exception belongs in the design-time path that has the structural blind spot, with an explanation of why the complete model cannot be assembled there.

Migration authoring is different. A scaffolder turns its limited view into proposed schema changes. If it cannot see an extension-owned table, a removal operation may look perfectly logical. Suppressing a warning does nothing to make that proposal safe.

So the second boundary needs a stronger invariant: inspect the generated migration operations and fail if they remove, rename, or destructively alter protected extension data. That converts a warning in prose into an executable gate.

This distinction matters. “Allow the known update path” and “trust every future generated migration” are not the same decision.

Keep a complete-model drift check

Once a noisy comparison is suppressed, the obvious risk is hiding real drift. The answer is not to pretend the partial view became authoritative. Keep a separate test that runs in a host where all contributors are loaded, builds the complete runtime model, and compares that model with the snapshot.

Now each check has one clear responsibility:

the design-time update path tolerates the known subset;
the full-model test detects genuine model-to-snapshot drift;
the migration-operation test blocks destructive scaffolding.

This is more precise than relying on one framework signal for three different questions.

Prove the guard is not vacuously green

Negative tests deserve a positive control.

Imagine a test that scans every migration and asserts that none removes a protected table. It passes. Good news, perhaps. But it also passes if migration discovery silently returns an empty collection.

Add a companion assertion that the scan finds the migration that originally created the protected object. If discovery breaks, the positive control fails. The pair proves both that the dangerous operation is absent and that the evidence set is present.

This pattern generalizes beyond migrations. Any test that says “no forbidden item exists” should make you ask whether it would still pass when the scanner found nothing.

Shared process state is another hidden boundary

The same change exposed a smaller reliability lesson. Tests for design-time factories temporarily set a process-wide configuration value. Separate test classes ran concurrently, and one could restore the value while another was still using it. Each class passed alone; together they failed intermittently.

The repair was not another retry. The tests were placed in one non-parallel collection because they share mutable process state.

That is the same ownership principle in miniature: the scope of the resource determines the scope of coordination. A process-wide variable cannot safely be treated as test-local state.

The trade-off is explicit complexity

This approach is not free. There is now a documented exception, a complete-model drift test, a migration-operation guard, a positive control, and serialized tests around shared environment state. Future maintainers must understand why those pieces exist.

But the alternative is false simplicity: a generic warning that blocks legitimate work, generated operations that can target valid data, and flaky tests that disguise the real contract.

The practical rule I keep is this:

When tooling has a structural blind spot, narrow the exception and move safety to executable checks that can observe the complete truth.

Do not silence evidence broadly. Do not force an architectural dependency merely to satisfy a tool. Give each check the context it needs, and make dangerous assumptions fail before they become database changes.

A Row Version Is a Cross-Layer Contract

Sat, 03 Oct 2026 06:24:18 +0000

A concurrency column can exist in the database and still be wrong.

The name may match. The migration may have run. Inserts may appear healthy. Yet optimistic concurrency can still be weaker than the application assumes because the runtime model, the physical schema, and the test environment disagree about what that column means.

The lesson is broader than one ORM feature: database-generated values are cross-layer contracts. Treating them as a property of only the entity class or only the table leaves a gap exactly where correctness matters.

What the contract actually contains

For a database-generated row version, at least five facts need to agree:

the physical type has true row-version semantics;
the value is non-nullable;
the database generates it on insert and update;
the ORM marks it as a concurrency token;
existing values remain intact during alignment or deployment.

A binary column of the expected length is not automatically equivalent. A nullable token changes the invariant. A model that knows about concurrency but not database generation can try to write a value the database owns. Conversely, a correctly generated database column provides little application protection if the runtime model never includes it in optimistic-concurrency checks.

The useful mental model is not “there is a column.” It is “every layer agrees who owns this value and how a stale write is detected.”

Prefer verification over destructive repair

Suppose the shipped database already has the correct non-null generated token, but the current EF Core model describes it incompletely. A tempting fix is to alter or recreate the column until the migration history looks tidy.

That can be the riskiest part of the change. Replacing a generated token can touch every row, invalidate values held by active writers, or disguise an unexpected schema. The safer move is often smaller:

align the runtime mapping with the physical contract;
add a forward-only migration that asserts the exact expected shape;
refuse to proceed when the real schema differs.

This kind of assertion migration changes no business data. It asks the database whether the table, column, type, length, nullability, and generation semantics match the known contract. Running it twice should be safe. Encountering a missing, nullable, or look-alike column should fail clearly.

Failing a rollout is inconvenient. Quietly weakening stale-write protection is worse. A fail-closed migration turns unknown drift into an explicit operational decision instead of an accidental data-integrity change.

Test at three different levels

No single test provider can prove the whole contract efficiently. A layered suite gives each test one honest job.

1. Model metadata

A cheap unit test can inspect EF Core metadata. It should verify that the property is required, marked as a concurrency token, and generated on add or update. This catches accidental mapping changes quickly, without starting a database.

Metadata tests do not prove the database behaves that way. They prove the application describes its expectation correctly.

2. Lightweight application flows

In-memory providers are useful for service and orchestration tests, but they do not automatically behave like a relational engine with generated row versions. Once a token becomes required, fixtures may fail because no value is produced.

A narrowly scoped, test-only save interceptor can generate a fresh fixed-length token for inserted or modified entities. That keeps fast tests representative of the required-value lifecycle. It should be described honestly as an emulator, not provider parity.

The emulator proves that application code can carry changing tokens through its flows. It cannot prove the SQL type, migration assertion, or actual stale-write mechanics.

3. A focused real-database proof

The decisive test uses the real provider. Create the shipped shape, insert a synthetic row, and retain its generated token. Apply the alignment migration—ideally twice—and verify that both the row and original token survive.

Then load the same row through two contexts. Save through the first and confirm its token changes. Attempt to save the stale copy through the second. The expected concurrency exception is the behavioural proof that the contract works end to end.

Negative cases matter too. A missing table, missing column, nullable token, or ordinary binary column should be refused. These cases prevent a permissive assertion from becoming ceremonial.

Put the expensive proof on the required path

A real-database test that developers can skip forever is documentation, not a gate. Register the small provider-faithful suite in the required CI job and include the relevant file scopes in change detection.

This does not mean every application test should use a full database. That would make feedback slower and fixtures harder to maintain. The trade-off is deliberate separation:

metadata tests are cheap and broad;
in-memory tests exercise application flows;
real-database tests prove database-owned behaviour.

The suite costs more than one happy-path unit test. In return, failures become easier to interpret because each layer states what it can and cannot guarantee.

A practical review checklist

When reviewing a database-generated concurrency token, ask:

Does the runtime model match the shipped type, nullability, and generation rules?
Does the migration preserve rows and existing token values?
Does unexpected schema fail closed?
Do fast fixtures represent the required token lifecycle without claiming provider equivalence?
Does a real-provider test prove token change and stale-write rejection?
Is that proof part of required CI?

The broader engineering habit is simple: when a value is owned by the database, verify the contract where each promise is made. Model tests describe intent. Fast tests protect application flow. Only the real provider can prove the final integrity boundary.

When EF Core's Design-Time Model Is Supposed to Be Incomplete

Sat, 26 Sep 2026 06:02:03 +0000

Framework warnings are useful because they compress hard-earned experience into an early signal. But a signal is not an invariant. In an extensible EF Core architecture, design-time tooling can legitimately see less of the model than the running application. If that difference is intentional, treating every pending-model warning as real drift can block a safe database update—or encourage a destructive migration.

The answer is not to ignore the warning casually. It is to understand exactly why it is false, then replace the lost signal with checks that understand the real architecture.

How a Valid Model Becomes Invisible

Consider a modular .NET application with a DbContext owned by a foundational module. Higher-level modules can contribute entity configurations through runtime discovery. This keeps the dependency direction clean: the foundational data module does not need references back to every feature that extends it.

At runtime, the host loads the feature assemblies and the DbContext receives the complete set of configurations. At design time, the EF Core tooling starts from the foundational project. Loading a higher-level contributor from there would create a circular dependency, so the design-time process builds a smaller model.

The migration snapshot still represents the complete model. The design-time differ compares that snapshot with its partial view and concludes that the contributed entity has disappeared. A probe migration may therefore contain a drop operation for a table that remains valid and necessary at runtime.

The tool is behaving consistently with the inputs it can see. The architectural context is what it lacks.

Prove the False Positive Before Suppressing It

Before changing warning behaviour, reduce the difference to something explainable.

Generate a disposable probe migration and inspect every operation. If the only reported difference is the known extension entity that design time cannot load, you have evidence for a visibility gap. If the probe also changes columns, indexes, relationships, or unrelated tables, stop: that may be genuine drift.

Then verify the full model independently. Run a snapshot comparison in a test process where all contributing assemblies are loaded. That test should compare the migration snapshot against the same model the application actually builds.

Only after both checks agree should the design-time factory suppress the specific pending-model warning. The suppression belongs at the narrow boundary where the false positive occurs, not in a broad configuration that hides the warning for unrelated contexts.

This is an important distinction: the warning is disabled because a stronger source of truth exists, not because the warning is inconvenient.

Turn the Destructive Failure Mode Into a Build Failure

Even after database update is unblocked, migration scaffolding may still use the incomplete design-time model. A future developer can generate a migration and receive a plausible-looking drop operation.

Comments and runbooks help, but they do not stop a merge. An executable guard can.

Inspect every migration's operations and fail if a protected extension table is dropped, renamed, or destructively altered. Cover structured operations such as table drops and column drops, but also inspect raw SQL for equivalent destructive statements. The goal is not a general SQL parser. It is a focused tripwire for the known architectural blind spot.

Add a positive control as well. The suite should prove that migration discovery found the migration which creates the protected table. Without that check, a broken scanner could inspect zero migrations and report a reassuring green result. A rejection-only test cannot distinguish “nothing is wrong” from “nothing ran.”

That small positive assertion dramatically improves the credibility of the safety test.

Keep the Test Harness Honest

Design-time factory tests often need temporary configuration, such as a process-wide environment variable containing a connection string. Two test classes that mutate the same variable can race: one restores the original value while the other is still constructing its context.

That creates a flaky failure which disappears when either class runs alone.

Treat process-wide configuration as shared mutable state. Put those tests in one serialized collection, restore the previous value in a finally block, and make it explicit that the connection value is only used to construct options when no database call is required.

This detail is adjacent to the model problem, but it matters. A safety test that flakes trains people to distrust or bypass it.

The Trade-Off Is Custom Safety Work

This approach is not free. The team must maintain a full-model snapshot test, a focused migration-operation guard, a positive control, serialized environment-sensitive tests, and documentation explaining which CLI signal is intentionally unreliable for this context.

The alternative is worse: reverse the dependency direction, abandon modular extension points, block legitimate database updates, or risk committing a destructive migration produced by a partial model.

The general rule is simple:

Identify why the generic check is wrong.
Prove the exact boundary of the false positive.
Suppress only at that boundary.
Replace the lost signal with a stronger invariant.
Add a positive control so the invariant cannot pass vacuously.

Framework defaults are valuable, but architecture-specific evidence is stronger. When design time and runtime intentionally see different worlds, make that difference explicit—and make the dangerous interpretation impossible to merge unnoticed.

When EF Core Sees Only Part of Your Model

Sat, 19 Sep 2026 12:18:35 +0000

Framework warnings are valuable because they turn hidden risk into visible friction. But a warning is still an interpretation of the evidence available to the tool. In a modular application, the command-line process may not load the same assemblies as the running application. When that happens, the design-time model can be a projection rather than the whole truth.

That creates an uncomfortable situation: a migration warning may be both technically correct about the model it sees and dangerously wrong about the database operation it proposes.

The answer is not to ignore warnings casually. It is to identify the boundary, narrow the exception, and replace the lost signal with a stronger executable invariant.

The model can change with the process

Consider a lower-level persistence module that owns a database context. At runtime, higher-level modules can contribute entity configurations through a discovery mechanism. This preserves the dependency direction: the lower-level module does not need references back to every feature that extends it.

Now run command-line migration tooling from the lower-level project. The higher-level contributor may not be loaded, because adding that reference would create a project cycle. The tool builds a valid model, but it is only the portion visible from that process.

The migration snapshot, meanwhile, includes the contributed table. It was created from the full application model and must remain there for every host that uses the shared schema.

The differ compares those two views and concludes that the table exists in the snapshot but not in the current model. Its proposed fix is logical from that narrow perspective: drop the table.

From the system’s perspective, that operation is destructive.

Regenerating the snapshot until the warning disappears is tempting. It is also exactly the wrong response when the design-time model is incomplete by construction.

The first diagnostic question should be: what is the entire proposed difference? A probe migration can make the answer concrete. If the only change is removal of a table supplied by a module that the tooling process cannot load, the warning describes a visibility gap—not necessarily real drift.

This distinction matters. “The warning is a false positive” is too broad. A particular warning, for a particular context, under a documented loading boundary may be a false positive. Other differences could still be real.

The safe decision is therefore narrow: allow the legitimate database-update path to proceed despite that one known condition, while keeping a separate full-model comparison as the authoritative drift test.

Suppression spends a safety signal

Ignoring a warning removes friction. It does not remove the underlying ambiguity.

If a design-time factory suppresses a known pending-model warning, the team has spent a safety signal. That signal should be replaced with evidence closer to the failure mode.

In this case, the feared outcome is not an abstract “model mismatch.” It is a migration that drops, renames, or damages a table the design-time process cannot see. That can be tested directly.

An executable migration guard can inspect the operations produced by every committed migration and fail when it finds:

a drop of the protected table;
a rename that moves it out of the contract;
a column removal targeting that table; or
raw SQL containing the destructive operation.

This is more specific than the original warning, and that specificity is a strength. The test says exactly which invariant must survive.

Negative guards need positive controls

There is a subtle testing trap here. A test that scans migrations and finds no forbidden operation can pass because the migrations are safe—or because discovery found nothing.

That is a vacuous pass.

Add a positive control that proves the scan sees the migration that originally created the protected table. Now the pair of tests establishes both halves of the claim:

the evidence set is present; and
none of that evidence violates the destructive-operation invariant.

This pattern generalizes well. Whenever a test says “nothing bad exists,” pair it with proof that the search space is populated. It is useful for dependency scans, authorization maps, route inventories, migration checks, and reflection-based conventions.

Keep the full model as the authority

The migration guard protects one known destructive edge. It does not prove that every legitimate model change has a migration.

For that, retain a snapshot comparison that runs in a process where all runtime contributors are loaded. That test compares the snapshot with the full model rather than the design-time projection.

These checks have different jobs:

the full-model comparison detects real snapshot drift;
the migration guard blocks the known destructive artifact;
the positive control proves the guard actually inspected meaningful input; and
the narrowly scoped suppression keeps the operational update path usable.

Together, they are stronger than treating one framework warning as universally authoritative.

The trade-off is deliberate maintenance

This approach is not free. The guard knows about a specific architectural boundary. If extension mechanics change, the tests and documentation must change with them. Contributors need to understand why the suppression exists and why generated migration output still requires review.

The alternative is worse: either block legitimate operations forever, or normalize a habit of dismissing warnings and accepting generated drops.

The practical review rule is simple: when tooling sees only a projection, document the blind spot, scope the exception, and encode the real safety property as a failing test. Framework diagnostics are excellent inputs. Your architecture still owns the final claim.

Your Reader Cannot Be Stricter Than Your Schema

Thu, 17 Sep 2026 08:20:48 +0000

SingleOrDefault looks like a small query choice. In practice, it is an assertion about your data model: for this predicate, zero or one row may exist.

That assertion is valuable when storage enforces the same rule. When the database permits duplicates, however, the reader is relying on an invariant that does not exist. One unexpected row can turn an ordinary lookup into an exception before validation, authorization, or other normal handling begins.

I recently reviewed a committed recovery for exactly that class of mismatch. The useful lesson was not the specific lookup. It was how to contain the exception without pretending the data had become correct.

A query can encode a hidden contract

Consider a generalized account table:

Rows permitted by storage: 0..many per normalized key
Rows expected by reader:    0..1 per normalized key

The read path might be perfectly reasonable in isolation:

var record = await records.SingleOrDefaultAsync(x => x.LookupKey == key);

But the method name does not create uniqueness. It only checks cardinality at read time. If two rows match, the query throws.

This is why I now treat Single and SingleOrDefault as executable invariant assertions. During review, I ask: what proves the invariant? A unique index? A constrained aggregate? A transactionally protected write path? Or only an earlier existence check that can race?

Containment is not repair

When duplicate data already exists, immediately adding a unique index may be unsafe. Migration can fail on the existing rows. Previously accepted imports or registrations may begin failing without a useful remediation path.

At the same time, leaving a critical read path to throw can make a narrow data defect disproportionately disruptive.

A staged response separates two goals:

Containment: provide a deterministic, non-crashing resolution path while preserving security and making the defect visible.
Correction: repair the existing data and enforce the intended rule for future writes.

The distinction matters. A tolerant reader is a recovery mechanism, not evidence that duplicates are acceptable.

Properties of a safe recovery path

A useful containment pattern keeps the normal case boring:

try
{
    return await ReadExpectedSingleAsync(key);
}
catch (InvalidOperationException)
{
    var matches = await ReadBoundedCandidatesAsync(key);
    if (matches.Count < 2)
        throw;

    ReportCollision(matches.Select(x => x.OpaqueId));
    return ChooseDeterministically(matches);
}

This sketch is intentionally incomplete, but it highlights several important properties.

Keep the fast path unchanged

Most lookups are not ambiguous. Do not make every request pay for a corruption-recovery query. Invoke the fallback only after the expected lookup demonstrates the precise failure you are prepared to handle.

Prove ambiguity before handling it

InvalidOperationException can come from many places. Catching it and returning “not found” would turn an unrelated store failure into a silent wrong answer. Re-query narrowly; if there are not actually multiple matches, rethrow the original fault.

Choose deterministically

Never accept database enumeration order as a resolution policy. Define explicit ranking from legitimate domain facts, then add a stable final tie-break. The same data must produce the same candidate on every attempt.

Determinism does not make the selected record correct. It prevents the recovery itself from becoming random.

Preserve downstream verification

Resolving one candidate must not grant access, approve a transaction, or bypass an eligibility rule. Credential checks, authorization, state validation, and other security decisions still run after resolution. Containment should make the lookup deterministic, not weaken the boundaries that follow it. A legitimate candidate may still lose the ranking, so some affected operations can remain unavailable until the data is repaired.

Bound and observe the fallback

A pathological key should not cause an unbounded scan during a critical request. Cap diagnostic reads, raise a high-signal operational event, and log only what responders need. Opaque record identifiers may support repair; the sensitive lookup value often does not belong in logs.

The stronger end state lives in storage

After containment, the work is not finished. The durable sequence is usually:

inventory collisions
-> decide merge or deletion policy
-> repair existing rows
-> reject or reconcile conflicting writes
-> add the storage constraint
-> remove or narrow temporary recovery code

For relational data, that often means a unique index aligned with the normalization and null semantics used by the application. The write path should return a useful domain result when the constraint rejects a conflict. A pre-insert lookup can improve the message, but the database remains the concurrency-safe authority.

There is a real trade-off. Immediate enforcement gives the cleanest future guarantee but can break deployment against historical data. Temporary tolerance contains the exception but adds policy, cannot guarantee later verification will succeed, and can become permanent by neglect. Treat it as migration work with an owner, telemetry, and an exit condition.

Test the invariant and the escape hatch

Focused tests should cover more than “duplicates do not throw.” I would pin:

the ordinary single-row path remains untouched;
selection is stable when candidates arrive in different orders;
inactive or retired records cannot outrank valid ones;
unrelated exceptions escape unchanged;
downstream verification still decides the outcome;
diagnostics contain repairable identifiers but no sensitive key;
the candidate read is bounded;
the future uniqueness constraint rejects a conflicting concurrent write.

The deeper lesson is architectural: reads, writes, and storage must agree on cardinality. If a reader says “exactly one,” make that promise explicit at the boundary able to enforce it. Until then, the code is not reading an invariant. It is discovering, at runtime, whether the hope was true.

Getting Started with GraphQL in ASP.NET

Tue, 04 Aug 2026 08:44:29 +0000

Getting Started with GraphQL in ASP.NET and EF Core

GraphQL is a modern API technology that allows clients to request exactly the data they need. Unlike traditional REST APIs, GraphQL uses a single endpoint and gives consumers more control over the response structure.

If you're building ASP.NET applications with Entity Framework Core, adding GraphQL can be a great way to expose your data efficiently.

Why GraphQL?

With REST APIs, clients often receive more data than they need or must call multiple endpoints to collect related information.

GraphQL helps solve these problems by providing:

Flexible data retrieval
Fewer API requests
Strongly typed schemas
Better performance for complex data scenarios

Create a New ASP.NET Project

Start by creating a Web API project:

dotnet new webapi -n GraphQLDemo
cd GraphQLDemo

Install the required packages:

dotnet add package HotChocolate.AspNetCore
dotnet add package HotChocolate.Data.EntityFramework
dotnet add package Microsoft.EntityFrameworkCore.InMemory

Create the Entity

Let's create a simple Product model:

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
}

Configure EF Core

Create a DbContext:

using Microsoft.EntityFrameworkCore;

public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options)
        : base(options)
    {
    }

    public DbSet<Product> Products => Set<Product>();
}

Create a GraphQL Query

GraphQL queries define the data clients can request.

public class Query
{
    public IQueryable<Product> GetProducts(
        [Service] AppDbContext context)
    {
        return context.Products;
    }
}

Returning IQueryable allows Hot Chocolate to optimize filtering, sorting, and projections.

In Program.cs:

using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseInMemoryDatabase("ProductsDb"));

builder.Services
    .AddGraphQLServer()
    .AddQueryType<Query>();

var app = builder.Build();

using (var scope = app.Services.CreateScope())
{
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();

    db.Products.AddRange(
        new Product { Id = 1, Name = "Laptop", Price = 999.99m },
        new Product { Id = 2, Name = "Mouse", Price = 29.99m }
    );

    db.SaveChanges();
}

app.MapGraphQL();

app.Run();

Run Your First Query

Navigate to:

https://localhost:5001/graphql

Execute:

query {
  products {
    id
    name
    price
  }
}

Response:

{
  "data": {
    "products": [
      {
        "id": 1,
        "name": "Laptop",
        "price": 999.99
      },
      {
        "id": 2,
        "name": "Mouse",
        "price": 29.99
      }
    ]
  }
}

Enable Filtering and Sorting

One of the best features of Hot Chocolate is built-in filtering and sorting.

Update the query:

using HotChocolate.Data;

public class Query
{
    [UseFiltering]
    [UseSorting]
    public IQueryable<Product> GetProducts(
        [Service] AppDbContext context)
    {
        return context.Products;
    }
}

builder.Services
    .AddGraphQLServer()
    .AddQueryType<Query>()
    .AddFiltering()
    .AddSorting();

Now clients can run queries like:

query {
  products(
    where: { price: { gt: 100 } }
    order: { price: DESC }
  ) {
    name
    price
  }
}

Conclusion

GraphQL and EF Core work very well together in ASP.NET applications. With Hot Chocolate, you can expose database entities through GraphQL with minimal configuration while gaining powerful features like filtering, sorting, and projections.

If you're already using EF Core, adding GraphQL is an easy way to make your APIs more flexible and developer-friendly. Start with simple queries, then move on to mutations, authentication, and real database providers like SQL Server or PostgreSQL.

Happy coding! 🚀

References

GraphQL Official Documentation, Learn GraphQL

https://graphql.org/learn/

GraphQL Official Documentation, Queries

https://graphql.org/learn/queries/

Hot Chocolate Documentation, Getting Started with GraphQL in .NET

https://chillicream.com/docs/hotchocolate/get-started-with-graphql-in-net-core

Hot Chocolate Documentation, GraphQL Server for .NET
https://chillicream.com/docs/hotchocolate

EF Core Mapping for DDD — for Dummies

Mon, 13 Jul 2026 19:04:55 +0000

You built a nice domain model with rules and private properties — but EF Core wants simple classes with public get; set;.

Don't worry. This guide shows you how to save DDD models to the database without messing up your code. Short sentences. Real examples. No jargon overload.

Before you start: know basic C# and what EF Core is. DDD just means putting business rules inside your C# classes instead of scattering them everywhere.

1 · What's the Problem?

DDD (Domain-Driven Design) is a fancy name for a simple idea: put your business rules inside your C# classes.

For example, "you can't ship an empty order" should live on the Order class — not in some random service file.

EF Core is the tool that saves your C# objects to SQL Server. It works great with simple classes that have public { get; set; } on everything.

But DDD classes are different — they use:

private set
factory methods like Order.Create()
hidden lists

That's where mapping comes in: a separate config file that tells EF Core "here's how to read and write my class" — without changing the class itself.

Bad model vs good model

The bad one is easy for EF Core but anyone can break the rules. The good one protects itself — EF Core just needs a little help to save it.

// ❌ BAD — no rules, anyone can change anything
public class Order
{
    public Guid Id { get; set; }
    public string Status { get; set; } = "";
    public List<OrderLine> Lines { get; set; } = [];
    // Someone can write: order.Status = "Shipped" on an empty order. Oops.
}

// ✅ GOOD — rules live here, properties are protected
public sealed class Order
{
    public OrderId Id { get; private set; }
    public OrderStatus Status { get; private set; }
    private readonly List<OrderLine> _lines = [];
    public IReadOnlyCollection<OrderLine> Lines => _lines.AsReadOnly();

    private Order() { } // EF Core needs this empty constructor — you never call it

    public static Order Create(CustomerId customerId) { /* ... */ }
    public void AddLine(ProductId productId, int qty, Money price) { /* checks rules */ }
    public void Place() { /* checks rules before shipping */ }
}

Keep database stuff out of your business code

Your Domain project (business rules) should never mention EF Core or SQL Server.

All the "how to save to the database" code goes in a separate Infrastructure project.

Think of it like this: your business code shouldn't know a database exists.

// Domain/Billing.Domain.csproj
//   → NO EntityFrameworkCore package. Just plain C#.

// Infrastructure/Billing.Infrastructure.csproj
//   → Has EF Core. References Domain. Contains mapping files.

// Example mapping file:
// Infrastructure/Persistence/Configurations/OrderConfiguration.cs

💡 Think of it like a translator. Your C# class speaks "business rules." The database speaks "tables and columns." The mapping file is the translator — and it lives in Infrastructure, not in your business code.

2 · Where Does the Code Go?

Split your solution into folders (projects):

Project	What goes here
Domain	Business classes — NO EF Core
Application	"Place order", "Cancel order" — NO EF Core
Infrastructure	EF Core and mapping files

Only the "main" object of each group gets a DbSet in EF Core. We'll explain that group (called an aggregate) in the next section.

Folder layout

src/
├── Billing.Domain/              # Business rules — NO EF Core here
│   ├── Orders/
│   │   ├── Order.cs             # The "boss" object (aggregate root)
│   │   ├── OrderLine.cs         # A line item inside an order
│   │   └── OrderId.cs           # A safe ID type (section 6)
│   └── Common/
│       └── Money.cs             # A small object with no ID (section 4)
│
├── Billing.Application/         # Handlers — NO EF Core
│
└── Billing.Infrastructure/      # EF Core lives HERE
    └── Persistence/
        ├── ApplicationDbContext.cs
        └── Configurations/
            └── OrderConfiguration.cs   # "How to save Order to SQL"

DbContext — only register the "boss" objects

DbSet means "EF Core can load and save this type directly." Only the main object (like Order) gets one. Line items (OrderLine) are saved automatically when you save the order.

public sealed class ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
    : DbContext(options)
{
    // ✅ YES — Order is the "boss" of its group
    public DbSet<Order> Orders => Set<Order>();
    public DbSet<Customer> Customers => Set<Customer>();

    // ❌ NO — OrderLine is saved through Order, not on its own
    // public DbSet<OrderLine> OrderLines => ...  DON'T DO THIS

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // Finds all mapping files automatically
        modelBuilder.ApplyConfigurationsFromAssembly(typeof(ApplicationDbContext).Assembly);
    }
}

3 · The Main Object (Aggregate Root)

An aggregate is a group of objects that belong together — like an Order and its OrderLine items.

You always load and save the whole group through one "boss" object called the aggregate root. In our example, Order is the boss.

EF Core needs a private empty constructor (private Order() { }) to rebuild objects from the database. Your app code should never call it — always use Order.Create() instead.

The Order class — business rules inside

Notice: you can't change status directly. You call Place() and the class checks the rules for you.

// Domain/Orders/Order.cs
public sealed class Order : BaseEntity
{
    public OrderId Id { get; private set; }
    public CustomerId CustomerId { get; private set; }
    public OrderStatus Status { get; private set; }
    public Money Total { get; private set; } = Money.Zero;

    private readonly List<OrderLine> _lines = [];
    public IReadOnlyCollection<OrderLine> Lines => _lines.AsReadOnly();

    private Order() { } // EF Core only — your code never calls this

    public static Order Create(CustomerId customerId)
    {
        var order = new Order
        {
            Id = OrderId.New(),
            CustomerId = customerId,
            Status = OrderStatus.Draft
        };
        order.Raise(new OrderCreatedEvent(order.Id));
        return order;
    }

    public void AddLine(ProductId productId, int qty, Money unitPrice)
    {
        if (Status != OrderStatus.Draft)
            throw new DomainException("Cannot modify a placed order.");
        if (qty <= 0)
            throw new DomainException("Quantity must be positive.");

        _lines.Add(new OrderLine(productId, qty, unitPrice));
        Total = Money.Sum(_lines.Select(l => l.LineTotal));
    }

    public void Place()
    {
        if (_lines.Count == 0) throw new DomainException("Empty order.");
        Status = OrderStatus.Placed;
        Raise(new OrderPlacedEvent(Id, CustomerId, Total));
    }
}

The mapping file — tells EF Core how to save Order

This file lives in Infrastructure. It says: table name, how to save IDs, how to save Money, how to save line items, and what to ignore.

// Infrastructure/Persistence/Configurations/OrderConfiguration.cs
public sealed class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.ToTable("Orders");

        builder.HasKey(o => o.Id);
        builder.Property(o => o.Id)
            .HasConversion(id => id.Value, v => new OrderId(v));

        builder.Property(o => o.CustomerId)
            .HasConversion(id => id.Value, v => new CustomerId(v));

        builder.Property(o => o.Status)
            .HasConversion<string>()
            .HasMaxLength(32);

        // Money is a small object — save it as extra columns (section 4)
        builder.OwnsOne(o => o.Total, money =>
        {
            money.Property(m => m.Amount).HasColumnName("TotalAmount").HasPrecision(18, 2);
            money.Property(m => m.Currency).HasColumnName("TotalCurrency").HasMaxLength(3);
        });

        // Line items — saved in a separate table, linked to Order
        builder.HasMany<OrderLine>("_lines")
            .WithOne()
            .HasForeignKey(l => l.OrderId)
            .OnDelete(DeleteBehavior.Cascade);

        // Events are in-memory only — don't save to database
        builder.Ignore(o => o.DomainEvents);
    }
}

⚠️ Watch out: don't make setters public just to fix an EF error. If EF Core complains about a private set, fix it in the mapping file — don't weaken your class.

4 · Small Objects With No ID (Value Objects)

Some objects don't need their own ID.

Money is just an amount and a currency.
Address is just street, city, zip.

Two Money(10, "EUR") objects are the same thing — that's a value object.

EF Core saves them as extra columns on the parent table (not a separate table). You use OwnsOne or, in .NET 8+, the simpler ComplexType.

What a value object looks like

No Id property. Just data. You can add validation in the constructor — like "street can't be empty."

// Money — just amount + currency, nothing else
public sealed record Money(decimal Amount, string Currency)
{
    public static Money Zero => new(0m, "EUR");

    public static Money Sum(IEnumerable<Money> items)
    {
        var list = items.ToList();
        if (list.Count == 0) return Zero;
        return new Money(list.Sum(m => m.Amount), list[0].Currency);
    }
}

// Address — another common value object
public sealed record Address(string Street, string City, string PostalCode, string Country)
{
    public Address(string street, string city, string postalCode, string country)
    {
        if (string.IsNullOrWhiteSpace(street)) throw new DomainException("Street required.");
        Street = street.Trim();
        City = city.Trim();
        PostalCode = postalCode.Trim();
        Country = country.Trim();
    }
}

OwnsOne — save it as extra columns

The address columns go on the Customers table — no new table needed. You pick the column names.

// Creates columns on Customers table:
//   ShipStreet, ShipCity, ShipPostalCode, ShipCountry

builder.OwnsOne(c => c.ShippingAddress, addr =>
{
    addr.Property(a => a.Street).HasColumnName("ShipStreet").HasMaxLength(200);
    addr.Property(a => a.City).HasColumnName("ShipCity").HasMaxLength(100);
    addr.Property(a => a.PostalCode).HasColumnName("ShipPostalCode").HasMaxLength(20);
    addr.Property(a => a.Country).HasColumnName("ShipCountry").HasMaxLength(60);
});

ComplexType — even easier (.NET 8+)

If you're on .NET 8 or later, slap [ComplexType] on the record and use ComplexProperty in the mapping. Less typing, same result.

[ComplexType]
public sealed record Money(decimal Amount, string Currency) { /* ... */ }

builder.ComplexProperty(o => o.Total, money =>
{
    money.Property(m => m.Amount).HasColumnName("TotalAmount").HasPrecision(18, 2);
    money.Property(m => m.Currency).HasColumnName("TotalCurrency").HasMaxLength(3);
});

// Which one to pick?
//   OwnsOne     → works on older EF Core, more options
//   ComplexType   → .NET 8+, simpler, always extra columns

OwnsMany — a list of small objects needs its own table

Usually one value object = extra columns. But if you have a list of them (like discount codes), EF Core creates a small separate table.

public sealed class Order : BaseEntity
{
    private readonly List<DiscountCode> _discounts = [];
    public IReadOnlyCollection<DiscountCode> Discounts => _discounts.AsReadOnly();
}

builder.OwnsMany(o => o.Discounts, d =>
{
    d.ToTable("OrderDiscounts");
    d.WithOwner().HasForeignKey("OrderId");
    d.Property(x => x.Code).HasMaxLength(20);
    d.Property(x => x.Percentage).HasPrecision(5, 2);
    d.HasKey("OrderId", nameof(DiscountCode.Code));
});

5 · Lists Inside an Object (Backing Fields)

Don't expose a public List<OrderLine> that anyone can add to or clear.

Instead:

Keep a private list (_lines)
Expose a read-only view (Lines)
Changes go through methods like AddLine()

EF Core can still read and write your private list — you just tell the mapping file where it is.

Private list, public read-only view

// In your Order class:
private readonly List<OrderLine> _lines = [];
public IReadOnlyCollection<OrderLine> Lines => _lines.AsReadOnly();

public void AddLine(ProductId productId, int qty, Money unitPrice)
{
    _lines.Add(new OrderLine(productId, qty, unitPrice));
}

// In your mapping file — point EF Core at "_lines"
builder.HasMany<OrderLine>("_lines")
    .WithOne()
    .HasForeignKey(l => l.OrderId)
    .OnDelete(DeleteBehavior.Cascade);

OrderLine — belongs inside Order, not on its own

OrderLine is not the "boss." You never load it directly from the database — you load the Order and its lines come with it.

public sealed class OrderLine
{
    public OrderLineId Id { get; private set; }
    public OrderId OrderId { get; private set; }
    public ProductId ProductId { get; private set; }
    public int Quantity { get; private set; }
    public Money UnitPrice { get; private set; }
    public Money LineTotal => new(Quantity * UnitPrice.Amount, UnitPrice.Currency);

    private OrderLine() { } // EF Core only

    internal OrderLine(ProductId productId, int qty, Money unitPrice)
    {
        Id = OrderLineId.New();
        ProductId = productId;
        Quantity = qty;
        UnitPrice = unitPrice;
    }
}

// Mapping file for OrderLine
public sealed class OrderLineConfiguration : IEntityTypeConfiguration<OrderLine>
{
    public void Configure(EntityTypeBuilder<OrderLine> builder)
    {
        builder.ToTable("OrderLines");
        builder.HasKey(l => l.Id);
        builder.Property(l => l.Id)
            .HasConversion(id => id.Value, v => new OrderLineId(v));
        builder.OwnsOne(l => l.UnitPrice, m => { /* column names */ });
        builder.Ignore(l => l.LineTotal); // calculated — don't save to DB
    }
}

⚠️ Watch out: don't query line items on their own. Don't add DbSet<OrderLine>. Always load the Order first.

6 · Safe IDs (No More Guid Mix-ups)

If everything is a Guid, you can accidentally pass a customer ID where an order ID is expected — and C# won't warn you.

The fix: wrap each ID in its own small type (OrderId, CustomerId). Swap them by mistake and the compiler catches it.

EF Core still saves them as plain Guid in SQL — you just add a one-line conversion in the mapping file.

Wrap your Guids

public readonly record struct OrderId(Guid Value)
{
    public static OrderId New() => new(Guid.NewGuid());
}

public readonly record struct CustomerId(Guid Value);
public readonly record struct ProductId(Guid Value);

// This won't compile — you swapped the IDs:
// void Ship(OrderId orderId, CustomerId customerId) { }
// Ship(customerId, orderId); // ❌ compiler error — saved you!

Tell EF Core how to save them

Write this helper once, then use one line per ID in every mapping file.

public static class StronglyTypedIdExtensions
{
    public static PropertyBuilder<TId> HasStronglyTypedIdConversion<TId>(
        this PropertyBuilder<TId> propertyBuilder)
        where TId : struct
    {
        var converter = new ValueConverter<TId, Guid>(
            id => (Guid)typeof(TId).GetProperty("Value")!.GetValue(id)!,
            value => (TId)Activator.CreateInstance(typeof(TId), value)!);

        return propertyBuilder.HasConversion(converter);
    }
}

// In OrderConfiguration — one line each:
builder.Property(o => o.Id).HasStronglyTypedIdConversion<OrderId>();
builder.Property(o => o.CustomerId).HasStronglyTypedIdConversion<CustomerId>();

7 · The Mapping File (Putting It All Together)

One mapping class per entity, in Infrastructure.

It answers: what table? what columns? how to save IDs and value objects? what to ignore?

Here's a complete example for Order — use it as a template.

public sealed class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.ToTable("Orders", schema: "billing");

        // ID
        builder.HasKey(o => o.Id);
        builder.Property(o => o.Id).HasStronglyTypedIdConversion<OrderId>();

        // Link to Customer — just store the ID, no Customer object here
        builder.Property(o => o.CustomerId).HasStronglyTypedIdConversion<CustomerId>();

        // Status as readable text in SQL ("Draft", "Placed", ...)
        builder.Property(o => o.Status)
            .HasConversion<string>()
            .HasMaxLength(32)
            .IsRequired();

        // Money value object → extra columns
        builder.OwnsOne(o => o.Total, money =>
        {
            money.Property(m => m.Amount).HasColumnName("TotalAmount").HasPrecision(18, 2);
            money.Property(m => m.Currency).HasColumnName("TotalCurrency").HasMaxLength(3);
        });

        // Line items via private _lines field
        builder.HasMany<OrderLine>("_lines")
            .WithOne()
            .HasForeignKey(l => l.OrderId)
            .OnDelete(DeleteBehavior.Cascade);

        // Don't save events to the database
        builder.Ignore(o => o.DomainEvents);

        // Speed up common searches
        builder.HasIndex(o => o.CustomerId);
        builder.HasIndex(o => o.Status);
    }
}

What goes where?

✅ Put in mapping file (Infrastructure):

Table name
How to save IDs, enums, value objects
How to save lists (_lines)
Ignore events and calculated properties
Column sizes (MaxLength, Precision)

✅ OK to leave alone (EF guesses correctly):

int, string, bool properties
Column names same as property names

❌ Never put on Domain classes:

[Table], [Column], [ForeignKey] attributes
public setters "because EF needs them"
Any using Microsoft.EntityFrameworkCore;

8 · Saving, Loading & Mistakes to Avoid

A repository is a thin wrapper that loads and saves your "boss" objects (Order, Customer).

Your handler calls GetById, changes the object through its methods, then calls SaveChanges. That's it.

How to load, change, and save

// Interface — only works with Order, not OrderLine
public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(OrderId id, CancellationToken ct);
    void Add(Order order);
}

// Implementation
public sealed class OrderRepository(ApplicationDbContext db) : IOrderRepository
{
    public Task<Order?> GetByIdAsync(OrderId id, CancellationToken ct) =>
        db.Orders
            .Include(o => o.Lines)   // don't forget this — or lines won't load!
            .FirstOrDefaultAsync(o => o.Id == id, ct);

    public void Add(Order order) => db.Orders.Add(order);
}

// Typical flow in a handler:
var order = await repo.GetByIdAsync(cmd.OrderId, ct)
    ?? throw new NotFoundException();
order.Place();                    // business rules run here
await db.SaveChangesAsync(ct);    // EF saves changes to SQL

Domain events — memory only, not in the database

When something important happens (order placed), the class raises an event. These live in memory until SaveChanges sends them out. Never save them as a table column.

// In mapping file — always ignore events:
builder.Ignore(o => o.DomainEvents);

Quick lookup — "I have X, how do I map it?"

You have…	Map it with…
Main object (Order)	`DbSet` + mapping file
Item inside Order (Line)	`HasMany("_lines")`, no DbSet
Money, Address (no ID)	`OwnsOne` or `ComplexType`
List of small objects	`OwnsMany`
OrderId, CustomerId	`HasStronglyTypedIdConversion`
`private set` on property	works fine — don't change it
`private Order() { }`	EF Core needs it, your code doesn't
DomainEvents	`builder.Ignore(...)`
Calculated property	`builder.Ignore(...)`
Status enum	save as string
Link to another aggregate	store ID only, no `Customer` property

5 mistakes beginners make

Making everything public set — fix it in the mapping file, not the class.
DbSet for line items — only the boss object gets a DbSet.
Putting [Table] on domain classes — mapping files go in Infrastructure.
Customer property on Order — store CustomerId only, not the whole Customer object.
Forgetting .Include(o => o.Lines) — line items won't load and you'll wonder why the list is empty.

What's next?

Clean Architecture & CQRS — how the whole app fits together
EF Core In Depth — migrations, speed tips, production setup
Testing .NET — test your save/load code with a real database

Full tutorial with more examples: [www.web-partner.gr)

Written by Spyros Ponaris — .NET Tech Lead, Athens.

SQL Server and Azure SQL Updates with EF Core 10

Tue, 30 Dec 2025 21:06:54 +0000

EF Core 10 was released in November 2025 together with .NET 10 and is an LTS release supported until 2028. This version mainly focuses on better alignment with new SQL Server capabilities rather than introducing radically new concepts.

Below are a few changes that are worth noting from a practical point of view.

Vector data type support

EF Core 10 adds direct support for the vector data type introduced in SQL Server 2025 and Azure SQL. This makes it possible to store embeddings directly in the database without additional workarounds.

A simple entity example looks like this:

public class Blog
{
    public int Id { get; set; }

    [Column(TypeName = "vector(1536)")]
    public SqlVector<float> Embedding { get; set; }
}

Once the embedding is generated on the application side, it can be saved using the standard EF workflow:

context.Blogs.Add(new Blog
{
    Embedding = new SqlVector<float>(embedding)
});

await context.SaveChangesAsync();

Similarity queries can also be written directly in LINQ using EF.Functions.VectorDistance:

var blogs = await context.Blogs
    .OrderBy(b => EF.Functions.VectorDistance("cosine", b.Embedding, queryVector))
    .Take(3)
    .ToListAsync();

This is useful in scenarios such as semantic search or basic recommendation logic, without needing custom SQL or external query layers.

Native JSON data type mapping

With SQL Server 2025, JSON can now be stored using a dedicated json data type. EF Core 10 supports this natively and uses it automatically when the compatibility level allows it.

For example:

public class Blog
{
    public int Id { get; set; }
    public string[] Tags { get; set; }
    public BlogDetails Details { get; set; }
}

public class BlogDetails
{
    public int Viewers { get; set; }
}

Model configuration:

modelBuilder.Entity<Blog>()
    .ComplexProperty(b => b.Details, b => b.ToJson());

With this setup, both Tags and Details are created as json columns in the database.

Querying remains straightforward:

var blogs = await context.Blogs
    .Where(b => b.Details.Viewers > 3)
    .ToListAsync();

EF Core translates this into SQL using the appropriate JSON functions. For domains that already rely on JSON-like structures, this results in cleaner models and fewer mapping concerns.

Naming default constraints

EF Core 10 allows explicitly naming default constraints instead of relying on database-generated names. This can help reduce unnecessary changes in migrations and make schema updates easier to track.

Example:

modelBuilder.Entity<Post>()
    .Property(p => p.CreatedDate)
    .HasDefaultValueSql("GETDATE()", "DF_Post_CreatedDate");

It’s also possible to enable automatic naming across the model:

modelBuilder.UseNamedDefaultConstraints();

This change is mostly about maintainability, especially in projects with long migration histories.

Closing thoughts

EF Core 10 feels like a refinement release rather than a disruptive one. The added support for vector and JSON data types mainly improves how EF integrates with newer SQL Server features, while smaller changes like constraint naming help with long-term maintenance.

Why Most .NET Developers Misuse Records — and What It’s Costing Them

Tue, 08 Jul 2025 07:24:07 +0000

Most .NET devs are misusing records—and it's costing them more than they think. Memory overhead. Identity tracking bugs. EF Core confusion.

I broke it all down in my latest Medium post: Why Most .NET Developers Misuse Records and What It’s Costing Them Read here

Inside:

Why value equality isn't always the win you expect

How EF Core gets tripped up by records

Benchmark graphs showing real clone costs in hot loops

When to ditch the with expression and reach for a constructor

This one's for every architect, lead dev, and performance-obsessed coder who wants to use records right.

️ Read it. Share it. Argue with it. Let’s rethink how we use C# records.