Follow-up to #2919: docs + extended scenario tests for DbContext abstractions

[jeremydmiller]

Reviewer-requested follow-up to #2919 (DbContext abstractions support via WithDbContextAbstraction<TAbstraction, TDbContext>()).

Three new test scenarios

A new file at src/Persistence/EfCoreTests/dbContext_abstraction_scenarios.cs covers contracts that the merged PR's tests don't reach:

1. multiple_dbcontext_types_one_abstracted_one_direct — one Wolverine host with two DbContexts: OrdersDbContext registered through an IOrderRepository abstraction and CustomersDbContext used directly. Both handlers transact correctly through the EF Core middleware in parallel.

2. multiple_abstractions_for_same_dbcontext_each_used_independently — StoreDbContext implements both IItemRepository and IOrderInsightRepository. Two separate handlers, each depending on a different abstraction, both successfully commit through the same physical DbContext.

3. handler_using_two_abstractions_to_same_dbcontext_uses_one_scoped_instance — the headline scenario. The handler takes BOTH IItemRepository and IOrderInsightRepository, casts both back to StoreDbContext, and asserts ReferenceEquals(itemsCtx, ordersCtx). That's the contract the merged CastDbContextFrame depends on: at runtime, both parameters resolve to the same scoped DbContext, just viewed through different interfaces, so a single SaveChangesAsync commits all writes atomically.

A note about #3: the contract only holds when the abstractions forward to the same scoped DbContext in DI via a factory:

services.AddScoped<IItemRepository>(sp => sp.GetRequiredService<StoreDbContext>());
services.AddScoped<IOrderInsightRepository>(sp => sp.GetRequiredService<StoreDbContext>());

services.AddScoped<IItemRepository, StoreDbContext>() (without the factory) would create a separate DbContext instance per registered interface, and the cast frame would land on whichever the codegen picked first while the handler's other reference points at a different one. The new docs section calls this out explicitly.

Docs

New DbContext Abstractions section at the bottom of docs/guide/durability/efcore/transactional-middleware.md. Five #region sample_* blocks in the test file, expanded by mdsnippets so every code block in the doc lives in a passing test:

• sample_register_dbcontext_abstraction — the bare single-abstraction registration shape
• sample_handler_using_dbcontext_abstraction — handler depending on the abstraction
• sample_register_multiple_dbcontext_abstractions — two abstractions, factory-forwarded to the same scoped DbContext
• sample_handler_using_multiple_abstractions — handler taking both abstractions; ref-equality contract
• sample_register_mixed_dbcontexts — multi-DbContext, mixed abstraction registration

The rest of the doc diffs in this PR are mdsnippets regenerations of unrelated snippets it touched while running over the whole repo.

Schema setup detail (mirrors the GH-2618 workaround)

EF Core's EnsureCreatedAsync is a no-op when the database already exists — and the shared Wolverine integration-tests Postgres always does. So each scenario drops + creates its test schemas and then issues raw CREATE TABLE DDL for the user-defined entity tables, the same pattern Bug_DurableLocalQueue_ancillary_store_routing uses for the same reason.

Verification

• New scenario suite: 3/3 pass against Postgres on port 5433.
• Full dotnet build wolverine.slnx -c Release clean (0 warnings, 0 errors).
• mdsnippets expansion of the new doc anchors succeeded and is committed.

🤖 Generated with Claude Code