Issue #31819: Fast DetectChanges; Issue #16491: legacy Merge-Option Feature

src/EFCore/ChangeTracking/ChangeTracker.cs

@@ -215,6 +215,44 @@ public virtual IEnumerable<EntityEntry<TEntity>> Entries<TEntity>()
             .Select(e => new EntityEntry<TEntity>(e));
     }
 
+    /// <summary>
+    /// Returns tracked entities that are in a given state from a fast cache.
+    /// </summary>
+    /// <param name="added">Entities in EntityState.Added state</param>
+    /// <param name="modified">Entities in Modified.Added state</param>
+    /// <param name="deleted">Entities in Modified.Deleted state</param>
+    /// <param name="unchanged">Entities in Modified.Unchanged state</param>
+    /// <returns>An entry for each entity that matched the search criteria.</returns>
+    public virtual IEnumerable<EntityEntry> GetEntriesForState(
+        bool added = false,
+        bool modified = false,
+        bool deleted = false,
+        bool unchanged = false)
+    {
+        return StateManager.GetEntriesForState(added, modified, deleted, unchanged)
+            .Select(e => new EntityEntry(e));
+    }
+
+    /// <summary>
+    /// Returns tracked entities that are in a given state from a fast cache.
+    /// </summary>
+    /// <param name="added">Entities in EntityState.Added state</param>
+    /// <param name="modified">Entities in Modified.Added state</param>
+    /// <param name="deleted">Entities in Modified.Deleted state</param>
+    /// <param name="unchanged">Entities in Modified.Unchanged state</param>
+    /// <returns>An entry for each entity that matched the search criteria.</returns>
+    public virtual IEnumerable<EntityEntry<TEntity>> GetEntriesForState<TEntity>(
+        bool added = false,
+        bool modified = false,
+        bool deleted = false,
+        bool unchanged = false)
+        where TEntity : class
+    {
+        return StateManager.GetEntriesForState(added, modified, deleted, unchanged)
+            .Where(e => e.Entity is TEntity)
+            .Select(e => new EntityEntry<TEntity>(e));
+    }
+
     private void TryDetectChanges()
     {
         if (AutoDetectChangesEnabled)

src/EFCore/ChangeTracking/EntityEntry.cs

@@ -680,6 +680,65 @@ public virtual void Reload()
     public virtual async Task ReloadAsync(CancellationToken cancellationToken = default)
         => Reload(await GetDatabaseValuesAsync(cancellationToken).ConfigureAwait(false));
 
+    /// <summary>
+    ///     Reloads the entity from the database using the specified <see cref="MergeOption" />.
+    /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         The behavior of this method depends on the <see cref="MergeOption" /> specified:
+    ///     </para>
+    ///     <para>
+    ///         <see cref="MergeOption.OverwriteChanges" />: Overwrites both current and original property values with values from the database.
+    ///         The entity will be in the <see cref="EntityState.Unchanged" /> state after calling this method.
+    ///     </para>
+    ///     <para>
+    ///         <see cref="MergeOption.PreserveChanges" />: Updates original property values with values from the database,
+    ///         but preserves any local modifications to current values. Modified properties remain modified with their current values.
+    ///     </para>
+    ///     <para>
+    ///         If the entity does not exist in the database, the entity will be <see cref="EntityState.Detached" />.
+    ///         Calling Reload on an <see cref="EntityState.Added" /> entity that does not exist in the database is a no-op.
+    ///     </para>
+    ///     <para>
+    ///         See <see href="https://aka.ms/efcore-docs-entity-entries">Accessing tracked entities in EF Core</see> for more information and
+    ///         examples.
+    ///     </para>
+    /// </remarks>
+    /// <param name="mergeOption">The merge option controlling how database values are applied to the entity.</param>
+    public virtual void Reload(MergeOption mergeOption)
+        => Reload(GetDatabaseValues(), mergeOption);
+
+    /// <summary>
+    ///     Reloads the entity from the database using the specified <see cref="MergeOption" />.
+    /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         The behavior of this method depends on the <see cref="MergeOption" /> specified:
+    ///     </para>
+    ///     <para>
+    ///         <see cref="MergeOption.OverwriteChanges" />: Overwrites both current and original property values with values from the database.
+    ///         The entity will be in the <see cref="EntityState.Unchanged" /> state after calling this method.
+    ///     </para>
+    ///     <para>
+    ///         <see cref="MergeOption.PreserveChanges" />: Updates original property values with values from the database,
+    ///         but preserves any local modifications to current values. Modified properties remain modified with their current values.
+    ///     </para>
+    ///     <para>
+    ///         If the entity does not exist in the database, the entity will be <see cref="EntityState.Detached" />.
+    ///         Calling Reload on an <see cref="EntityState.Added" /> entity that does not exist in the database is a no-op.
+    ///     </para>
+    ///     <para>
+    ///         See <see href="https://aka.ms/efcore-docs-entity-entries">Accessing tracked entities in EF Core</see> for more information and
+    ///         examples.
+    ///     </para>
+    /// </remarks>
+    /// <param name="mergeOption">The merge option controlling how database values are applied to the entity.</param>
+    /// <param name="cancellationToken">A <see cref="CancellationToken" /> to observe while waiting for the task to complete.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    /// <exception cref="OperationCanceledException">If the <see cref="CancellationToken" /> is canceled.</exception>
+    public virtual async Task ReloadAsync(MergeOption mergeOption, CancellationToken cancellationToken = default)
+        => Reload(await GetDatabaseValuesAsync(cancellationToken).ConfigureAwait(false), mergeOption);
+
     private void Reload(PropertyValues? storeValues)
     {
         if (storeValues == null)
@@ -697,6 +756,30 @@ private void Reload(PropertyValues? storeValues)
             State = EntityState.Unchanged;
         }
     }
+    private void Reload(PropertyValues? storeValues, MergeOption mergeOption)
+    {
+        if (storeValues == null)
+        {
+            if (State != EntityState.Added)
+            {
+                State = EntityState.Deleted;
+                State = EntityState.Detached;
+            }
+        }
+        else
+        {
+            foreach (var property in Metadata.GetProperties())
+            {
+                var value = storeValues[property];
+                InternalEntry.ReloadValue(property, value, mergeOption, updateEntityState: false);
+            }
+
+            if (mergeOption == MergeOption.OverwriteChanges)
+            {
+                State = EntityState.Unchanged;
+            }
+        }
+    }
 
     [field: AllowNull, MaybeNull]
     private IEntityFinder Finder

src/EFCore/ChangeTracking/Internal/InternalEntryBase.cs

@@ -998,6 +998,38 @@ private void DetectChanges(IComplexProperty complexProperty)
         }
     }
 
+    /// <summary>
+    /// Refreshes the property value with the value from the database
+    /// </summary>
+    /// <param name="propertyBase">Property</param>
+    /// <param name="value">New value from database</param>
+    /// <param name="mergeOption">MergeOption</param>
+    /// <param name="updateEntityState">Sets the EntityState to Unchanged if MergeOption.OverwriteChanges else calls ChangeDetector to determine changes</param>
+    public virtual void ReloadValue(IPropertyBase propertyBase, object? value, MergeOption mergeOption, bool updateEntityState)
+    {
+        var property = (IProperty)propertyBase;
+        EnsureOriginalValues();
+        bool isModified = IsModified(property);
+        _originalValues.SetValue(property, value, -1);
+        if (mergeOption == MergeOption.OverwriteChanges || !isModified)
+        {
+            SetProperty(propertyBase, value, isMaterialization: true, setModified: false);
+        }
+
+        if (updateEntityState)
+        {
+            if (mergeOption == MergeOption.OverwriteChanges)
+            {
+                SetEntityState(EntityState.Unchanged);
+            }
+            else if (StateManager is StateManager stateManager
+                     && stateManager.ChangeDetector is ChangeDetector changeDetector)
+            {
+                changeDetector.DetectValueChange(this, property);
+            }
+        }
+    }
+
     private void ReorderOriginalComplexCollectionEntries(IComplexProperty complexProperty, IList? newOriginalCollection)
     {
         Check.DebugAssert(HasOriginalValuesSnapshot, "This should only be called when original values are present");

src/EFCore/Extensions/EntityFrameworkQueryableExtensions.cs

@@ -3099,6 +3099,87 @@ public static IQueryable<TEntity> AsTracking<TEntity>(
 
     #endregion
 
+    #region Refreshing
+
+    internal static readonly MethodInfo RefreshMethodInfo
+    = typeof(EntityFrameworkQueryableExtensions).GetMethod(
+        nameof(Refresh), [typeof(IQueryable<>).MakeGenericType(Type.MakeGenericMethodParameter(0)), typeof(MergeOption)])!;
+
+
+    /// <summary>
+    /// Specifies that the current Entity Framework LINQ query should refresh already loaded objects with the specified merge option.
+    /// </summary>
+    /// <typeparam name="T">The type of entity being queried.</typeparam>
+    /// <param name="source">The source query.</param>
+    /// <param name="mergeOption">The MergeOption</param>
+    /// <returns>A new query annotated with the given tag.</returns>
+    public static IQueryable<T> Refresh<T>(
+        this IQueryable<T> source,
+        [NotParameterized] MergeOption mergeOption)
+    {
+        if (HasNonTrackingOrIgnoreAutoIncludes(source.Expression))
+        {
+            throw new InvalidOperationException(CoreStrings.RefreshNonTrackingQuery);
+        }
+
+        if (HasMultipleMergeOptions(source.Expression))
+        {
+            throw new InvalidOperationException(CoreStrings.RefreshMultipleMergeOptions);
+        }
+        return
+            source.Provider is EntityQueryProvider
+                ? source.Provider.CreateQuery<T>(
+                    Expression.Call(
+                        instance: null,
+                        method: RefreshMethodInfo.MakeGenericMethod(typeof(T)),
+                        arg0: source.Expression,
+                        arg1: Expression.Constant(mergeOption)))
+                : source;
+    }
+
+    private static bool HasNonTrackingOrIgnoreAutoIncludes(Expression expression)
+    {
+        Expression? current = expression;
+        while (current is MethodCallExpression call)
+        {
+            var method = call.Method;
+            if (method.DeclaringType == typeof(EntityFrameworkQueryableExtensions))
+            {
+                var name = method.Name;
+                if (name == nameof(AsNoTracking)
+                    || name == nameof(AsNoTrackingWithIdentityResolution)
+                    || name == nameof(IgnoreAutoIncludes))
+                {
+                    return true;
+                }
+            }
+
+            current = call.Arguments.Count > 0 ? call.Arguments[0] : null;
+        }
+
+        return false;
+    }
+
+    private static bool HasMultipleMergeOptions(Expression expression)
+    {
+        Expression? current = expression;
+        while (current is MethodCallExpression call)
+        {
+            var method = call.Method;
+            if (method.DeclaringType == typeof(EntityFrameworkQueryableExtensions)
+                && method.Name == nameof(Refresh))
+            {
+                return true;
+            }
+
+            current = call.Arguments.Count > 0 ? call.Arguments[0] : null;
+        }
+
+        return false;
+    }
+
+    #endregion
+
     #region Tagging
 
     /// <summary>

src/EFCore/MergeOption.cs

@@ -0,0 +1,27 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.EntityFrameworkCore;
+
+/// <summary>
+/// The different ways that new objects loaded from the database can be merged with existing objects already in memory.
+/// </summary>
+public enum MergeOption
+{
+    /// <summary>
+    /// Will only append new (top level-unique) rows.  This is the default behavior.
+    /// </summary>
+    AppendOnly = 0,
+
+    /// <summary>
+    /// The incoming values for this row will be written to both the current value and
+    /// the original value versions of the data for each column.
+    /// </summary>
+    OverwriteChanges = 1,
+
+    /// <summary>
+    /// The incoming values for this row will be written to the original value version
+    /// of each column. The current version of the data in each column will not be changed.
+    /// </summary>
+    PreserveChanges = 2
+}

src/EFCore/Properties/CoreStrings.resx

@@ -1577,6 +1577,12 @@
   <data name="ReferenceMustBeLoaded" xml:space="preserve">
     <value>The navigation '{1_entityType}.{0_navigation}' cannot have 'IsLoaded' set to false because the referenced entity is non-null and is therefore loaded.</value>
   </data>
+  <data name="RefreshMultipleMergeOptions" xml:space="preserve">
+    <value>The Refresh method can only be called once per query. Multiple merge options were specified.</value>
+  </data>
+  <data name="RefreshNonTrackingQuery" xml:space="preserve">
+    <value>The Refresh method requires a tracking query. Call AsTracking() before calling Refresh(), or use a context with tracking enabled by default.</value>
+  </data>
   <data name="RelationshipCannotBeInverted" xml:space="preserve">
     <value>The principal and dependent ends of the relationship cannot be changed once foreign key or principal key properties have been specified. Remove the conflicting configuration.</value>
   </data>

src/EFCore/Query/Internal/QueryableMethodNormalizingExpressionVisitor.cs

@@ -360,6 +360,14 @@ when methodCallExpression.Arguments is
                     _queryCompilationContext.IgnoreAutoIncludes = true;
                     return visitedExpression;
                 }
+
+                case nameof(EntityFrameworkQueryableExtensions.Refresh):
+                {
+                    var visitedExpression = Visit(methodCallExpression.Arguments[0]);
+                    _queryCompilationContext.RefreshMergeOption = methodCallExpression.Arguments[1].GetConstantValue<MergeOption>();
+                    return visitedExpression;
+                }
+
             }
         }
 

src/EFCore/Query/QueryCompilationContext.cs

@@ -136,6 +136,21 @@ public QueryCompilationContext(QueryCompilationContextDependencies dependencies,
     /// </summary>
     public virtual bool IgnoreAutoIncludes { get; internal set; }
 
+    /// <summary>
+    ///     <para>
+    ///         A value indicating how already loaded objects should be merged and refreshed with the results of this query.
+    ///     </para>
+    ///     <para>
+    ///         This property is typically used by database providers (and other extensions). It is generally
+    ///         not used in application code.
+    ///     </para>
+    /// </summary>
+    /// <remarks>
+    ///     See <see href="https://aka.ms/efcore-docs-providers">Implementation of database providers and extensions</see>
+    ///     and <see href="https://aka.ms/efcore-docs-how-query-works">How EF Core queries work</see> for more information and examples.
+    /// </remarks>
+    public virtual MergeOption RefreshMergeOption { get; internal set; }
+
     /// <summary>
     ///     The set of tags applied to this query.
     /// </summary>