Shadow Properties, Indexer Properties, Property Bags, and Infrastructure Metadata

Learning outcomes

Chapter 03 introduced backing fields and contrasted field-only with shadow state. In ServiceHub, Chapter 04 now uses shadow state deliberately for infrastructure metadata and shows the adjacent concepts that are often confused with it: shadow foreign keys, indexer properties, and shared-type property-bag entities. The goal is not to hide more data from the domain; it is to know exactly where each mapped value lives.

1. Shadow state exists in the EF model and ChangeTracker, not the CLR object

A shadow property has a name/type in EF's model but no CLR property or field on the entity class. For a tracked entity, EF stores its current/original values in the change-tracking entry. That makes shadow state useful for some infrastructure fields, but it also means a detached WorkOrder object does not carry those values with it.

builder.Property<DateTime>("CreatedUtc")    .HasColumnName("created_utc")    .HasDefaultValueSql("CURRENT_TIMESTAMP")    .ValueGeneratedOnAdd();builder.Property<DateTime?>("LastModifiedUtc")    .HasColumnName("last_modified_utc");

CreatedUtc continues Lesson 3's database-generated experiment as UTC DateTime specifically so the SQLite lab can compare/order it server-side. LastModifiedUtc is application-managed in this lesson so we can observe setting a shadow value explicitly.

2. Read/write shadow state through Entry while tracked

var workOrder = await db.WorkOrders.SingleAsync(    x => x.WorkOrderNumber == "WO-2026-000201", ct);var entry = db.Entry(workOrder);Console.WriteLine(entry.Property<DateTime>("CreatedUtc").CurrentValue);entry.Property<DateTime?>("LastModifiedUtc").CurrentValue =    new DateTime(2026, 8, 27, 10, 0, 0, DateTimeKind.Utc);workOrder.ReviseSummary("Inspect cavitation alarm and inlet pressure");await db.SaveChangesAsync(ct);

This is powerful but string-heavy. If business code routinely needs LastModifiedUtc, hiding it as a shadow property may be worse than exposing a well-designed domain/infrastructure abstraction.

3. EF.Property puts shadow state into a translatable query

var cutoff = new DateTime(2026, 8, 27, 0, 0, 0, DateTimeKind.Utc);var recent = await db.WorkOrders    .Where(x => EF.Property<DateTime>(x, "CreatedUtc") >= cutoff)    .OrderByDescending(x => EF.Property<DateTime>(x, "CreatedUtc"))    .Select(x => new    {        x.WorkOrderNumber,        CreatedUtc = EF.Property<DateTime>(x, "CreatedUtc")    })    .ToListAsync(ct);Console.WriteLine(db.WorkOrders    .Where(x => EF.Property<DateTime>(x, "CreatedUtc") >= cutoff)    .ToQueryString());

EF.Property is recognized by EF's query pipeline; it is not a general-purpose reflection API. Keep the exact property name centralized where possible because the compiler cannot rename a string literal for you.

4. No-tracking materialization cannot carry shadow values inside the entity

Microsoft documents that shadow properties cannot be accessed after a no-tracking query through a detached entity because the values are maintained by the change tracker. Project the value in the query if you need it outside tracking.

var rows = await db.WorkOrders    .AsNoTracking()    .Select(x => new    {        WorkOrder = x,        CreatedUtc = EF.Property<DateTime>(x, "CreatedUtc")    })    .ToListAsync(ct);

The projection carries the value explicitly. Do not load an untracked entity and then expect Entry(entity).Property("CreatedUtc") to magically recover the original store value without querying.

5. Shadow foreign keys can appear by convention

If a relationship has a navigation but no matching CLR foreign-key property, EF can create a shadow foreign-key property. This keeps the domain class free of a scalar FK, but it also makes serialization/disconnected updates harder because the FK value is tracker state rather than entity state.

public sealed class WorkOrderAttachment{    public long Id { get; set; }    public string FileName { get; set; } = string.Empty;    public WorkOrder WorkOrder { get; set; } = null!;}// With no CLR WorkOrderId property, relationship conventions/configuration// can create a shadow WorkOrderId foreign-key property.modelBuilder.Entity<WorkOrderAttachment>()    .HasOne(x => x.WorkOrder)    .WithMany()    .HasForeignKey("WorkOrderId");

Chapter 05 will decide when explicit FK properties improve aggregate/disconnected behavior. Here, inspect the metadata rather than assuming whether the FK is shadow.

6. Indexer properties are CLR-backed through an indexer

An indexer property is not shadow state. The entity has a CLR indexer—often backed by a dictionary—and EF maps named properties through that indexer.

public sealed class WorkOrderEnvelope{    private readonly Dictionary<string, object?> _values = new();    public int Id { get; set; }    public object? this[string key]    {        get => _values.TryGetValue(key, out var value) ? value : null;        set => _values[key] = value;    }}modelBuilder.Entity<WorkOrderEnvelope>(b =>{    b.HasKey(x => x.Id);    b.IndexerProperty<string>("RegionCode").HasMaxLength(12);});

The value lives in CLR state accessible through the indexer. This can be useful for dynamic extension data, but it trades compile-time domain discoverability for flexibility.

7. Property-bag entity types use Dictionary<string, object>

An EF property-bag entity type contains only indexer properties. EF currently supports Dictionary<string, object> for this pattern and configures it as a shared-type entity with a model name.

modelBuilder.SharedTypeEntity<Dictionary<string, object>>(    "WorkOrderAttribute",    b =>    {        b.ToTable("work_order_attributes");        b.IndexerProperty<int>("WorkOrderId");        b.IndexerProperty<string>("Name").HasMaxLength(80);        b.IndexerProperty<string>("Value").HasMaxLength(400);        b.HasKey("WorkOrderId", "Name");    });var set = db.Set<Dictionary<string, object>>("WorkOrderAttribute");

Property bags can model truly dynamic data or join payloads, but they are not a free replacement for normal entity types. They have feature limitations and make refactoring/validation more string-oriented.

8. Inspect shadow/indexer metadata explicitly

foreach (var entityType in db.Model.GetEntityTypes()){    foreach (var property in entityType.GetProperties())    {        Console.WriteLine(            $"{entityType.DisplayName()}.{property.Name} " +            $"shadow={property.IsShadowProperty()} " +            $"indexer={property.IsIndexerProperty()}");    }}

A field-only property from Chapter 03 is neither the same as a shadow property nor an indexer property; it has CLR field storage. Keep these categories explicit in design reviews.

9. Deliberately wrong approach: typo silently creates a second shadow property

builder.Property<DateTime>("CreatedUtc")    .HasColumnName("created_utc");// Later typo in another configuration fragment:builder.Property<DateTimeOffset>("CreatedUTC")    .HasColumnName("created_utc_2");

Because neither name must correspond to a CLR member, both strings can become valid model properties. The bug may surface as migration drift rather than a compiler error.

10. Hands-on lab: prove where each kind of state lives

1. Keep CreatedUtc and add LastModifiedUtc as shadow properties.
2. Load one work order with tracking, print both values via Entry.Property, set LastModifiedUtc, save, and inspect SQL.
3. Query by CreatedUtc with EF.Property and inspect ToQueryString().
4. Run an AsNoTracking projection that carries CreatedUtc explicitly.
5. Create the temporary WorkOrderAttachment shadow-FK example and inspect IsShadowProperty().
6. Create WorkOrderEnvelope and prove RegionCode is indexer-backed, not shadow.
7. Create the temporary shared WorkOrderAttribute property bag and inspect its model metadata.
8. Introduce the CreatedUTC typo, generate a migration/model dump, diagnose the duplicate, and remove it.

Verification checklist

• You can state where each mapped value is physically stored in CLR/tracker state.
• No-tracking code projects shadow values before detachment when needed.
• String property names are covered by model assertions.
• The property-bag example remains an explicit dynamic-data experiment, not a default modeling style.
• Relationship shadow-state examples are left for deeper treatment in Chapter 05.

11. Production judgment and bridge

Shadow state is best for narrowly scoped infrastructure metadata whose absence from the CLR model is intentional. Do not hide tenant identifiers, authorization-critical state, or business decisions merely to make entities look clean. Indexer/property-bag patterns are specialized flexibility tools, not the default for strongly modeled domains.

Lesson 5 combines property semantics with writes. You will configure optimistic concurrency, inspect the generated UPDATE predicate, compare application-managed tokens on SQLite with SQL Server rowversion, and see how store-generated/save behaviors decide which values EF sends or reads back.

Authoritative references

• Shadow and Indexer Properties - EF Core — shadow properties, EF.Property, indexer properties, and property-bag entity types
• Foreign and principal keys — shadow foreign-key conventions/configuration
• EF.Property<TProperty> — query-time access to shadow/indexer/field-backed metadata
• Change Tracking - EF Core — tracking-state lifetime and values
• Microsoft.EntityFrameworkCore 10.0.11 — current EF Core baseline