Interface IDbCommandInterceptor

Namespace

Microsoft.EntityFrameworkCore.Diagnostics

Assembly

Microsoft.EntityFrameworkCore.Relational.dll

Allows interception of commands sent to a relational database.

public interface IDbCommandInterceptor : IInterceptor

Remarks

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.

See EF Core interceptors for more information and examples.

Methods

CommandCanceled(DbCommand, CommandEndEventData)

Called when a command was canceled.

void CommandCanceled(DbCommand command, CommandEndEventData eventData)

Parameters

command DbCommand

The command.

eventData CommandEndEventData

Contextual information about the command and execution.

CommandCanceledAsync(DbCommand, CommandEndEventData, CancellationToken)

Called when a command was canceled.

Task CommandCanceledAsync(DbCommand command, CommandEndEventData eventData, CancellationToken cancellationToken = default)

Parameters

command DbCommand

The command.

eventData CommandEndEventData

Contextual information about the command and execution.

cancellationToken CancellationToken

A CancellationToken to observe while waiting for the task to complete.

Returns

Task

A Task representing the asynchronous operation.

Exceptions

OperationCanceledException

If the CancellationToken is canceled.

CommandCreated(CommandEndEventData, DbCommand)

Called immediately after EF calls CreateCommand().

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. An implementation of this method for any interceptor that is not attempting to change the result is to return the result value passed in.

Remarks

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>).

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. An 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

A CancellationToken to observe while waiting for the task to complete.

Returns

Task

A Task representing the asynchronous operation.

Exceptions

OperationCanceledException

If the CancellationToken is canceled.

CommandInitialized(CommandEndEventData, DbCommand)

Called after EF has initialized CommandText and other command configuration.

DbCommand CommandInitialized(CommandEndEventData eventData, DbCommand result)

Parameters

eventData CommandEndEventData

Contextual information about the command and execution.

result DbCommand

The command. This value is typically used as the return value for the implementation of this method.

Returns

DbCommand

The result that EF will use. An implementation of this method for any interceptor that is not attempting to change the result is to return the result value passed in.

DataReaderClosing(DbCommand, DataReaderClosingEventData, InterceptionResult)

Called just before EF intends to call Close().

InterceptionResult DataReaderClosing(DbCommand command, DataReaderClosingEventData eventData, InterceptionResult result)

Parameters

command DbCommand

The command.

eventData DataReaderClosingEventData

Contextual information about the command.

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, then EF will continue as normal. If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult.IsSuppressed is true, then EF will suppress the operation it was about to perform. An implementation of this method for any interceptor that is not attempting to suppress the operation is to return the result value passed in.

DataReaderClosingAsync(DbCommand, DataReaderClosingEventData, InterceptionResult)

Called just before EF intends to call CloseAsync() in an async context.

ValueTask<InterceptionResult> DataReaderClosingAsync(DbCommand command, DataReaderClosingEventData eventData, InterceptionResult result)

Parameters

command DbCommand

The command.

eventData DataReaderClosingEventData

Contextual information about the command.

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

ValueTask<InterceptionResult>

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

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, then EF will continue as normal. If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult.IsSuppressed is true, then EF will suppress the operation it was about to perform. An 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().

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. An implementation of this method for any interceptor that is not attempting to change the result is to return the result value passed in.

Remarks

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>).

NonQueryExecutedAsync(DbCommand, CommandExecutedEventData, int, CancellationToken)

Called immediately after EF calls ExecuteNonQueryAsync().

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

A CancellationToken to observe while waiting for the task to complete.

Returns

ValueTask<int>

A Task providing the result that EF will use. An 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)

Remarks

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).

Exceptions

OperationCanceledException

If the CancellationToken is canceled.

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. An 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

A CancellationToken to observe while waiting for the task to complete.

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. An 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)

Exceptions

OperationCanceledException

If the CancellationToken is canceled.

ReaderExecuted(DbCommand, CommandExecutedEventData, DbDataReader)

Called immediately after EF calls ExecuteReader().

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. An implementation of this method for any interceptor that is not attempting to change the result is to return the result value passed in.

Remarks

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>).

ReaderExecutedAsync(DbCommand, CommandExecutedEventData, DbDataReader, CancellationToken)

Called immediately after EF calls ExecuteReaderAsync().

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

A CancellationToken to observe while waiting for the task to complete.

Returns

ValueTask<DbDataReader>

A Task providing the result that EF will use. An 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)

Remarks

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).

Exceptions

OperationCanceledException

If the CancellationToken is canceled.

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. An 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

A CancellationToken to observe while waiting for the task to complete.

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. An 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)

Exceptions

OperationCanceledException

If the CancellationToken is canceled.

ScalarExecuted(DbCommand, CommandExecutedEventData, object?)

Called immediately after EF calls ExecuteScalar().

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. An implementation of this method for any interceptor that is not attempting to change the result is to return the result value passed in.

Remarks

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>).

ScalarExecutedAsync(DbCommand, CommandExecutedEventData, object?, CancellationToken)

Called immediately after EF calls ExecuteScalarAsync().

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

A CancellationToken to observe while waiting for the task to complete.

Returns

ValueTask<object>

A Task providing the result that EF will use. An 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)

Remarks

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).

Exceptions

OperationCanceledException

If the CancellationToken is canceled.

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. An 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

A CancellationToken to observe while waiting for the task to complete.

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. An 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)

Exceptions

OperationCanceledException

If the CancellationToken is canceled.