Class ExecutionStrategy

Namespace

Microsoft.EntityFrameworkCore.Storage

Assembly

Microsoft.EntityFrameworkCore.dll

The base class for IExecutionStrategy implementations.

public abstract class ExecutionStrategy : IExecutionStrategy

Inheritance

object

ExecutionStrategy

Implements

IExecutionStrategy

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Extension Methods

ExecutionStrategyExtensions.Execute(IExecutionStrategy, Action)

ExecutionStrategyExtensions.Execute<TState>(IExecutionStrategy, TState, Action<TState>)

ExecutionStrategyExtensions.Execute<TResult>(IExecutionStrategy, Func<TResult>)

ExecutionStrategyExtensions.Execute<TState, TResult>(IExecutionStrategy, TState, Func<TState, TResult>, Func<TState, ExecutionResult<TResult>>?)

ExecutionStrategyExtensions.Execute<TState, TResult>(IExecutionStrategy, TState, Func<TState, TResult>)

ExecutionStrategyExtensions.ExecuteAsync(IExecutionStrategy, Func<CancellationToken, Task>, CancellationToken)

ExecutionStrategyExtensions.ExecuteAsync(IExecutionStrategy, Func<Task>)

ExecutionStrategyExtensions.ExecuteAsync<TState>(IExecutionStrategy, TState, Func<TState, CancellationToken, Task>, CancellationToken)

ExecutionStrategyExtensions.ExecuteAsync<TState>(IExecutionStrategy, TState, Func<TState, Task>)

ExecutionStrategyExtensions.ExecuteAsync<TResult>(IExecutionStrategy, Func<CancellationToken, Task<TResult>>, CancellationToken)

ExecutionStrategyExtensions.ExecuteAsync<TResult>(IExecutionStrategy, Func<Task<TResult>>)

ExecutionStrategyExtensions.ExecuteAsync<TState, TResult>(IExecutionStrategy, TState, Func<TState, CancellationToken, Task<TResult>>, Func<TState, CancellationToken, Task<ExecutionResult<TResult>>>?, CancellationToken)

ExecutionStrategyExtensions.ExecuteAsync<TState, TResult>(IExecutionStrategy, TState, Func<TState, CancellationToken, Task<TResult>>, CancellationToken)

ExecutionStrategyExtensions.ExecuteAsync<TState, TResult>(IExecutionStrategy, TState, Func<TState, Task<TResult>>)

ExecutionStrategyExtensions.ExecuteInTransaction(IExecutionStrategy, Action, Func<bool>)

ExecutionStrategyExtensions.ExecuteInTransaction<TState>(IExecutionStrategy, TState, Action<TState>, Func<TState, bool>)

ExecutionStrategyExtensions.ExecuteInTransaction<TResult>(IExecutionStrategy, Func<TResult>, Func<bool>)

ExecutionStrategyExtensions.ExecuteInTransaction<TState, TResult>(IExecutionStrategy, TState, Func<TState, TResult>, Func<TState, bool>)

ExecutionStrategyExtensions.ExecuteInTransactionAsync(IExecutionStrategy, Func<CancellationToken, Task>, Func<CancellationToken, Task<bool>>, CancellationToken)

ExecutionStrategyExtensions.ExecuteInTransactionAsync(IExecutionStrategy, Func<Task>, Func<Task<bool>>)

ExecutionStrategyExtensions.ExecuteInTransactionAsync<TState>(IExecutionStrategy, TState, Func<TState, CancellationToken, Task>, Func<TState, CancellationToken, Task<bool>>, CancellationToken)

ExecutionStrategyExtensions.ExecuteInTransactionAsync<TResult>(IExecutionStrategy, Func<CancellationToken, Task<TResult>>, Func<CancellationToken, Task<bool>>, CancellationToken)

ExecutionStrategyExtensions.ExecuteInTransactionAsync<TState, TResult>(IExecutionStrategy, TState, Func<TState, CancellationToken, Task<TResult>>, Func<TState, CancellationToken, Task<bool>>, CancellationToken)

Remarks

The service lifetime is Scoped. This means that each DbContext instance will use its own instance of this service. The implementation may depend on other services registered with any lifetime. The implementation does not need to be thread-safe.

See Connection resiliency and database retries for more information and examples.

Constructors

ExecutionStrategy(DbContext, int, TimeSpan)

Creates a new instance of ExecutionStrategy.

protected ExecutionStrategy(DbContext context, int maxRetryCount, TimeSpan maxRetryDelay)

Parameters

context DbContext

The context on which the operations will be invoked.

maxRetryCount int

The maximum number of retry attempts.

maxRetryDelay TimeSpan

The maximum delay between retries.

Remarks

See Connection resiliency and database retries for more information and examples.

ExecutionStrategy(ExecutionStrategyDependencies, int, TimeSpan)

Creates a new instance of ExecutionStrategy.

protected ExecutionStrategy(ExecutionStrategyDependencies dependencies, int maxRetryCount, TimeSpan maxRetryDelay)

Parameters

dependencies ExecutionStrategyDependencies

Parameter object containing service dependencies.

maxRetryCount int

The maximum number of retry attempts.

maxRetryDelay TimeSpan

The maximum delay between retries.

Remarks

See Connection resiliency and database retries for more information and examples.

Fields

DefaultMaxDelay

The default maximum time delay between retries, must be nonnegative.

protected static readonly TimeSpan DefaultMaxDelay

Field Value

TimeSpan

DefaultMaxRetryCount

The default number of retry attempts.

protected static readonly int DefaultMaxRetryCount

Field Value

int

Remarks

See Connection resiliency and database retries for more information and examples.

Properties

Current

Gets or sets the currently executing strategy. All nested calls will be handled by the outermost strategy.

public static ExecutionStrategy? Current { get; protected set; }

Property Value

ExecutionStrategy

Remarks

See Connection resiliency and database retries for more information and examples.

Dependencies

Dependencies for this service.

protected virtual ExecutionStrategyDependencies Dependencies { get; }

Property Value

ExecutionStrategyDependencies

ExceptionsEncountered

The list of exceptions that caused the operation to be retried so far.

protected virtual List<Exception> ExceptionsEncountered { get; }

Property Value

List<Exception>

Remarks

See Connection resiliency and database retries for more information and examples.

MaxRetryCount

The maximum number of retry attempts.

public virtual int MaxRetryCount { get; }

Property Value

int

Remarks

See Connection resiliency and database retries for more information and examples.

MaxRetryDelay

The maximum delay between retries.

public virtual TimeSpan MaxRetryDelay { get; }

Property Value

TimeSpan

Remarks

See Connection resiliency and database retries for more information and examples.

Random

A pseudo-random number generator that can be used to vary the delay between retries.

protected virtual Random Random { get; }

Property Value

Random

RetriesOnFailure

Indicates whether this IExecutionStrategy might retry the execution after a failure.

public virtual bool RetriesOnFailure { get; }

Property Value

bool

Remarks

See Connection resiliency and database retries for more information and examples.

Methods

CallOnWrappedException<TResult>(Exception, Func<Exception, TResult>)

Recursively gets InnerException from exception as long as it is an exception created by Entity Framework and calls exceptionHandler on the innermost one.

public static TResult CallOnWrappedException<TResult>(Exception exception, Func<Exception, TResult> exceptionHandler)

Parameters

exception Exception

The exception to be unwrapped.

exceptionHandler Func<Exception, TResult>

A delegate that will be called with the unwrapped exception.

Returns

TResult

The result from exceptionHandler.

Type Parameters

TResult

The return type of exceptionHandler.

Remarks

See Connection resiliency and database retries for more information and examples.

ExecuteAsync<TState, TResult>(TState, Func<DbContext, TState, CancellationToken, Task<TResult>>, Func<DbContext, TState, CancellationToken, Task<ExecutionResult<TResult>>>?, CancellationToken)

Executes the specified asynchronous operation and returns the result.

public virtual Task<TResult> ExecuteAsync<TState, TResult>(TState state, Func<DbContext, TState, CancellationToken, Task<TResult>> operation, Func<DbContext, TState, CancellationToken, Task<ExecutionResult<TResult>>>? verifySucceeded, CancellationToken cancellationToken = default)

Parameters

state TState

The state that will be passed to the operation.

operation Func<DbContext, TState, CancellationToken, Task<TResult>>

A function that returns a started task of type TResult.

verifySucceeded Func<DbContext, TState, CancellationToken, Task<ExecutionResult<TResult>>>

A delegate that tests whether the operation succeeded even though an exception was thrown.

cancellationToken CancellationToken

A cancellation token used to cancel the retry operation, but not operations that are already in flight or that already completed successfully.

Returns

Task<TResult>

A task that will run to completion if the original task completes successfully (either the first time or after retrying transient failures). If the task fails with a non-transient error or the retry limit is reached, the returned task will become faulted and the exception must be observed.

Type Parameters

TState

The type of the state.

TResult

The result type of the Task<TResult> returned by operation.

Remarks

See Connection resiliency and database retries for more information and examples.

Exceptions

RetryLimitExceededException

The operation has not succeeded after the configured number of retries.

OperationCanceledException

If the CancellationToken is canceled.

Execute<TState, TResult>(TState, Func<DbContext, TState, TResult>, Func<DbContext, TState, ExecutionResult<TResult>>?)

Executes the specified operation and returns the result.

public virtual TResult Execute<TState, TResult>(TState state, Func<DbContext, TState, TResult> operation, Func<DbContext, TState, ExecutionResult<TResult>>? verifySucceeded)

Parameters

state TState

The state that will be passed to the operation.

operation Func<DbContext, TState, TResult>

A delegate representing an executable operation that returns the result of type TResult.

verifySucceeded Func<DbContext, TState, ExecutionResult<TResult>>

A delegate that tests whether the operation succeeded even though an exception was thrown.

Returns

TResult

The result from the operation.

Type Parameters

TState

The type of the state.

TResult

The return type of operation.

Remarks

See Connection resiliency and database retries for more information and examples.

Exceptions

RetryLimitExceededException

The operation has not succeeded after the configured number of retries.

GetNextDelay(Exception)

Determines whether the operation should be retried and the delay before the next attempt.

protected virtual TimeSpan? GetNextDelay(Exception lastException)

Parameters

lastException Exception

The exception thrown during the last execution attempt.

Returns

TimeSpan?

Returns the delay indicating how long to wait for before the next execution attempt if the operation should be retried; null otherwise

Remarks

See Connection resiliency and database retries for more information and examples.

OnFirstExecution()

Method called before the first operation execution

protected virtual void OnFirstExecution()

Remarks

See Connection resiliency and database retries for more information and examples.

OnRetry()

Method called before retrying the operation execution

protected virtual void OnRetry()

Remarks

See Connection resiliency and database retries for more information and examples.

ShouldRetryOn(Exception)

Determines whether the specified exception represents a transient failure that can be compensated by a retry.

protected abstract bool ShouldRetryOn(Exception exception)

Parameters

exception Exception

The exception object to be verified.

Returns

bool

true if the specified exception is considered as transient, otherwise false.

Remarks

See Connection resiliency and database retries for more information and examples.

ShouldVerifySuccessOn(Exception)

Determines whether the specified exception could be thrown after a successful execution.

protected virtual bool ShouldVerifySuccessOn(Exception exception)

Parameters

exception Exception

The exception object to be verified.

Returns

bool

true if the specified exception could be thrown after a successful execution, otherwise false.

Remarks

See Connection resiliency and database retries for more information and examples.