API review: add interception for DbCommand creation

src/EFCore.Relational/Diagnostics/CommandCorrelatedEventData.cs

@@ -0,0 +1,78 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+using System;
+using System.Data.Common;
+using System.Diagnostics;
+using JetBrains.Annotations;
+
+namespace Microsoft.EntityFrameworkCore.Diagnostics
+{
+    /// <summary>
+    ///     The <see cref="DiagnosticSource" /> event payload for events correlated with a <see cref="DbCommand"/>.
+    /// </summary>
+    public class CommandCorrelatedEventData : DbContextEventData
+    {
+        /// <summary>
+        ///     Constructs the event payload.
+        /// </summary>
+        /// <param name="eventDefinition"> The event definition. </param>
+        /// <param name="messageGenerator"> A delegate that generates a log message for this event. </param>
+        /// <param name="connection"> The <see cref="DbConnection"/> being used. </param>
+        /// <param name="context"> The <see cref="DbContext" /> currently being used, to null if not known. </param>
+        /// <param name="executeMethod"> The <see cref="DbCommand" /> method. </param>
+        /// <param name="commandId"> A correlation ID that identifies the <see cref="DbCommand" /> instance being used. </param>
+        /// <param name="connectionId"> A correlation ID that identifies the <see cref="DbConnection" /> instance being used. </param>
+        /// <param name="async"> Indicates whether or not the command was executed asynchronously. </param>
+        /// <param name="startTime"> The start time of this event. </param>
+        public CommandCorrelatedEventData(
+            [NotNull] EventDefinitionBase eventDefinition,
+            [NotNull] Func<EventDefinitionBase, EventData, string> messageGenerator,
+            [NotNull] DbConnection connection,
+            [CanBeNull] DbContext context,
+            DbCommandMethod executeMethod,
+            Guid commandId,
+            Guid connectionId,
+            bool async,
+            DateTimeOffset startTime)
+            : base(eventDefinition, messageGenerator, context)
+        {
+            Connection = connection;
+            CommandId = commandId;
+            ConnectionId = connectionId;
+            ExecuteMethod = executeMethod;
+            IsAsync = async;
+            StartTime = startTime;
+        }
+
+        /// <summary>
+        ///     The <see cref="DbConnection" />.
+        /// </summary>
+        public virtual DbConnection Connection { get; }
+
+        /// <summary>
+        ///     A correlation ID that identifies the <see cref="DbCommand" /> instance being used.
+        /// </summary>
+        public virtual Guid CommandId { get; }
+
+        /// <summary>
+        ///     A correlation ID that identifies the <see cref="DbConnection" /> instance being used.
+        /// </summary>
+        public virtual Guid ConnectionId { get; }
+
+        /// <summary>
+        ///     The <see cref="DbCommandMethod" /> method.
+        /// </summary>
+        public virtual DbCommandMethod ExecuteMethod { get; }
+
+        /// <summary>
+        ///     Indicates whether or not the operation is being executed asynchronously.
+        /// </summary>
+        public virtual bool IsAsync { get; }
+
+        /// <summary>
+        ///     The start time of this event.
+        /// </summary>
+        public virtual DateTimeOffset StartTime { get; }
+    }
+}

src/EFCore.Relational/Diagnostics/CommandEndEventData.cs

@@ -19,6 +19,7 @@ public class CommandEndEventData : CommandEventData
         /// </summary>
         /// <param name="eventDefinition"> The event definition. </param>
         /// <param name="messageGenerator"> A delegate that generates a log message for this event. </param>
+        /// <param name="connection"> The <see cref="DbConnection"/> being used. </param>
         /// <param name="command"> The <see cref="DbCommand" />. </param>
         /// <param name="context"> The <see cref="DbContext" /> currently being used, to null if not known. </param>
         /// <param name="executeMethod"> The <see cref="DbCommand" /> method. </param>
@@ -31,6 +32,7 @@ public class CommandEndEventData : CommandEventData
         public CommandEndEventData(
             [NotNull] EventDefinitionBase eventDefinition,
             [NotNull] Func<EventDefinitionBase, EventData, string> messageGenerator,
+            [NotNull] DbConnection connection,
             [NotNull] DbCommand command,
             [CanBeNull] DbContext context,
             DbCommandMethod executeMethod,
@@ -43,6 +45,7 @@ public CommandEndEventData(
             : base(
                 eventDefinition,
                 messageGenerator,
+                connection,
                 command,
                 context,
                 executeMethod,

src/EFCore.Relational/Diagnostics/CommandErrorEventData.cs

@@ -18,6 +18,7 @@ public class CommandErrorEventData : CommandEndEventData, IErrorEventData
         /// </summary>
         /// <param name="eventDefinition"> The event definition. </param>
         /// <param name="messageGenerator"> A delegate that generates a log message for this event. </param>
+        /// <param name="connection"> The <see cref="DbConnection"/> being used. </param>
         /// <param name="command"> The <see cref="DbCommand" /> that was executing when it failed. </param>
         /// <param name="context"> The <see cref="DbContext" /> currently being used, to null if not known. </param>
         /// <param name="executeMethod"> The <see cref="DbCommand" /> method that was used to execute the command. </param>
@@ -31,6 +32,7 @@ public class CommandErrorEventData : CommandEndEventData, IErrorEventData
         public CommandErrorEventData(
             [NotNull] EventDefinitionBase eventDefinition,
             [NotNull] Func<EventDefinitionBase, EventData, string> messageGenerator,
+            [NotNull] DbConnection connection,
             [NotNull] DbCommand command,
             [CanBeNull] DbContext context,
             DbCommandMethod executeMethod,
@@ -44,6 +46,7 @@ public CommandErrorEventData(
             : base(
                 eventDefinition,
                 messageGenerator,
+                connection,
                 command,
                 context,
                 executeMethod,

src/EFCore.Relational/Diagnostics/CommandEventData.cs

@@ -12,13 +12,14 @@ namespace Microsoft.EntityFrameworkCore.Diagnostics
     ///     The <see cref="DiagnosticSource" /> event payload for
     ///     <see cref="RelationalEventId" /> command events.
     /// </summary>
-    public class CommandEventData : DbContextEventData
+    public class CommandEventData : CommandCorrelatedEventData
     {
         /// <summary>
         ///     Constructs the event payload.
         /// </summary>
         /// <param name="eventDefinition"> The event definition. </param>
         /// <param name="messageGenerator"> A delegate that generates a log message for this event. </param>
+        /// <param name="connection"> The <see cref="DbConnection"/> being used. </param>
         /// <param name="command"> The <see cref="DbCommand" />. </param>
         /// <param name="context"> The <see cref="DbContext" /> currently being used, to null if not known. </param>
         /// <param name="executeMethod"> The <see cref="DbCommand" /> method. </param>
@@ -30,6 +31,7 @@ public class CommandEventData : DbContextEventData
         public CommandEventData(
             [NotNull] EventDefinitionBase eventDefinition,
             [NotNull] Func<EventDefinitionBase, EventData, string> messageGenerator,
+            [NotNull] DbConnection connection,
             [NotNull] DbCommand command,
             [CanBeNull] DbContext context,
             DbCommandMethod executeMethod,
@@ -38,50 +40,29 @@ public CommandEventData(
             bool async,
             bool logParameterValues,
             DateTimeOffset startTime)
-            : base(eventDefinition, messageGenerator, context)
+            : base(
+                eventDefinition,
+                messageGenerator,
+                connection,
+                context,
+                executeMethod,
+                commandId,
+                connectionId,
+                async,
+                startTime)
         {
             Command = command;
-            CommandId = commandId;
-            ConnectionId = connectionId;
-            ExecuteMethod = executeMethod;
-            IsAsync = async;
             LogParameterValues = logParameterValues;
-            StartTime = startTime;
         }
 
         /// <summary>
         ///     The <see cref="DbCommand" />.
         /// </summary>
         public virtual DbCommand Command { get; }
 
-        /// <summary>
-        ///     A correlation ID that identifies the <see cref="DbCommand" /> instance being used.
-        /// </summary>
-        public virtual Guid CommandId { get; }
-
-        /// <summary>
-        ///     A correlation ID that identifies the <see cref="DbConnection" /> instance being used.
-        /// </summary>
-        public virtual Guid ConnectionId { get; }
-
-        /// <summary>
-        ///     The <see cref="DbCommand" /> method.
-        /// </summary>
-        public virtual DbCommandMethod ExecuteMethod { get; }
-
-        /// <summary>
-        ///     Indicates whether or not the operation is being executed asynchronously.
-        /// </summary>
-        public virtual bool IsAsync { get; }
-
         /// <summary>
         ///     Indicates whether or not the application allows logging of parameter values.
         /// </summary>
         public virtual bool LogParameterValues { get; }
-
-        /// <summary>
-        ///     The start time of this event.
-        /// </summary>
-        public virtual DateTimeOffset StartTime { get; }
     }
 }

src/EFCore.Relational/Diagnostics/CommandExecutedEventData.cs

@@ -18,6 +18,7 @@ public class CommandExecutedEventData : CommandEndEventData
         /// </summary>
         /// <param name="eventDefinition"> The event definition. </param>
         /// <param name="messageGenerator"> A delegate that generates a log message for this event. </param>
+        /// <param name="connection"> The <see cref="DbConnection"/> being used. </param>
         /// <param name="command"> The <see cref="DbCommand" /> that was executing when it failed. </param>
         /// <param name="context"> The <see cref="DbContext" /> currently being used, to null if not known. </param>
         /// <param name="executeMethod"> The <see cref="DbCommand" /> method that was used to execute the command. </param>
@@ -31,6 +32,7 @@ public class CommandExecutedEventData : CommandEndEventData
         public CommandExecutedEventData(
             [NotNull] EventDefinitionBase eventDefinition,
             [NotNull] Func<EventDefinitionBase, EventData, string> messageGenerator,
+            [NotNull] DbConnection connection,
             [NotNull] DbCommand command,
             [CanBeNull] DbContext context,
             DbCommandMethod executeMethod,
@@ -44,6 +46,7 @@ public CommandExecutedEventData(
             : base(
                 eventDefinition,
                 messageGenerator,
+                connection,
                 command,
                 context,
                 executeMethod,

src/EFCore.Relational/Diagnostics/DbCommandInterceptor.cs

@@ -15,6 +15,48 @@ namespace Microsoft.EntityFrameworkCore.Diagnostics
     /// </summary>
     public abstract class DbCommandInterceptor : IDbCommandInterceptor
     {
+        /// <summary>
+        ///     Called just before EF intends to call <see cref="DbConnection.CreateCommand"/>.
+        /// </summary>
+        /// <param name="eventData"> Contextual information about the command and execution. </param>
+        /// <param name="result">
+        ///     Represents the current result if one exists.
+        ///     This value will have <see cref="InterceptionResult{DbCommand}.HasResult"/> set to true if some previous
+        ///     interceptor suppressed execution by calling <see cref="InterceptionResult{DbCommand}.SuppressWithResult"/>.
+        ///     This value is typically used as the return value for the implementation of this method.
+        /// </param>
+        /// <returns>
+        ///     If <see cref="InterceptionResult{DbCommand}.HasResult"/> is false, the EF will continue as normal.
+        ///     If <see cref="InterceptionResult{DbCommand}.HasResult"/> is true, then EF will suppress the operation it
+        ///     was about to perform and use <see cref="InterceptionResult{DbCommand}.Result"/> instead.
+        ///     A normal implementation of this method for any interceptor that is not attempting to change the result
+        ///     is to return the <paramref name="result" /> value passed in.
+        /// </returns>
+        public virtual InterceptionResult<DbCommand> CommandCreating(CommandCorrelatedEventData eventData, InterceptionResult<DbCommand> result)
+            => result;
+
+        /// <summary>
+        ///     <para>
+        ///         Called immediately after EF calls <see cref="DbConnection.CreateCommand"/>.
+        ///     </para>
+        ///     <para>
+        ///         This method is still called if an interceptor suppressed creation of a command in <see cref="IDbCommandInterceptor.CommandCreating" />.
+        ///         In this case, <paramref name="result" /> is the result returned by <see cref="IDbCommandInterceptor.CommandCreating" />.
+        ///     </para>
+        /// </summary>
+        /// <param name="eventData"> Contextual information about the command and execution. </param>
+        /// <param name="result">
+        ///     The result of the call to <see cref="DbConnection.CreateCommand" />.
+        ///     This value is typically used as the return value for the implementation of this method.
+        /// </param>
+        /// <returns>
+        ///     The result that EF will use.
+        ///     A normal implementation of this method for any interceptor that is not attempting to change the result
+        ///     is to return the <paramref name="result" /> value passed in.
+        /// </returns>
+        public virtual DbCommand CommandCreated(CommandEndEventData eventData, DbCommand result)
+            => result;
+
         /// <summary>
         ///     Called just before EF intends to call <see cref="DbCommand.ExecuteReader()" />.
         /// </summary>
@@ -37,9 +79,7 @@ public virtual InterceptionResult<DbDataReader> ReaderExecuting(
             DbCommand command,
             CommandEventData eventData,
             InterceptionResult<DbDataReader> result)
-        {
-            return result;
-        }
+            => result;
 
         /// <summary>
         ///     Called just before EF intends to call <see cref="DbCommand.ExecuteScalar()" />.
@@ -62,7 +102,8 @@ public virtual InterceptionResult<DbDataReader> ReaderExecuting(
         public virtual InterceptionResult<object> ScalarExecuting(
             DbCommand command,
             CommandEventData eventData,
-            InterceptionResult<object> result) => result;
+            InterceptionResult<object> result)
+            => result;
 
         /// <summary>
         ///     Called just before EF intends to call <see cref="DbCommand.ExecuteNonQuery()" />.

src/EFCore.Relational/Diagnostics/IDbCommandInterceptor.cs

@@ -31,6 +31,50 @@ namespace Microsoft.EntityFrameworkCore.Diagnostics
     /// </summary>
     public interface IDbCommandInterceptor : IInterceptor
     {
+        /// <summary>
+        ///     Called just before EF intends to call <see cref="DbConnection.CreateCommand"/>.
+        /// </summary>
+        /// <param name="eventData"> Contextual information about the command and execution. </param>
+        /// <param name="result">
+        ///     Represents the current result if one exists.
+        ///     This value will have <see cref="InterceptionResult{DbCommand}.HasResult"/> set to true if some previous
+        ///     interceptor suppressed execution by calling <see cref="InterceptionResult{DbCommand}.SuppressWithResult"/>.
+        ///     This value is typically used as the return value for the implementation of this method.
+        /// </param>
+        /// <returns>
+        ///     If <see cref="InterceptionResult{DbCommand}.HasResult"/> is false, the EF will continue as normal.
+        ///     If <see cref="InterceptionResult{DbCommand}.HasResult"/> is true, then EF will suppress the operation it
+        ///     was about to perform and use <see cref="InterceptionResult{DbCommand}.Result"/> instead.
+        ///     A normal implementation of this method for any interceptor that is not attempting to change the result
+        ///     is to return the <paramref name="result" /> value passed in.
+        /// </returns>
+        InterceptionResult<DbCommand> CommandCreating(
+            [NotNull] CommandCorrelatedEventData eventData,
+            InterceptionResult<DbCommand> result);
+
+        /// <summary>
+        ///     <para>
+        ///         Called immediately after EF calls <see cref="DbConnection.CreateCommand"/>.
+        ///     </para>
+        ///     <para>
+        ///         This method is still called if an interceptor suppressed creation of a command in <see cref="CommandCreating" />.
+        ///         In this case, <paramref name="result" /> is the result returned by <see cref="CommandCreating" />.
+        ///     </para>
+        /// </summary>
+        /// <param name="eventData"> Contextual information about the command and execution. </param>
+        /// <param name="result">
+        ///     The result of the call to <see cref="DbConnection.CreateCommand" />.
+        ///     This value is typically used as the return value for the implementation of this method.
+        /// </param>
+        /// <returns>
+        ///     The result that EF will use.
+        ///     A normal implementation of this method for any interceptor that is not attempting to change the result
+        ///     is to return the <paramref name="result" /> value passed in.
+        /// </returns>
+        DbCommand CommandCreated(
+            [NotNull] CommandEndEventData eventData,
+            [NotNull] DbCommand result);
+
         /// <summary>
         ///     Called just before EF intends to call <see cref="DbCommand.ExecuteReader()" />.
         /// </summary>

src/EFCore.Relational/Diagnostics/Internal/DbCommandInterceptorAggregator.cs

@@ -36,6 +36,30 @@ public CompositeDbCommandInterceptor([NotNull] IEnumerable<IDbCommandInterceptor
                 _interceptors = interceptors.ToArray();
             }
 
+            public InterceptionResult<DbCommand> CommandCreating(
+                CommandCorrelatedEventData eventData,
+                InterceptionResult<DbCommand> result)
+            {
+                for (var i = 0; i < _interceptors.Length; i++)
+                {
+                    result = _interceptors[i].CommandCreating(eventData, result);
+                }
+
+                return result;
+            }
+
+            public DbCommand CommandCreated(
+                CommandEndEventData eventData,
+                DbCommand result)
+            {
+                for (var i = 0; i < _interceptors.Length; i++)
+                {
+                    result = _interceptors[i].CommandCreated(eventData, result);
+                }
+
+                return result;
+            }
+
             public InterceptionResult<DbDataReader> ReaderExecuting(
                 DbCommand command,
                 CommandEventData eventData,