Merge pull request #58 from EFNext/feat/hot-reload-tweaks

Add hot reload support for EF Core and MongoDB integrations

Author: koenbeuk

docs/.vitepress/config.mts

@@ -77,6 +77,7 @@ const sidebar: DefaultTheme.Sidebar = {
         { text: 'Block-Bodied Members', link: '/advanced/block-bodied-members' },
         { text: 'Custom Transformers', link: '/advanced/custom-transformers' },
         { text: 'Testing Strategy', link: '/advanced/testing-strategy' },
+        { text: 'Hot Reload', link: '/advanced/hot-reload' },
         { text: 'Limitations', link: '/advanced/limitations' },
       ]
     }

docs/advanced/hot-reload.md

@@ -0,0 +1,56 @@
+# Hot Reload
+
+ExpressiveSharp supports .NET hot reload. When you edit the body of an `[Expressive]` member during a `dotnet watch` (or IDE hot-reload) session, the next query execution uses the new expression — no manual cache clear, app restart, or rebuild required.
+
+## How It Works
+
+Three things happen on a hot-reload event:
+
+1. **Source generator re-runs incrementally.** Roslyn re-emits the per-assembly `ExpressionRegistry` so the factory methods produce lambdas built from the new IL.
+2. **The runtime invokes ExpressiveSharp's `[MetadataUpdateHandler]`.** This handler calls `ResetMap()` on each affected assembly's generated registry (rebuilding the `MethodHandle → LambdaExpression` dictionary) and clears the resolver and replacer caches.
+3. **The next query expands fresh.** EF Core (and MongoDB) integrations call `ExpandExpressives()` on every query execution, so the new expression body is woven in immediately.
+
+EF Core's compiled-query cache keys off the post-expansion tree shape. A structural change to an `[Expressive]` body produces a different cache key, so a fresh SQL compilation happens automatically.
+
+## Caveats
+
+::: warning `EF.CompileQuery` results are snapshotted
+`EF.CompileQuery` invokes expansion **once**, at compile time, and returns a delegate. Hot-reloading an `[Expressive]` member after the delegate is built does **not** retroactively update it. To pick up the new body, recreate the compiled query.
+:::
+
+::: warning Manually captured expression trees are frozen
+If you call `.ExpandExpressives()` yourself and store the result in a field or static, the tree is captured at that moment. Hot reload does not rewrite already-materialized trees held in user memory. Prefer the per-execution path (`AsExpressive()` + LINQ, or the `ExpressiveQueryCompiler` decorator wired by `UseExpressives()`).
+:::
+
+::: tip Constant-only edits behave like normal EF Core parameterization
+Changing `p.Status == 1` to `p.Status == 2` inside an `[Expressive]` member reuses the same compiled SQL with a different parameter — exactly the same behaviour as inline literals. This is the EF Core constant-parameterization rule, not an ExpressiveSharp limitation.
+:::
+
+::: info Rude edits still need a restart
+Signature changes, member removal, attribute edits, and other [rude edits](https://learn.microsoft.com/en-us/aspnet/core/test/hot-reload) require an app restart — same as any other `dotnet watch` rude edit. Body-only changes are the supported case.
+:::
+
+## Verifying It Works
+
+1. Start your app under `dotnet watch run` with EF Core SQL logging enabled (`LogTo(Console.WriteLine, LogLevel.Information)`).
+2. Run a query that uses an `[Expressive]` member:
+
+   ```csharp
+   public sealed class Product
+   {
+       public int Quantity { get; set; }
+       public int Price { get; set; }
+
+       [Expressive]
+       public int Total => Quantity * Price;
+   }
+
+   // ...
+   var rows = ctx.Products.AsExpressive().Where(p => p.Total > 100).ToList();
+   ```
+
+3. Observe the SQL: `WHERE [p].[Quantity] * [p].[Price] > @__p_0`.
+4. Edit `Total` to `Quantity * Price * 2`. Save.
+5. Trigger the same query path. The new SQL should reflect the updated computation.
+
+If the SQL does not update, check that you are not (a) calling through `EF.CompileQuery`, or (b) reusing a captured `Expression` tree built before the edit.

docs/guide/integrations/ef-core.md

@@ -214,6 +214,16 @@ The built-in `RelationalExtensions` package (for window functions) uses this plu
 The `ExpressiveSharp.EntityFrameworkCore` package bundles Roslyn analyzers and code fixes from `ExpressiveSharp.EntityFrameworkCore.CodeFixers`. These provide compile-time diagnostics and IDE quick-fix actions for common issues like missing `[Expressive]` attributes.
 :::
 
+## Hot Reload
+
+Body edits to `[Expressive]` members flow through to EF Core automatically — `ExpressiveQueryCompiler` re-expands every query at execution time, and the new tree shape produces a fresh entry in EF Core's compiled-query cache. No restart, no manual cache clear.
+
+::: warning
+`EF.CompileQuery(...)` snapshots expansion at compile time. Hot-reloading an `[Expressive]` member does not retroactively update an already-compiled query delegate — you have to recreate it.
+:::
+
+See [Hot Reload](../../advanced/hot-reload) for the full picture, including caveats around captured expression trees and rude edits.
+
 ## Next Steps
 
 - [Window Functions](../window-functions) — SQL window functions via the RelationalExtensions package

tests/ExpressiveSharp.EntityFrameworkCore.IntegrationTests/Tests/Sqlite/HotReloadTests.cs

@@ -0,0 +1,82 @@
+using System.Linq.Expressions;
+using System.Reflection;
+using ExpressiveSharp.EntityFrameworkCore.IntegrationTests.Infrastructure;
+using ExpressiveSharp.IntegrationTests.Scenarios.Store.Models;
+using ExpressiveSharp.Services;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+namespace ExpressiveSharp.EntityFrameworkCore.IntegrationTests.Tests.Sqlite;
+
+[TestClass]
+[DoNotParallelize]
+public class HotReloadTests : EFCoreTestBase
+{
+    protected override IAsyncDisposable CreateContextHandle(out DbContext context)
+    {
+        var handle = TestContextFactories.CreateSqlite();
+        context = handle.Context;
+        return handle;
+    }
+
+    [TestInitialize]
+    public Task SeedHotReloadData() => Context.SeedStoreAsync();
+
+    [TestMethod]
+    public async Task HotReload_NewExpressiveBody_FlowsThroughToSqlAndResults()
+    {
+        var baselineSql = Context.Set<Order>().Where(o => o.Total > 200).ToQueryString();
+        var baselineTotals = await Context.Set<Order>().Select(o => o.Total).OrderBy(t => t).ToListAsync();
+        CollectionAssert.AreEqual(new[] { 30.0, 240.0, 250.0, 1500.0 }, baselineTotals);
+
+        var (registryType, mapField, totalKey) = HotReloadRegistry.Locate(typeof(Order), nameof(Order.Total));
+        var map = (IDictionary<nint, LambdaExpression>)mapField.GetValue(null)!;
+        Expression<Func<Order, double>> reloaded = o => o.Price * o.Quantity * 2;
+
+        try
+        {
+            map[totalKey] = reloaded;
+            HotReloadRegistry.ClearResolverCaches();
+
+            var reloadedSql = Context.Set<Order>().Where(o => o.Total > 200).ToQueryString();
+            Assert.AreNotEqual(baselineSql, reloadedSql,
+                "ExpressiveQueryCompiler did not pick up the reloaded body — SQL is unchanged.");
+
+            var reloadedTotals = await Context.Set<Order>().Select(o => o.Total).OrderBy(t => t).ToListAsync();
+            CollectionAssert.AreEqual(new[] { 60.0, 480.0, 500.0, 3000.0 }, reloadedTotals);
+        }
+        finally
+        {
+            HotReloadRegistry.Reset(registryType);
+            HotReloadRegistry.ClearResolverCaches();
+        }
+    }
+}
+
+internal static class HotReloadRegistry
+{
+    public static (Type RegistryType, FieldInfo MapField, nint MemberKey) Locate(Type declaringType, string propertyName)
+    {
+        var registryType = declaringType.Assembly.GetType("ExpressiveSharp.Generated.ExpressionRegistry")
+            ?? throw new InvalidOperationException(
+                $"Generated ExpressionRegistry not found in {declaringType.Assembly.GetName().Name}.");
+        var mapField = registryType.GetField("_map", BindingFlags.Static | BindingFlags.NonPublic)
+            ?? throw new InvalidOperationException("ExpressionRegistry._map not found.");
+        var key = declaringType.GetProperty(propertyName)!.GetMethod!.MethodHandle.Value;
+        return (registryType, mapField, key);
+    }
+
+    public static void Reset(Type registryType)
+    {
+        var reset = registryType.GetMethod("ResetMap", BindingFlags.Static | BindingFlags.NonPublic)!;
+        reset.Invoke(null, null);
+    }
+
+    public static void ClearResolverCaches()
+    {
+        var method = typeof(ExpressiveResolver).GetMethod(
+            "ClearCachesForMetadataUpdate",
+            BindingFlags.Static | BindingFlags.NonPublic)!;
+        method.Invoke(null, null);
+    }
+}

tests/ExpressiveSharp.MongoDB.IntegrationTests/Tests/HotReloadTests.cs

@@ -0,0 +1,73 @@
+using System.Linq.Expressions;
+using System.Reflection;
+using ExpressiveSharp.IntegrationTests.Scenarios.Store.Models;
+using ExpressiveSharp.MongoDB.Extensions;
+using ExpressiveSharp.MongoDB.IntegrationTests.Infrastructure;
+using ExpressiveSharp.Services;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using MongoDB.Driver;
+using MongoDB.Driver.Linq;
+
+namespace ExpressiveSharp.MongoDB.IntegrationTests.Tests;
+
+[TestClass]
+[DoNotParallelize]
+public class HotReloadTests : MongoTestBase
+{
+    [TestMethod]
+    public async Task HotReload_NewExpressiveBody_FlowsThroughToMongoQueryProvider()
+    {
+        var baselineTotals = await Orders.AsExpressive()
+            .Select(o => o.Total)
+            .ToListAsync();
+        CollectionAssert.AreEquivalent(new[] { 240.0, 1500.0, 30.0, 250.0 }, baselineTotals);
+
+        var (registryType, mapField, totalKey) = HotReloadRegistry.Locate(typeof(Order), nameof(Order.Total));
+        var map = (IDictionary<nint, LambdaExpression>)mapField.GetValue(null)!;
+        Expression<Func<Order, double>> reloaded = o => o.Price * o.Quantity * 2;
+
+        try
+        {
+            map[totalKey] = reloaded;
+            HotReloadRegistry.ClearResolverCaches();
+
+            var reloadedTotals = await Orders.AsExpressive()
+                .Select(o => o.Total)
+                .ToListAsync();
+            CollectionAssert.AreEquivalent(new[] { 480.0, 3000.0, 60.0, 500.0 }, reloadedTotals);
+        }
+        finally
+        {
+            HotReloadRegistry.Reset(registryType);
+            HotReloadRegistry.ClearResolverCaches();
+        }
+    }
+}
+
+internal static class HotReloadRegistry
+{
+    public static (Type RegistryType, FieldInfo MapField, nint MemberKey) Locate(Type declaringType, string propertyName)
+    {
+        var registryType = declaringType.Assembly.GetType("ExpressiveSharp.Generated.ExpressionRegistry")
+            ?? throw new InvalidOperationException(
+                $"Generated ExpressionRegistry not found in {declaringType.Assembly.GetName().Name}.");
+        var mapField = registryType.GetField("_map", BindingFlags.Static | BindingFlags.NonPublic)
+            ?? throw new InvalidOperationException("ExpressionRegistry._map not found.");
+        var key = declaringType.GetProperty(propertyName)!.GetMethod!.MethodHandle.Value;
+        return (registryType, mapField, key);
+    }
+
+    public static void Reset(Type registryType)
+    {
+        var reset = registryType.GetMethod("ResetMap", BindingFlags.Static | BindingFlags.NonPublic)!;
+        reset.Invoke(null, null);
+    }
+
+    public static void ClearResolverCaches()
+    {
+        var method = typeof(ExpressiveResolver).GetMethod(
+            "ClearCachesForMetadataUpdate",
+            BindingFlags.Static | BindingFlags.NonPublic)!;
+        method.Invoke(null, null);
+    }
+}

tests/ExpressiveSharp.Tests/Services/ExpressiveHotReloadHandlerTests.cs

@@ -1,3 +1,4 @@
+using System.Linq.Expressions;
 using System.Reflection;
 using System.Reflection.Metadata;
 using ExpressiveSharp.Services;
@@ -92,4 +93,35 @@ public void Assembly_RegistersExpressiveHotReloadHandler()
         Assert.IsTrue(attributes.Any(a => a.HandlerType == typeof(ExpressiveHotReloadHandler)),
             "MetadataUpdateHandlerAttribute for ExpressiveHotReloadHandler not found on ExpressiveSharp assembly.");
     }
+    
+    [TestMethod]
+    public void ClearCache_RebuildsGeneratedRegistryMap()
+    {
+        var registryType = typeof(Product).Assembly.GetType("ExpressiveSharp.Generated.ExpressionRegistry");
+        Assert.IsNotNull(registryType, "Generated ExpressionRegistry not found in test assembly.");
+
+        var mapField = registryType!.GetField("_map", BindingFlags.Static | BindingFlags.NonPublic);
+        Assert.IsNotNull(mapField, "ExpressionRegistry._map field not found.");
+
+        var totalProperty = typeof(Product).GetProperty(nameof(Product.Total))!;
+        var resolver = new ExpressiveResolver();
+
+        var initial = resolver.FindGeneratedExpression(totalProperty);
+        Assert.IsNotNull(initial);
+        Assert.AreEqual(ExpressionType.Multiply, initial.Body.NodeType);
+
+        var mapBefore = mapField!.GetValue(null);
+        Assert.IsNotNull(mapBefore);
+
+        ExpressiveHotReloadHandler.ClearCache([typeof(Product)]);
+
+        var mapAfter = mapField.GetValue(null);
+        Assert.IsNotNull(mapAfter);
+        Assert.IsFalse(ReferenceEquals(mapBefore, mapAfter),
+            "ExpressionRegistry._map was not rebuilt — ResetMap was not invoked by the hot-reload handler.");
+
+        var rebuilt = resolver.FindGeneratedExpression(totalProperty);
+        Assert.IsNotNull(rebuilt);
+        Assert.AreEqual(initial.ToString(), rebuilt.ToString());
+    }
 }