On this page
Compose persistence across modules
Own contexts, transactions, variable EF models and immutable schema history.
Give approved modules a shared EF model without hiding context ownership, transactions or tenant admission. The optional composition APIs arrived in 0.18.0 and are available in the 0.19.0 package family.
Choose the ownership boundary
The host owns the DbContext, provider connection, authorized tenant selection,
factory lifetime and migration history. A module contributes mappings through
IModuleModel; it does not discover arbitrary assemblies or select a connection
from a request body. Foundation's factory/model hooks are not a tenant sandbox,
a permission check or a schema-provisioning service.
Reference Fabricators.Infrastructure in the integration layer and select your
EF provider explicitly. Keep product entities and business invariants in their
own layers; see package responsibilities.
Register the context factory
Configure the host's IDbContextFactory<TContext>, then register its module-facing
adapter with AddFoundationModuleDbContext<TContext>(). A module asks the resulting
IModuleDbContextFactory for a new context. The caller owns async disposal and
any transaction it starts.
The adapter does not join two independently created contexts into one transaction. If one use case must write several modules atomically, the trusted orchestration must deliberately use the same context/transaction or the provider's explicit transaction-sharing mechanism. Do not rely on a repository-per-save convention. Never cache a DbContext or use it concurrently across requests.
Describe a variable model explicitly
A ModuleModelSet is an ordered immutable snapshot of approved contributions,
identified by module ID, mapping revision and implementation type. Its fingerprint
also includes the host's explicit model variant. Reject duplicate IDs and update
the revision/variant whenever the resulting mapping changes.
A context implementing IModuleModelContext exposes that snapshot. Opt into
UseFoundationModuleModelCache on its EF options so model keys include context
type, composition fingerprint and the design-time flag. Without this opt-in, EF's
normal context-type cache can reuse a different composition's model in the same
process.
Do not use the fingerprint as an authorization token or a substitute for an app installation receipt. Model composition and permission/tenant authority have separate lifecycles. A changing composition is a host deployment decision, not an anonymous per-query option.
Apply migrations through the owner
The host must define how its mappings become schema and how already applied migrations remain immutable. Validate the expected history, produce reviewed SQL with the provider's migration tooling, then deploy under the appropriate owner. Do not run DDL under the API runtime role or invent a new history on a populated customer database.
When upgrading an application, a changed assembly at an unchanged immutable app release is not silently adopted by these hooks. Application installers own app release/version and receipt validation; Foundation supplies no bypass.
Prove the composition you will ship
Test two different module sets in the same process, changed revisions/variants, design-time keys and mapping conflicts. Use the actual relational provider to prove transaction commit/rollback and disposal. A model-cache test alone proves neither schema readiness nor tenant isolation.
Next: Infrastructure API, cache boundaries and authoring verification.