DcsvIo.D2.DataGovernance.EntityFrameworkCore 0.1.1

DcsvIo.D2.DataGovernance.EntityFrameworkCore

Audience: backend .NET service engineers decorating EF Core entity models for GDPR anonymization — wiring the fluent .Anonymize* API, registering the engine, and configuring the startup model guard.

EF Core metadata layer for GDPR anonymization. Converges the attribute and fluent decoration front-ends onto one AnonymizationRule stored as the D2:Anonymize EF Core model annotation. The anonymization engine reads only that annotation at runtime. Includes the AnonymizationEngine (erases PII in place on subject erasure), AnonymizationModelValidator (deny-by-default boot guard), and AddD2DataGovernance (DI entry point).

Install

dotnet add package DcsvIo.D2.DataGovernance.EntityFrameworkCore

Purpose

Two decoration paths produce the same annotation on a mapped property:

• Attribute path — [Anonymizable(...)] on the CLR property, activated by ApplyAnonymizationConventions() in ConfigureConventions. The AnonymizableAttributeConvention (IModelFinalizingConvention) walks every mapped scalar and complex sub-property at model-finalization time, reads the attribute, and writes the D2:Anonymize annotation with DataAnnotation configuration source.
• Fluent path — Anonymize* extension methods called in OnModelCreating on PropertyBuilder<T>, OwnedNavigationBuilder<TOwner, TDependent>, ComplexPropertyBuilder<T>, or ComplexTypePropertyBuilder<TProperty>. Each method writes the annotation directly via the public HasAnnotation API (Explicit configuration source).

When both paths target the same property, the fluent declaration wins. EF Core's config-source precedence (Explicit > DataAnnotation) enforces this automatically.

Public API surface

Annotation key

Fluent extension methods

All overloads are C# 14 block-form extensions. Each writes an AnonymizationRule via AnonymizationRule.Create and the public HasAnnotation API (Explicit source).

On PropertyBuilder<TProperty> — entity scalars and directly-reached VO fields

On ComplexTypePropertyBuilder<TProperty> — complex-type member columns

Use this overload when you already hold the member builder from cp.Property(lambda). Typical usage: inside a ComplexProperty(…, cp => { … }) block after cp.Property(…).

This overload is structurally identical to PropertyBuilder<TProperty> (same four methods, same BCL guards, same HasAnnotation write with Explicit configuration source). The receiver type differs: EF Core returns ComplexTypePropertyBuilder<TProperty> from cp.Property(lambda), which is a distinct CLR type from PropertyBuilder<TProperty>, so C# 14 extension-member inference requires a separate overload block.

A [NotMapped] guard is not needed on this block: cp.Property(x => x.Member) itself throws upstream in EF before this overload is ever reached for an unmapped member, so a [NotMapped] member cannot reach this code. Contrast with the ComplexPropertyBuilder<TComplex> selector-based block below, which DOES check [NotMapped] because it accepts a member-selector lambda and calls builder.Property(sub) internally.

On OwnedNavigationBuilder<TOwner, TDependent> — OwnsOne/OwnsMany foreign-VO sub-properties

Each resolves the inner PropertyBuilder via builder.Property(sub) and writes the annotation with Explicit source.

On ComplexPropertyBuilder<TComplex> — ComplexProperty(...) foreign-VO sub-properties

Same four-method shape as OwnedNavigationBuilder, with Expression<Func<TComplex, TProp>>.

Activation extension

Decoration paths

Attribute path — consumer-owned types

Decorate CLR properties with [Anonymizable(...)] and call builder.ApplyAnonymizationConventions() in ConfigureConventions:

protected override void ConfigureConventions(ModelConfigurationBuilder builder)
{
    base.ConfigureConventions(builder);
    builder.ApplyAnonymizationConventions();
}

The convention walks all entity types (including EF-surfaced owned-entity types) and all declared complex properties at finalization time. Only mapped properties are reached; [NotMapped] or unmapped members are invisible to the convention.

Fluent path — foreign VOs and overrides

Decorate in OnModelCreating for types the consumer does not own (or when overriding an attribute):

protected override void OnModelCreating(ModelBuilder model)
{
    // Scalar on an entity
    model.Entity<User>()
         .Property(u => u.Email)
         .AnonymizeTemplate("deletedUser{UserId}@deleted.user.dcsv.io");

    // Sub-property on an owned navigation (OwnsOne)
    model.Entity<User>()
         .OwnsOne(u => u.Address, nav =>
         {
             nav.AnonymizeNull<string?>(a => a.Street);
             nav.AnonymizeEmpty<string?>(a => a.PostalCode);
         });

    // Sub-property on a complex property (selector-based — holds ComplexPropertyBuilder<T>)
    model.Entity<Profile>()
         .ComplexProperty(p => p.DisplayName, cp =>
         {
             cp.Anonymize<string>(d => d.Value, "[deleted]");
         });

    // Sub-property on a complex property (receiver-based — holds ComplexTypePropertyBuilder<T>)
    // clearedSentinel is a caller-defined tombstone, e.g. "v1." + new string('0', 64)
    model.Entity<Address>()
         .ComplexProperty(a => a.Location, cp =>
         {
             cp.Property(l => l.City).HasMaxLength(100).AnonymizeNull();
             cp.Property(l => l.PostalCode).HasMaxLength(20).AnonymizeEmpty();
             cp.Property(l => l.HashId).HasMaxLength(67).Anonymize("v1." + new string('0', 64));
         });
}

Precedence

Divergent attribute + fluent declarations (different strategies on the same property) are not an error at this layer — fluent wins. Detection of divergent double-declarations is the responsibility of the startup model guard.

Anonymization engine

AnonymizationEngine (IAnonymizationEngine) erases PII on subject deletion. Register it via AddD2DataGovernance.

// In a hosted service or CQRS command handler:
var result = await engine.AnonymizeUserAsync(userId, ct);

Returns D2Result<AnonymizationOutcome>. Fail-closed: any entity-type failure returns a non-Ok result — never silent partial success.

Tiers

Idempotency

Every query filters on IsAnonymized == false. Re-running for the same subject is safe.

Startup model guard

AnonymizationModelValidator runs as an IHostedService and validates the host DbContext model at start-up, aborting boot with a PII-safe InvalidOperationException on any misconfiguration. The guard checks:

All findings are collected before throwing so operators see the full list in one boot attempt. Opt out (test hosts only) by setting DATA_GOVERNANCE__SKIPMODELVALIDATION=true.

DI registration

Register everything via AddD2DataGovernance:

services.AddD2DataGovernance(configuration);

// Or with a configuration callback (wins over the bound section value):
services.AddD2DataGovernance(configuration, opts => opts.BatchSize = 200);

This registers:

• IAnonymizationEngine → AnonymizationEngine (scoped — matches the host DbContext)
• AnonymizationEngineOptions bound from the DATA_GOVERNANCE configuration section
• AnonymizationModelValidator as a singleton IHostedService

DbContext requirement: the engine and validator resolve the non-generic DbContext from a created scope. Register the host's concrete context as DbContext:

// AddDbContext<T> registers both T and DbContext by default.
services.AddDbContext<MyContext>(...);

// Or explicitly, when AddDbContext is not used:
services.AddScoped<DbContext>(sp => sp.GetRequiredService<MyContext>());

Options

AnonymizationEngineOptions (section DATA_GOVERNANCE):

Dependencies

Tests

Unit tests live in the DcsvIo.D2.Tests DataGovernance EF Core unit suite and the DcsvIo.D2.Tests DataGovernance unit suite. Unit-test contexts are model-build-only — no database connection is ever opened. Most use UseNpgsql with a dummy connection string to exercise Npgsql-specific relational metadata (column types, JSON mapping) that the in-memory provider does not model; a few use the EF Core in-memory provider (UseInMemoryDatabase) where only generic annotation/model-build logic is under test. Integration tests live in the DcsvIo.D2.Tests DataGovernance integration suite and use Testcontainers-PostgreSQL for end-to-end Tier-A/B anonymization assertions.

Telemetry

No telemetry surface — the engine emits no spans or metrics. The AnonymizationModelValidator logs a PII-safe InvalidOperationException message on boot-guard failure; all other log events are at Debug level. Consumers instrument the anonymization call sites in their own OTel setup.

Edge cases / gotchas

• Tier-C entities blocked at boot — any owned-JSON (ToJson()) or OwnsMany child-table entity decorated with [Anonymizable] causes AnonymizationModelValidator to abort host startup. Tier-C shapes require full materialization before overwrite; bulk ExecuteUpdateAsync cannot reach them. Restructure as first-class root entities or mark [ExemptFromAnonymization].
• Fluent wins over attribute — when both an [Anonymizable] attribute and a fluent .Anonymize* call target the same property, the fluent declaration wins (EF Core Explicit > DataAnnotation configuration source). Divergent double-declarations are detected by the startup guard (V6 check).
• SetNull on non-nullable column blocked at boot — V7 check in AnonymizationModelValidator detects SetNull rules targeting non-nullable columns and aborts startup. Use a Constant or Template rule instead.

Configuration

AnonymizationEngineOptions (configuration section DATA_GOVERNANCE):

References

• DcsvIo.D2.DataGovernance.Abstractions — marker interfaces, attribute, rule, and engine seam
• the shared library index — shared library index and dependency graph