mirror of https://github.com/abpframework/abp.git
21 changed files with 1537 additions and 89 deletions
@ -0,0 +1,75 @@ |
|||||
|
```json |
||||
|
//[doc-seo] |
||||
|
{ |
||||
|
"Description": "Upgrade your ABP solutions from v10.x to v11.0 with this migration guide covering important behavior and integration changes." |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
# ABP Version 11.0 Migration Guide |
||||
|
|
||||
|
This document is a guide for upgrading ABP v10.x solutions to ABP v11.0. There are some changes in this version that may affect your applications. Please read them carefully and apply the necessary changes to your application. |
||||
|
|
||||
|
> **Package Version Changes:** Before upgrading, review the [Package Version Changes](../../package-version-changes.md) document to see version changes on dependent NuGet and NPM packages and align your project with ABP's internal package versions. |
||||
|
|
||||
|
## Open-Source (Framework) |
||||
|
|
||||
|
This version contains the following changes on the open-source side: |
||||
|
|
||||
|
### Polly Is No Longer Referenced |
||||
|
|
||||
|
**Who is affected** |
||||
|
|
||||
|
- Applications that use Polly in their own code without referencing the `Polly` package themselves, and get it through one of the ABP packages below. |
||||
|
|
||||
|
**What changed** |
||||
|
|
||||
|
- ABP retries its own HTTP requests and file operations with `Volo.Abp.Threading.RetryHelper`, so these packages no longer reference `Polly`: |
||||
|
|
||||
|
| Package | Removed reference | |
||||
|
|---------|-------------------| |
||||
|
| Volo.Abp.BlobStoring.FileSystem | Polly | |
||||
|
| Volo.Abp.Cli.Core | Polly, Polly.Extensions.Http | |
||||
|
| Volo.Abp.FeatureManagement.Domain | Polly | |
||||
|
| Volo.Abp.PermissionManagement.Domain | Polly | |
||||
|
| Volo.Abp.SettingManagement.Domain | Polly | |
||||
|
|
||||
|
- The number of attempts, the delays between them and the failures that are retried are unchanged in all of them. |
||||
|
- No ABP API takes or returns a Polly type, so nothing else changes for an application that does not use Polly itself. |
||||
|
|
||||
|
**What to do** |
||||
|
|
||||
|
Reference the package in the projects that use it. `abp update` rewrites `Volo.*` references only, so it does not add this one. ABP referenced Polly 8.6.3 up to v10.7, so that version keeps the behavior you had: |
||||
|
|
||||
|
```xml |
||||
|
<PackageReference Include="Polly" Version="8.6.3" /> |
||||
|
``` |
||||
|
|
||||
|
`RetryHelper` is an alternative if you use Polly only to retry a failing call: |
||||
|
|
||||
|
```csharp |
||||
|
await RetryHelper.ExecuteAsync( |
||||
|
async cancellationToken => await httpClient.GetAsync(url, cancellationToken), |
||||
|
new RetryOptions<HttpResponseMessage> |
||||
|
{ |
||||
|
MaxRetryCount = 3, |
||||
|
ShouldRetryOnResult = response => !response.IsSuccessStatusCode |
||||
|
}); |
||||
|
``` |
||||
|
|
||||
|
## Pro |
||||
|
|
||||
|
This version contains the following changes on the PRO side: |
||||
|
|
||||
|
### Polly Is No Longer Referenced |
||||
|
|
||||
|
**Who is affected** |
||||
|
|
||||
|
- Applications that use Polly in their own code without referencing the `Polly` package themselves, and get it through `Volo.Abp.LanguageManagement.Domain` or `Volo.Abp.TextTemplateManagement.Domain`. |
||||
|
|
||||
|
**What changed** |
||||
|
|
||||
|
- Both packages retry with `Volo.Abp.Threading.RetryHelper` instead of Polly and no longer reference it. The number of attempts, the delays between them and the failures that are retried are unchanged. |
||||
|
|
||||
|
**What to do** |
||||
|
|
||||
|
Reference the `Polly` package in the projects that use it, as described in the open-source section above. |
||||
@ -0,0 +1,49 @@ |
|||||
|
using System; |
||||
|
|
||||
|
namespace Volo.Abp.Threading; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// A failed attempt that <see cref="RetryHelper"/> is about to retry.
|
||||
|
/// </summary>
|
||||
|
public class RetryAttempt |
||||
|
{ |
||||
|
/// <summary>
|
||||
|
/// Number of the retry that is about to be performed, starting from 1.
|
||||
|
/// </summary>
|
||||
|
public int RetryCount { get; } |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// How long to wait before the retry.
|
||||
|
/// </summary>
|
||||
|
public TimeSpan RetryDelay { get; } |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// The exception that caused the retry. Null if the attempt is retried because of its result.
|
||||
|
/// </summary>
|
||||
|
public Exception? Exception { get; } |
||||
|
|
||||
|
public RetryAttempt(int retryCount, TimeSpan retryDelay, Exception? exception) |
||||
|
{ |
||||
|
RetryCount = retryCount; |
||||
|
RetryDelay = retryDelay; |
||||
|
Exception = exception; |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// A failed attempt that <see cref="RetryHelper"/> is about to retry.
|
||||
|
/// </summary>
|
||||
|
/// <typeparam name="TResult">Type of the value returned by the retried action.</typeparam>
|
||||
|
public class RetryAttempt<TResult> : RetryAttempt |
||||
|
{ |
||||
|
/// <summary>
|
||||
|
/// The result that caused the retry. Default if the attempt is retried because of an exception.
|
||||
|
/// </summary>
|
||||
|
public TResult? Result { get; } |
||||
|
|
||||
|
public RetryAttempt(int retryCount, TimeSpan retryDelay, Exception? exception, TResult? result) |
||||
|
: base(retryCount, retryDelay, exception) |
||||
|
{ |
||||
|
Result = result; |
||||
|
} |
||||
|
} |
||||
@ -0,0 +1,232 @@ |
|||||
|
using System; |
||||
|
using System.Runtime.ExceptionServices; |
||||
|
using System.Threading; |
||||
|
using System.Threading.Tasks; |
||||
|
|
||||
|
namespace Volo.Abp.Threading; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Runs an action and retries it while it keeps failing, waiting between the attempts.
|
||||
|
/// See <see cref="RetryOptions"/> to control the retry count, the delay and which failures are retried.
|
||||
|
/// </summary>
|
||||
|
public static class RetryHelper |
||||
|
{ |
||||
|
// Task.Delay rejects a longer delay on the netstandard targets.
|
||||
|
private static readonly TimeSpan MaxDelay = TimeSpan.FromMilliseconds(int.MaxValue); |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Runs the given action and retries it while it throws a retryable exception.
|
||||
|
/// Rethrows the last exception when the retries are exhausted.
|
||||
|
/// </summary>
|
||||
|
public static async Task ExecuteAsync( |
||||
|
Func<CancellationToken, Task> action, |
||||
|
RetryOptions? options = null, |
||||
|
CancellationToken cancellationToken = default) |
||||
|
{ |
||||
|
Check.NotNull(action, nameof(action)); |
||||
|
|
||||
|
options ??= new RetryOptions(); |
||||
|
|
||||
|
// Read once, so that changing a shared instance cannot affect a running execution.
|
||||
|
var maxRetryCount = options.MaxRetryCount; |
||||
|
var delayFactory = options.DelayFactory; |
||||
|
var shouldRetryOnException = options.ShouldRetryOnException; |
||||
|
var onRetry = options.OnRetry; |
||||
|
|
||||
|
Validate(maxRetryCount, delayFactory, shouldRetryOnException); |
||||
|
|
||||
|
var retryCount = 0; |
||||
|
|
||||
|
while (true) |
||||
|
{ |
||||
|
cancellationToken.ThrowIfCancellationRequested(); |
||||
|
|
||||
|
Exception? caught = null; |
||||
|
|
||||
|
try |
||||
|
{ |
||||
|
await action(cancellationToken); |
||||
|
return; |
||||
|
} |
||||
|
catch (Exception ex) |
||||
|
{ |
||||
|
caught = ex; |
||||
|
} |
||||
|
|
||||
|
var exception = caught!; |
||||
|
|
||||
|
// Asked on every attempt, including the last one, which is not retried.
|
||||
|
var isHandled = shouldRetryOnException(exception); |
||||
|
|
||||
|
if (!isHandled || IsLastRetry(retryCount, maxRetryCount)) |
||||
|
{ |
||||
|
ExceptionDispatchInfo.Capture(exception).Throw(); |
||||
|
} |
||||
|
|
||||
|
retryCount = NextRetryCount(retryCount); |
||||
|
|
||||
|
var delay = GetDelay(delayFactory, retryCount); |
||||
|
if (onRetry != null) |
||||
|
{ |
||||
|
await onRetry(new RetryAttempt(retryCount, delay, exception)); |
||||
|
} |
||||
|
|
||||
|
await WaitAsync(delay, cancellationToken); |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Runs the given action and retries it while it throws a retryable exception or returns a retryable result.
|
||||
|
/// Rethrows the last exception when the retries are exhausted, or returns the result of the last attempt
|
||||
|
/// if it failed because of its result. A retried result is disposed if it is disposable.
|
||||
|
/// </summary>
|
||||
|
public static async Task<TResult> ExecuteAsync<TResult>( |
||||
|
Func<CancellationToken, Task<TResult>> action, |
||||
|
RetryOptions<TResult>? options = null, |
||||
|
CancellationToken cancellationToken = default) |
||||
|
{ |
||||
|
Check.NotNull(action, nameof(action)); |
||||
|
|
||||
|
options ??= new RetryOptions<TResult>(); |
||||
|
|
||||
|
// Read once, so that changing a shared instance cannot affect a running execution.
|
||||
|
var maxRetryCount = options.MaxRetryCount; |
||||
|
var delayFactory = options.DelayFactory; |
||||
|
var shouldRetryOnException = options.ShouldRetryOnException; |
||||
|
var shouldRetryOnResult = options.ShouldRetryOnResult; |
||||
|
var onRetry = options.OnRetry; |
||||
|
|
||||
|
Validate(maxRetryCount, delayFactory, shouldRetryOnException); |
||||
|
Check.NotNull(shouldRetryOnResult, nameof(RetryOptions<TResult>.ShouldRetryOnResult)); |
||||
|
|
||||
|
var retryCount = 0; |
||||
|
|
||||
|
while (true) |
||||
|
{ |
||||
|
cancellationToken.ThrowIfCancellationRequested(); |
||||
|
|
||||
|
Exception? exception = null; |
||||
|
var result = default(TResult)!; |
||||
|
var hasResult = false; |
||||
|
|
||||
|
try |
||||
|
{ |
||||
|
result = await action(cancellationToken); |
||||
|
hasResult = true; |
||||
|
|
||||
|
if (!shouldRetryOnResult(result)) |
||||
|
{ |
||||
|
return result; |
||||
|
} |
||||
|
} |
||||
|
catch (Exception ex) |
||||
|
{ |
||||
|
exception = ex; |
||||
|
} |
||||
|
|
||||
|
// Asked on every attempt, including the last one, which is not retried.
|
||||
|
var isUnhandledException = exception != null && !shouldRetryOnException(exception); |
||||
|
|
||||
|
if (isUnhandledException || IsLastRetry(retryCount, maxRetryCount)) |
||||
|
{ |
||||
|
if (exception != null) |
||||
|
{ |
||||
|
// The caller never sees this result, so it must not leak.
|
||||
|
if (hasResult) |
||||
|
{ |
||||
|
await TryDisposeAsync(result); |
||||
|
} |
||||
|
|
||||
|
ExceptionDispatchInfo.Capture(exception).Throw(); |
||||
|
} |
||||
|
|
||||
|
return result; |
||||
|
} |
||||
|
|
||||
|
retryCount = NextRetryCount(retryCount); |
||||
|
|
||||
|
var delay = GetDelay(delayFactory, retryCount); |
||||
|
if (onRetry != null) |
||||
|
{ |
||||
|
await onRetry(new RetryAttempt<TResult>(retryCount, delay, exception, exception == null ? result : default)); |
||||
|
} |
||||
|
|
||||
|
if (hasResult) |
||||
|
{ |
||||
|
await TryDisposeAsync(result); |
||||
|
} |
||||
|
|
||||
|
await WaitAsync(delay, cancellationToken); |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
private static void Validate( |
||||
|
int maxRetryCount, |
||||
|
Func<int, TimeSpan> delayFactory, |
||||
|
Func<Exception, bool> shouldRetryOnException) |
||||
|
{ |
||||
|
if (maxRetryCount < 0) |
||||
|
{ |
||||
|
throw new ArgumentOutOfRangeException(nameof(RetryOptions.MaxRetryCount), maxRetryCount, "Must not be negative."); |
||||
|
} |
||||
|
|
||||
|
Check.NotNull(delayFactory, nameof(RetryOptions.DelayFactory)); |
||||
|
Check.NotNull(shouldRetryOnException, nameof(RetryOptions.ShouldRetryOnException)); |
||||
|
} |
||||
|
|
||||
|
// int.MaxValue means "retry forever": the counter stops there instead of overflowing.
|
||||
|
private static bool IsLastRetry(int retryCount, int maxRetryCount) |
||||
|
{ |
||||
|
return maxRetryCount != int.MaxValue && retryCount >= maxRetryCount; |
||||
|
} |
||||
|
|
||||
|
private static TimeSpan GetDelay(Func<int, TimeSpan> delayFactory, int retryCount) |
||||
|
{ |
||||
|
var delay = delayFactory(retryCount); |
||||
|
|
||||
|
// Clamped before it is reported, so that the reported delay is the one that is waited for.
|
||||
|
return delay > MaxDelay ? MaxDelay : delay; |
||||
|
} |
||||
|
|
||||
|
internal static TimeSpan GetExponentialDelay(int retryCount) |
||||
|
{ |
||||
|
var seconds = Math.Pow(2, retryCount); |
||||
|
|
||||
|
// Stops growing instead of overflowing when the retry count gets high.
|
||||
|
return seconds >= MaxDelay.TotalSeconds ? MaxDelay : TimeSpan.FromSeconds(seconds); |
||||
|
} |
||||
|
|
||||
|
private static int NextRetryCount(int retryCount) |
||||
|
{ |
||||
|
return retryCount == int.MaxValue ? retryCount : retryCount + 1; |
||||
|
} |
||||
|
|
||||
|
private static async Task TryDisposeAsync<TResult>(TResult result) |
||||
|
{ |
||||
|
try |
||||
|
{ |
||||
|
if (result is IAsyncDisposable asyncDisposable) |
||||
|
{ |
||||
|
await asyncDisposable.DisposeAsync(); |
||||
|
} |
||||
|
else if (result is IDisposable disposable) |
||||
|
{ |
||||
|
disposable.Dispose(); |
||||
|
} |
||||
|
} |
||||
|
catch |
||||
|
{ |
||||
|
// A result that is being thrown away should not fail the retry.
|
||||
|
} |
||||
|
} |
||||
|
|
||||
|
private static async Task WaitAsync(TimeSpan delay, CancellationToken cancellationToken) |
||||
|
{ |
||||
|
cancellationToken.ThrowIfCancellationRequested(); |
||||
|
|
||||
|
if (delay > TimeSpan.Zero) |
||||
|
{ |
||||
|
await Task.Delay(delay, cancellationToken); |
||||
|
} |
||||
|
} |
||||
|
} |
||||
@ -0,0 +1,69 @@ |
|||||
|
using System; |
||||
|
using System.Threading.Tasks; |
||||
|
|
||||
|
namespace Volo.Abp.Threading; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Options to control how <see cref="RetryHelper"/> retries a failing action.
|
||||
|
/// </summary>
|
||||
|
public class RetryOptions |
||||
|
{ |
||||
|
/// <summary>
|
||||
|
/// How many times to retry after the initial attempt fails. Default: 3.
|
||||
|
/// Set to <see cref="int.MaxValue"/> to retry forever.
|
||||
|
/// </summary>
|
||||
|
public int MaxRetryCount { get; set; } = 3; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Returns how long to wait before the given retry.
|
||||
|
/// Default: 2^retryCount seconds, up to the longest delay that can be waited for.
|
||||
|
/// </summary>
|
||||
|
public Func<int, TimeSpan> DelayFactory { get; set; } = RetryHelper.GetExponentialDelay; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Decides if the action should be retried after the given exception.
|
||||
|
/// Default: retries any exception except <see cref="OperationCanceledException"/>.
|
||||
|
/// </summary>
|
||||
|
public Func<Exception, bool> ShouldRetryOnException { get; set; } = exception => exception is not OperationCanceledException; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Called once per retry, before waiting.
|
||||
|
/// </summary>
|
||||
|
public Func<RetryAttempt, Task>? OnRetry { get; set; } |
||||
|
} |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Options to control how <see cref="RetryHelper"/> retries a failing action that returns a value.
|
||||
|
/// The action can also be retried because of the value it returned.
|
||||
|
/// </summary>
|
||||
|
/// <typeparam name="TResult">Type of the value returned by the retried action.</typeparam>
|
||||
|
public class RetryOptions<TResult> |
||||
|
{ |
||||
|
/// <summary>
|
||||
|
/// How many times to retry after the initial attempt fails. Default: 3.
|
||||
|
/// Set to <see cref="int.MaxValue"/> to retry forever.
|
||||
|
/// </summary>
|
||||
|
public int MaxRetryCount { get; set; } = 3; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Returns how long to wait before the given retry.
|
||||
|
/// Default: 2^retryCount seconds, up to the longest delay that can be waited for.
|
||||
|
/// </summary>
|
||||
|
public Func<int, TimeSpan> DelayFactory { get; set; } = RetryHelper.GetExponentialDelay; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Decides if the action should be retried after the given exception.
|
||||
|
/// Default: retries any exception except <see cref="OperationCanceledException"/>.
|
||||
|
/// </summary>
|
||||
|
public Func<Exception, bool> ShouldRetryOnException { get; set; } = exception => exception is not OperationCanceledException; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Decides if the action should be retried because of the value it returned. Default: no result is retried.
|
||||
|
/// </summary>
|
||||
|
public Func<TResult, bool> ShouldRetryOnResult { get; set; } = _ => false; |
||||
|
|
||||
|
/// <summary>
|
||||
|
/// Called once per retry, before the retried result is disposed and before waiting.
|
||||
|
/// </summary>
|
||||
|
public Func<RetryAttempt<TResult>, Task>? OnRetry { get; set; } |
||||
|
} |
||||
File diff suppressed because it is too large
Loading…
Reference in new issue