New ChangeTracker events

- Tracking
- StateChanging
- DetectingChanges
- DetectedChanges

Part of #626
Fixes #27093
Fixes #16256

src/EFCore/ChangeTracking/ChangeTracker.cs

@@ -332,6 +332,16 @@ public virtual void TrackGraph<TState>(
 
  private IEntityEntryGraphIterator GraphIterator { get; }
 
+ /// <summary>
+ /// An event fired when an entity is about to be tracked by the context, either because it is returned
+ /// from a tracking query, or because it is being attached or added to the context.
+ /// </summary>
+ public event EventHandler<EntityTrackingEventArgs> Tracking
+ {
+ add => StateManager.Tracking += value;
+ remove => StateManager.Tracking -= value;
+ }
+
  /// <summary>
  /// An event fired when an entity is tracked by the context, either because it was returned
  /// from a tracking query, or because it was attached or added to the context.
@@ -342,6 +352,20 @@ public event EventHandler<EntityTrackedEventArgs> Tracked
  remove => StateManager.Tracked -= value;
  }
 
+ /// <summary>
+ /// An event fired when an entity that is tracked by the associated <see cref="DbContext" /> is moving
+ /// from one <see cref="EntityState" /> to another.
+ /// </summary>
+ /// <remarks>
+ /// Note that this event does not fire for entities when they are first tracked by the context.
+ /// Use the <see cref="Tracking" /> event to get notified when the context begins tracking an entity.
+ /// </remarks>
+ public event EventHandler<EntityStateChangingEventArgs> StateChanging
+ {
+ add => StateManager.StateChanging += value;
+ remove => StateManager.StateChanging -= value;
+ }
+
  /// <summary>
  /// An event fired when an entity that is tracked by the associated <see cref="DbContext" /> has moved
  /// from one <see cref="EntityState" /> to another.
@@ -356,6 +380,28 @@ public event EventHandler<EntityStateChangedEventArgs> StateChanged
  remove => StateManager.StateChanged -= value;
  }
 
+ /// <summary>
+ /// An event fired when detecting changes to the entity graph or a single entity is about to happen, either through an
+ /// explicit call to <see cref="DetectChanges" /> or <see cref="EntityEntry.DetectChanges" />, or automatically, such as part of
+ /// executing <see cref="DbContext.SaveChanges()" /> or <see cref="DbContext.SaveChangesAsync(System.Threading.CancellationToken)" />.
+ /// </summary>
+ public event EventHandler<DetectChangesEventArgs> DetectingChanges
+ {
+ add => ChangeDetector.DetectingChanges += value;
+ remove => ChangeDetector.DetectingChanges -= value;
+ }
+
+ /// <summary>
+ /// An event fired when any changes have been detected to the entity graph or a single entity, either through an
+ /// explicit call to <see cref="DetectChanges" /> or <see cref="EntityEntry.DetectChanges" />, or automatically, such as part of
+ /// executing <see cref="DbContext.SaveChanges()" /> or <see cref="DbContext.SaveChangesAsync(System.Threading.CancellationToken)" />.
+ /// </summary>
+ public event EventHandler<DetectedChangesEventArgs> DetectedChanges
+ {
+ add => ChangeDetector.DetectedChanges += value;
+ remove => ChangeDetector.DetectedChanges -= value;
+ }
+
  /// <summary>
  /// Forces immediate cascading deletion of child/dependent entities when they are either
  /// severed from a required parent/principal entity, or the required parent/principal entity

src/EFCore/ChangeTracking/DetectChangesEventArgs.cs

@@ -0,0 +1,39 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Microsoft.EntityFrameworkCore.ChangeTracking.Internal;
+
+namespace Microsoft.EntityFrameworkCore.ChangeTracking;
+
+/// <summary>
+/// Event arguments for the <see cref="ChangeTracker.DetectingChanges" /> event.
+/// </summary>
+/// <remarks>
+/// See <see href="https://aka.ms/efcore-docs-state-changes">State changes of entities in EF Core</see> for more information and examples.
+/// </remarks>
+public class DetectChangesEventArgs : EventArgs
+{
+ private readonly InternalEntityEntry? _internalEntityEntry;
+ private EntityEntry? _entry;
+
+ /// <summary>
+ /// This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+ /// the same compatibility standards as public APIs. It may be changed or removed without notice in
+ /// any release. You should only use it directly in your code with extreme caution and knowing that
+ /// doing so can result in application failures when updating to a new Entity Framework Core release.
+ /// </summary>
+ [EntityFrameworkInternal]
+ public DetectChangesEventArgs(InternalEntityEntry? internalEntityEntry)
+ {
+ _internalEntityEntry = internalEntityEntry;
+ }
+
+ /// <summary>
+ /// If detecting changes for a single entity, then this is the <see cref="EntityEntry" /> for that entity.
+ /// If detecting changes for an entire graph, then <see langword="null" />.
+ /// </summary>
+ public virtual EntityEntry? Entry
+ => _internalEntityEntry == null
+ ? null
+ : (_entry ??= new EntityEntry(_internalEntityEntry));
+}

src/EFCore/ChangeTracking/DetectedChangesEventArgs.cs

@@ -0,0 +1,35 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Microsoft.EntityFrameworkCore.ChangeTracking.Internal;
+
+namespace Microsoft.EntityFrameworkCore.ChangeTracking;
+
+/// <summary>
+/// Event arguments for the <see cref="ChangeTracker.DetectedChanges" /> event.
+/// </summary>
+/// <remarks>
+/// See <see href="https://aka.ms/efcore-docs-state-changes">State changes of entities in EF Core</see> for more information and examples.
+/// </remarks>
+public class DetectedChangesEventArgs : DetectChangesEventArgs
+{
+ /// <summary>
+ /// This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+ /// the same compatibility standards as public APIs. It may be changed or removed without notice in
+ /// any release. You should only use it directly in your code with extreme caution and knowing that
+ /// doing so can result in application failures when updating to a new Entity Framework Core release.
+ /// </summary>
+ [EntityFrameworkInternal]
+ public DetectedChangesEventArgs(
+ InternalEntityEntry? internalEntityEntry,
+ bool changesFound)
+ : base(internalEntityEntry)
+ {
+ ChangesFound = changesFound;
+ }
+
+ /// <summary>
+ /// Returns <see langword="true" /> if changes were found, <see langword="false" /> otherwise.
+ /// </summary>
+ public virtual bool ChangesFound { get; }
+}

src/EFCore/ChangeTracking/EntityStateChangingEventArgs.cs

@@ -0,0 +1,42 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Microsoft.EntityFrameworkCore.ChangeTracking.Internal;
+
+namespace Microsoft.EntityFrameworkCore.ChangeTracking;
+
+/// <summary>
+/// Event arguments for the <see cref="ChangeTracker.StateChanging" /> event.
+/// </summary>
+/// <remarks>
+/// See <see href="https://aka.ms/efcore-docs-state-changes">State changes of entities in EF Core</see> for more information and examples.
+/// </remarks>
+public class EntityStateChangingEventArgs : EntityEntryEventArgs
+{
+ /// <summary>
+ /// This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+ /// the same compatibility standards as public APIs. It may be changed or removed without notice in
+ /// any release. You should only use it directly in your code with extreme caution and knowing that
+ /// doing so can result in application failures when updating to a new Entity Framework Core release.
+ /// </summary>
+ [EntityFrameworkInternal]
+ public EntityStateChangingEventArgs(
+ InternalEntityEntry internalEntityEntry,
+ EntityState oldState,
+ EntityState newState)
+ : base(internalEntityEntry)
+ {
+ OldState = oldState;
+ NewState = newState;
+ }
+
+ /// <summary>
+ /// The state that the entity is transitioning from.
+ /// </summary>
+ public virtual EntityState OldState { get; }
+
+ /// <summary>
+ /// The state that the entity is transitioning to.
+ /// </summary>
+ public virtual EntityState NewState { get; }
+}

src/EFCore/ChangeTracking/EntityTrackingEventArgs.cs

@@ -0,0 +1,42 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Microsoft.EntityFrameworkCore.ChangeTracking.Internal;
+
+namespace Microsoft.EntityFrameworkCore.ChangeTracking;
+
+/// <summary>
+/// Event arguments for the <see cref="ChangeTracker.Tracking" /> event.
+/// </summary>
+/// <remarks>
+/// See <see href="https://aka.ms/efcore-docs-state-changes">State changes of entities in EF Core</see> for more information and examples.
+/// </remarks>
+public class EntityTrackingEventArgs : EntityEntryEventArgs
+{
+ /// <summary>
+ /// This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+ /// the same compatibility standards as public APIs. It may be changed or removed without notice in
+ /// any release. You should only use it directly in your code with extreme caution and knowing that
+ /// doing so can result in application failures when updating to a new Entity Framework Core release.
+ /// </summary>
+ [EntityFrameworkInternal]
+ public EntityTrackingEventArgs(
+ InternalEntityEntry internalEntityEntry,
+ EntityState state,
+ bool fromQuery)
+ : base(internalEntityEntry)
+ {
+ State = state;
+ FromQuery = fromQuery;
+ }
+
+ /// <summary>
+ /// The <see cref="EntityState" /> that the tracked entity will be tracked with.
+ /// </summary>
+ public virtual EntityState State { get; }
+
+ /// <summary>
+ /// <see langword="true" /> if the entity is being tracked as part of a database query; <see langword="false" /> otherwise.
+ /// </summary>
+ public virtual bool FromQuery { get; }
+}