Interface IDbConnectionInterceptor

Namespace

Microsoft.EntityFrameworkCore.Diagnostics

Assembly

Microsoft.EntityFrameworkCore.Relational.dll

Allows interception of operations on DbConnection.

public interface IDbConnectionInterceptor : IInterceptor

Remarks

Connection interceptors can be used to view, change, or suppress the operation on DbConnection, and to modify the result before it is returned to EF.

Consider inheriting from DbConnectionInterceptor 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

ConnectionClosed(DbConnection, ConnectionEndEventData)

Called just after EF has called Close() in an async context.

void ConnectionClosed(DbConnection connection, ConnectionEndEventData eventData)

Parameters

connection DbConnection

The connection.

eventData ConnectionEndEventData

Contextual information about the connection.

ConnectionClosedAsync(DbConnection, ConnectionEndEventData)

Called just after EF has called CloseAsync().

Task ConnectionClosedAsync(DbConnection connection, ConnectionEndEventData eventData)

Parameters

connection DbConnection

The connection.

eventData ConnectionEndEventData

Contextual information about the connection.

Returns

Task

A Task representing the asynchronous operation.

ConnectionClosing(DbConnection, ConnectionEventData, InterceptionResult)

Called just before EF intends to call Close().

InterceptionResult ConnectionClosing(DbConnection connection, ConnectionEventData eventData, InterceptionResult result)

Parameters

connection DbConnection

The connection.

eventData ConnectionEventData

Contextual information about the connection.

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.

ConnectionClosingAsync(DbConnection, ConnectionEventData, InterceptionResult)

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

ValueTask<InterceptionResult> ConnectionClosingAsync(DbConnection connection, ConnectionEventData eventData, InterceptionResult result)

Parameters

connection DbConnection

The connection.

eventData ConnectionEventData

Contextual information about the connection.

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.

ConnectionCreated(ConnectionCreatedEventData, DbConnection)

Called just after EF creates a DbConnection. This event is not triggered if the application provides the connection to use.

DbConnection ConnectionCreated(ConnectionCreatedEventData eventData, DbConnection result)

Parameters

eventData ConnectionCreatedEventData

Contextual information about the connection.

result DbConnection

The connection that has been created. This value is typically used as the return value for the implementation of this method.

Returns

DbConnection

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.

ConnectionCreating(ConnectionCreatingEventData, InterceptionResult<DbConnection>)

Called just before EF creates a DbConnection. This event is not triggered if the application provides the connection to use.

InterceptionResult<DbConnection> ConnectionCreating(ConnectionCreatingEventData eventData, InterceptionResult<DbConnection> result)

Parameters

eventData ConnectionCreatingEventData

Contextual information about the connection.

result InterceptionResult<DbConnection>

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<DbConnection>

If Microsoft.EntityFrameworkCore.Diagnostics.InterceptionResult`1.HasResult is false, then 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 should return the result value passed in.

ConnectionDisposed(DbConnection, ConnectionEndEventData)

Called just after EF has called Dispose() in an async context.

void ConnectionDisposed(DbConnection connection, ConnectionEndEventData eventData)

Parameters

connection DbConnection

The connection.

eventData ConnectionEndEventData

Contextual information about the connection.

ConnectionDisposedAsync(DbConnection, ConnectionEndEventData)

Called just after EF has called DisposeAsync().

Task ConnectionDisposedAsync(DbConnection connection, ConnectionEndEventData eventData)

Parameters

connection DbConnection

The connection.

eventData ConnectionEndEventData

Contextual information about the connection.

Returns

Task

A Task representing the asynchronous operation.

ConnectionDisposing(DbConnection, ConnectionEventData, InterceptionResult)

Called just before EF intends to call Dispose() for the DbConnection.

InterceptionResult ConnectionDisposing(DbConnection connection, ConnectionEventData eventData, InterceptionResult result)

Parameters

connection DbConnection

The connection.

eventData ConnectionEventData

Contextual information about the connection.

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

ConnectionDisposingAsync(DbConnection, ConnectionEventData, InterceptionResult)

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

ValueTask<InterceptionResult> ConnectionDisposingAsync(DbConnection connection, ConnectionEventData eventData, InterceptionResult result)

Parameters

connection DbConnection

The connection.

eventData ConnectionEventData

Contextual information about the connection.

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.

ConnectionFailed(DbConnection, ConnectionErrorEventData)

Called when closing of a connection has failed with an exception.

void ConnectionFailed(DbConnection connection, ConnectionErrorEventData eventData)

Parameters

connection DbConnection

The connection.

eventData ConnectionErrorEventData

Contextual information about the connection.

ConnectionFailedAsync(DbConnection, ConnectionErrorEventData, CancellationToken)

Called when closing of a connection has failed with an exception.

Task ConnectionFailedAsync(DbConnection connection, ConnectionErrorEventData eventData, CancellationToken cancellationToken = default)

Parameters

connection DbConnection

The connection.

eventData ConnectionErrorEventData

Contextual information about the connection.

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.

ConnectionOpened(DbConnection, ConnectionEndEventData)

Called just after EF has called Open().

void ConnectionOpened(DbConnection connection, ConnectionEndEventData eventData)

Parameters

connection DbConnection

The connection.

eventData ConnectionEndEventData

Contextual information about the connection.

ConnectionOpenedAsync(DbConnection, ConnectionEndEventData, CancellationToken)

Called just after EF has called OpenAsync().

Task ConnectionOpenedAsync(DbConnection connection, ConnectionEndEventData eventData, CancellationToken cancellationToken = default)

Parameters

connection DbConnection

The connection.

eventData ConnectionEndEventData

Contextual information about the connection.

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.

ConnectionOpening(DbConnection, ConnectionEventData, InterceptionResult)

Called just before EF intends to call Open().

InterceptionResult ConnectionOpening(DbConnection connection, ConnectionEventData eventData, InterceptionResult result)

Parameters

connection DbConnection

The connection.

eventData ConnectionEventData

Contextual information about the connection.

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.

ConnectionOpeningAsync(DbConnection, ConnectionEventData, InterceptionResult, CancellationToken)

Called just before EF intends to call OpenAsync().

ValueTask<InterceptionResult> ConnectionOpeningAsync(DbConnection connection, ConnectionEventData eventData, InterceptionResult result, CancellationToken cancellationToken = default)

Parameters

connection DbConnection

The connection.

eventData ConnectionEventData

Contextual information about the connection.

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.

cancellationToken CancellationToken

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

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.

Exceptions

OperationCanceledException

If the CancellationToken is canceled.