Interface IDbCommandInterceptor

Namespace

Microsoft.EntityFrameworkCore.Diagnostics

Assembly

Microsoft.EntityFrameworkCore.Relational.dll

Allows interception of commands sent to a relational database.

Command interceptors can be used to view, change, or suppress execution of the DbCommand, and to modify the result before it is returned to EF.

Consider inheriting from DbCommandInterceptor if not implementing all methods.

Use Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.AddInterceptors(Microsoft.EntityFrameworkCore.Diagnostics.IInterceptor[]) to register application interceptors.

Extensions can also register interceptors in the internal service provider. If both injected and application interceptors are found, then the injected interceptors are run in the order that they are resolved from the service provider, and then the application interceptors are run last.

public interface IDbCommandInterceptor : IInterceptor

Methods

CommandCreated(CommandEndEventData, DbCommand)

Called immediately after EF calls CreateCommand().

This method is still called if an interceptor suppressed creation of a command in CommandCreating(CommandCorrelatedEventData, InterceptionResult<DbCommand>). In this case, result is the result returned by CommandCreating(CommandCorrelatedEventData, InterceptionResult<DbCommand>).

DbCommand CommandCreated(CommandEndEventData eventData, DbCommand result)

Parameters

eventData CommandEndEventData

Contextual information about the command and execution.

result DbCommand

The result of the call to CreateCommand(). This value is typically used as the return value for the implementation of this method.

Returns

DbCommand

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 result value passed in.

CommandCreating(CommandCorrelatedEventData, InterceptionResult<DbCommand>)

Called just before EF intends to call CreateCommand().

InterceptionResult<DbCommand> CommandCreating(CommandCorrelatedEventData eventData, InterceptionResult<DbCommand> result)

Parameters

eventData CommandCorrelatedEventData

Contextual information about the command and execution.

result InterceptionResult<DbCommand>

Represents the current result if one exists. This value will have Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult set to true if some previous interceptor suppressed execution by calling Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.SuppressWithResult(`0). This value is typically used as the return value for the implementation of this method.

Returns

InterceptionResult<DbCommand>

If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult is false, the EF will continue as normal. If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult is true, then EF will suppress the operation it was about to perform and use Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.Result instead. A normal implementation of this method for any interceptor that is not attempting to change the result is to return the result value passed in.

CommandFailed(DbCommand, CommandErrorEventData)

Called when execution of a command has failed with an exception.

void CommandFailed(DbCommand command, CommandErrorEventData eventData)

Parameters

command DbCommand

The command.

eventData CommandErrorEventData

Contextual information about the command and execution.

CommandFailedAsync(DbCommand, CommandErrorEventData, CancellationToken)

Called when execution of a command has failed with an exception.

Task CommandFailedAsync(DbCommand command, CommandErrorEventData eventData, CancellationToken cancellationToken = default)

Parameters

command DbCommand

The command.

eventData CommandErrorEventData

Contextual information about the command and execution.

cancellationToken CancellationToken

The cancellation token.

Returns

Task

A Task representing the asynchronous operation.

DataReaderDisposing(DbCommand, DataReaderDisposingEventData, InterceptionResult)

Called when execution of a DbDataReader is about to be disposed.

InterceptionResult DataReaderDisposing(DbCommand command, DataReaderDisposingEventData eventData, InterceptionResult result)

Parameters

command DbCommand

The command.

eventData DataReaderDisposingEventData

Contextual information about the command and reader.

result InterceptionResult

Represents the current result if one exists. This value will have Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult.IsSuppressed set to true if some previous interceptor suppressed execution by calling Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult.Suppress. This value is typically used as the return value for the implementation of this method.

Returns

InterceptionResult

If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult.IsSuppressed is false, the EF will continue as normal. If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult.IsSuppressed is true, then EF will suppress the operation it was about to perform. A normal implementation of this method for any interceptor that is not attempting to suppress the operation is to return the result value passed in.

NonQueryExecuted(DbCommand, CommandExecutedEventData, int)

Called immediately after EF calls ExecuteNonQuery().

This method is still called if an interceptor suppressed execution of a command in NonQueryExecuting(DbCommand, CommandEventData, InterceptionResult<int>). In this case, result is the result returned by NonQueryExecuting(DbCommand, CommandEventData, InterceptionResult<int>).

int NonQueryExecuted(DbCommand command, CommandExecutedEventData eventData, int result)

Parameters

command DbCommand

The command.

eventData CommandExecutedEventData

Contextual information about the command and execution.

result int

The result of the call to ExecuteNonQuery(). This value is typically used as the return value for the implementation of this method.

Returns

int

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 result value passed in.

NonQueryExecutedAsync(DbCommand, CommandExecutedEventData, int, CancellationToken)

Called immediately after EF calls ExecuteNonQueryAsync().

This method is still called if an interceptor suppressed execution of a command in NonQueryExecutingAsync(DbCommand, CommandEventData, InterceptionResult<int>, CancellationToken). In this case, result is the result returned by NonQueryExecutingAsync(DbCommand, CommandEventData, InterceptionResult<int>, CancellationToken).

ValueTask<int> NonQueryExecutedAsync(DbCommand command, CommandExecutedEventData eventData, int result, CancellationToken cancellationToken = default)

Parameters

command DbCommand

The command.

eventData CommandExecutedEventData

Contextual information about the command and execution.

result int

The result of the call to ExecuteNonQueryAsync(). This value is typically used as the return value for the implementation of this method.

cancellationToken CancellationToken

The cancellation token.

Returns

ValueTask<int>

A Task providing 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 result value passed in, often using FromResult<TResult>(TResult)

NonQueryExecuting(DbCommand, CommandEventData, InterceptionResult<int>)

Called just before EF intends to call ExecuteNonQuery().

InterceptionResult<int> NonQueryExecuting(DbCommand command, CommandEventData eventData, InterceptionResult<int> result)

Parameters

command DbCommand

The command.

eventData CommandEventData

Contextual information about the command and execution.

result InterceptionResult<int>

Represents the current result if one exists. This value will have Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult set to true if some previous interceptor suppressed execution by calling Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.SuppressWithResult(`0). This value is typically used as the return value for the implementation of this method.

Returns

InterceptionResult<int>

If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult is false, the EF will continue as normal. If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult is true, then EF will suppress the operation it was about to perform and use Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.Result instead. A normal implementation of this method for any interceptor that is not attempting to change the result is to return the result value passed in.

NonQueryExecutingAsync(DbCommand, CommandEventData, InterceptionResult<int>, CancellationToken)

Called just before EF intends to call ExecuteNonQueryAsync().

ValueTask<InterceptionResult<int>> NonQueryExecutingAsync(DbCommand command, CommandEventData eventData, InterceptionResult<int> result, CancellationToken cancellationToken = default)

Parameters

command DbCommand

The command.

eventData CommandEventData

Contextual information about the command and execution.

result InterceptionResult<int>

Represents the current result if one exists. This value will have Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult set to true if some previous interceptor suppressed execution by calling Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.SuppressWithResult(`0). This value is typically used as the return value for the implementation of this method.

cancellationToken CancellationToken

The cancellation token.

Returns

ValueTask<InterceptionResult<int>>

If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult is false, the EF will continue as normal. If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult is true, then EF will suppress the operation it was about to perform and use Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.Result instead. A normal implementation of this method for any interceptor that is not attempting to change the result is to return the result value passed in, often using FromResult<TResult>(TResult)

ReaderExecuted(DbCommand, CommandExecutedEventData, DbDataReader)

Called immediately after EF calls ExecuteReader().

This method is still called if an interceptor suppressed execution of a command in ReaderExecuting(DbCommand, CommandEventData, InterceptionResult<DbDataReader>). In this case, result is the result returned by ReaderExecuting(DbCommand, CommandEventData, InterceptionResult<DbDataReader>).

DbDataReader ReaderExecuted(DbCommand command, CommandExecutedEventData eventData, DbDataReader result)

Parameters

command DbCommand

The command.

eventData CommandExecutedEventData

Contextual information about the command and execution.

result DbDataReader

The result of the call to ExecuteReader(). This value is typically used as the return value for the implementation of this method.

Returns

DbDataReader

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 result value passed in.

ReaderExecutedAsync(DbCommand, CommandExecutedEventData, DbDataReader, CancellationToken)

Called immediately after EF calls ExecuteReaderAsync().

This method is still called if an interceptor suppressed execution of a command in ReaderExecutingAsync(DbCommand, CommandEventData, InterceptionResult<DbDataReader>, CancellationToken). In this case, result is the result returned by ReaderExecutingAsync(DbCommand, CommandEventData, InterceptionResult<DbDataReader>, CancellationToken).

ValueTask<DbDataReader> ReaderExecutedAsync(DbCommand command, CommandExecutedEventData eventData, DbDataReader result, CancellationToken cancellationToken = default)

Parameters

command DbCommand

The command.

eventData CommandExecutedEventData

Contextual information about the command and execution.

result DbDataReader

The result of the call to ExecuteReaderAsync(). This value is typically used as the return value for the implementation of this method.

cancellationToken CancellationToken

The cancellation token.

Returns

ValueTask<DbDataReader>

A Task providing 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 result value passed in, often using FromResult<TResult>(TResult)

ReaderExecuting(DbCommand, CommandEventData, InterceptionResult<DbDataReader>)

Called just before EF intends to call ExecuteReader().

InterceptionResult<DbDataReader> ReaderExecuting(DbCommand command, CommandEventData eventData, InterceptionResult<DbDataReader> result)

Parameters

command DbCommand

The command.

eventData CommandEventData

Contextual information about the command and execution.

result InterceptionResult<DbDataReader>

Represents the current result if one exists. This value will have Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult set to true if some previous interceptor suppressed execution by calling Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.SuppressWithResult(`0). This value is typically used as the return value for the implementation of this method.

Returns

InterceptionResult<DbDataReader>

If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult is false, the EF will continue as normal. If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult is true, then EF will suppress the operation it was about to perform and use Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.Result instead. A normal implementation of this method for any interceptor that is not attempting to change the result is to return the result value passed in.

ReaderExecutingAsync(DbCommand, CommandEventData, InterceptionResult<DbDataReader>, CancellationToken)

Called just before EF intends to call ExecuteReaderAsync().

ValueTask<InterceptionResult<DbDataReader>> ReaderExecutingAsync(DbCommand command, CommandEventData eventData, InterceptionResult<DbDataReader> result, CancellationToken cancellationToken = default)

Parameters

command DbCommand

The command.

eventData CommandEventData

Contextual information about the command and execution.

result InterceptionResult<DbDataReader>

Represents the current result if one exists. This value will have Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult set to true if some previous interceptor suppressed execution by calling Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.SuppressWithResult(`0). This value is typically used as the return value for the implementation of this method.

cancellationToken CancellationToken

The cancellation token.

Returns

ValueTask<InterceptionResult<DbDataReader>>

If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult is false, the EF will continue as normal. If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult is true, then EF will suppress the operation it was about to perform and use Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.Result instead. A normal implementation of this method for any interceptor that is not attempting to change the result is to return the result value passed in, often using FromResult<TResult>(TResult)

ScalarExecuted(DbCommand, CommandExecutedEventData, object)

Called immediately after EF calls ExecuteScalar().

This method is still called if an interceptor suppressed execution of a command in ScalarExecuting(DbCommand, CommandEventData, InterceptionResult<object>). In this case, result is the result returned by ScalarExecuting(DbCommand, CommandEventData, InterceptionResult<object>).

object ScalarExecuted(DbCommand command, CommandExecutedEventData eventData, object result)

Parameters

command DbCommand

The command.

eventData CommandExecutedEventData

Contextual information about the command and execution.

result object

The result of the call to ExecuteScalar(). This value is typically used as the return value for the implementation of this method.

Returns

object

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 result value passed in.

ScalarExecutedAsync(DbCommand, CommandExecutedEventData, object, CancellationToken)

Called immediately after EF calls ExecuteScalarAsync().

This method is still called if an interceptor suppressed execution of a command in ScalarExecutingAsync(DbCommand, CommandEventData, InterceptionResult<object>, CancellationToken). In this case, result is the result returned by ScalarExecutingAsync(DbCommand, CommandEventData, InterceptionResult<object>, CancellationToken).

ValueTask<object> ScalarExecutedAsync(DbCommand command, CommandExecutedEventData eventData, object result, CancellationToken cancellationToken = default)

Parameters

command DbCommand

The command.

eventData CommandExecutedEventData

Contextual information about the command and execution.

result object

The result of the call to ExecuteScalarAsync(). This value is typically used as the return value for the implementation of this method.

cancellationToken CancellationToken

The cancellation token.

Returns

ValueTask<object>

A Task providing 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 result value passed in, often using FromResult<TResult>(TResult)

ScalarExecuting(DbCommand, CommandEventData, InterceptionResult<object>)

Called just before EF intends to call ExecuteScalar().

InterceptionResult<object> ScalarExecuting(DbCommand command, CommandEventData eventData, InterceptionResult<object> result)

Parameters

command DbCommand

The command.

eventData CommandEventData

Contextual information about the command and execution.

result InterceptionResult<object>

Represents the current result if one exists. This value will have Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult set to true if some previous interceptor suppressed execution by calling Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.SuppressWithResult(`0). This value is typically used as the return value for the implementation of this method.

Returns

InterceptionResult<object>

If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult is false, the EF will continue as normal. If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult is true, then EF will suppress the operation it was about to perform and use Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.Result instead. A normal implementation of this method for any interceptor that is not attempting to change the result is to return the result value passed in.

ScalarExecutingAsync(DbCommand, CommandEventData, InterceptionResult<object>, CancellationToken)

Called just before EF intends to call ExecuteScalarAsync().

ValueTask<InterceptionResult<object>> ScalarExecutingAsync(DbCommand command, CommandEventData eventData, InterceptionResult<object> result, CancellationToken cancellationToken = default)

Parameters

command DbCommand

The command.

eventData CommandEventData

Contextual information about the command and execution.

result InterceptionResult<object>

Represents the current result if one exists. This value will have Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult set to true if some previous interceptor suppressed execution by calling Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.SuppressWithResult(`0). This value is typically used as the return value for the implementation of this method.

cancellationToken CancellationToken

The cancellation token.

Returns

ValueTask<InterceptionResult<object>>

If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult is false, the EF will continue as normal. If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult is true, then EF will suppress the operation it was about to perform and use Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.Result instead. A normal implementation of this method for any interceptor that is not attempting to change the result is to return the result value passed in, often using FromResult<TResult>(TResult)