Freigeben über


Core-APIs für konfigurierbare Wiederholungslogik in SqlClient

Gilt für: .NET Framework .NET .NET Standard

Herunterladen von ADO.NET

Wenn die integrierten Anbieter von Wiederholungslogik Ihre Anforderungen nicht erfüllen, können Sie eigene benutzerdefinierte Anbieter erstellen. Diese Anbieter können Sie dann einem SqlConnection- oder SqlCommand-Objekt zuweisen, um Ihre benutzerdefinierte Logik anzuwenden.

Die integrierten Anbieter werden um drei Schnittstellen herum entworfen, die zum Implementieren benutzerdefinierter Anbieter verwendet werden können. Benutzerdefinierte Wiederholungsanbieter können dann genauso wie interne Wiederholungsanbieter in einem SqlConnection- oder SqlCommand-Objekt verwendet werden:

  1. SqlRetryIntervalBaseEnumerator: Generiert eine Folge von Zeitintervallen.
  2. SqlRetryLogicBase: Ruft das nächste Zeitintervall für einen angegebenen Enumerator ab, wenn die Anzahl der Wiederholungen nicht überschritten wurde und eine vorübergehende Bedingung erfüllt ist.
  3. SqlRetryLogicBaseProvider: Wendet Wiederholungslogik auf Verbindungs- und Befehlsvorgänge an.

Achtung

Durch Implementieren eines benutzerdefinierten Anbieters von Wiederholungslogik sind Sie für alle Aspekte verantwortlich, einschließlich Parallelität, Leistung und Ausnahmeverwaltung.

Beispiel

Die Implementierung in diesem Beispiel ist so einfach wie möglich, um eine schrittweise Anpassung zu zeigen. Sie enthält keine erweiterten Methoden wie Threadsicherheit, Asynchronizität und Parallelität. Ausführliche Informationen zu einer echten Implementierung finden Sie in der vordefinierten Wiederholungslogik im GitHub-Repository „Microsoft.Data.SqlClient“.

  1. Definieren Sie benutzerdefinierte Klassen für konfigurierbare Wiederholungslogik:

    • Enumerator: Hiermit wird eine festgelegte Folge von Zeitintervallen definiert und der zulässige Zeitbereich von zwei Minuten auf vier Minuten erweitert.
    public class CustomEnumerator : SqlRetryIntervalBaseEnumerator
    {
        // Set the maximum acceptable time to 4 minutes
        private readonly TimeSpan _maxValue = TimeSpan.FromMinutes(4);
    
        public CustomEnumerator(TimeSpan timeInterval, TimeSpan maxTime, TimeSpan minTime)
            : base(timeInterval, maxTime, minTime) {}
    
        // Return fixed time on each request
        protected override TimeSpan GetNextInterval()
        {
            return GapTimeInterval;
        }
    
        // Override the validate method with the new time range validation
        protected override void Validate(TimeSpan timeInterval, TimeSpan maxTimeInterval, TimeSpan minTimeInterval)
        {
            if (minTimeInterval < TimeSpan.Zero || minTimeInterval > _maxValue)
            {
                throw new ArgumentOutOfRangeException(nameof(minTimeInterval));
            }
    
            if (maxTimeInterval < TimeSpan.Zero || maxTimeInterval > _maxValue)
            {
                throw new ArgumentOutOfRangeException(nameof(maxTimeInterval));
            }
    
            if (timeInterval < TimeSpan.Zero || timeInterval > _maxValue)
            {
                throw new ArgumentOutOfRangeException(nameof(timeInterval));
            }
    
            if (maxTimeInterval < minTimeInterval)
            {
                throw new ArgumentOutOfRangeException(nameof(minTimeInterval));
            }
        }
    }
    
    • Wiederholungslogik: Hiermit wird eine Wiederholungslogik für jeden Befehl implementiert, der nicht Teil einer aktiven Transaktion ist. Verringern Sie die Anzahl der Wiederholungen von 60 auf 20.
    public class CustomRetryLogic : SqlRetryLogicBase
    {
        // Maximum number of attempts
        private const int maxAttempts = 20;
    
        public CustomRetryLogic(int numberOfTries,
                                 SqlRetryIntervalBaseEnumerator enumerator,
                                 Predicate<Exception> transientPredicate)
        {
            if (!(numberOfTries > 0 && numberOfTries <= maxAttempts))
            {
                // 'numberOfTries' should be between 1 and 20.
                throw new ArgumentOutOfRangeException(nameof(numberOfTries));
            }
    
            // Assign parameters to the relevant properties
            NumberOfTries = numberOfTries;
            RetryIntervalEnumerator = enumerator;
            TransientPredicate = transientPredicate;
            Current = 0;
        }
    
        // Prepare this object for the next round
        public override void Reset()
        {
            Current = 0;
            RetryIntervalEnumerator.Reset();
        }
    
        public override bool TryNextInterval(out TimeSpan intervalTime)
        {
            intervalTime = TimeSpan.Zero;
            // First try has occurred before starting the retry process. 
            // Check if retry is still allowed
            bool result = Current < NumberOfTries - 1;
    
            if (result)
            {
                // Increase the number of attempts
                Current++;
                // It's okay if the RetryIntervalEnumerator gets to the last value before we've reached our maximum number of attempts.
                // MoveNext() will simply leave the enumerator on the final interval value and we will repeat that for the final attempts.
                RetryIntervalEnumerator.MoveNext();
                // Receive the current time from enumerator
                intervalTime = RetryIntervalEnumerator.Current;
            }
            return result;
        }
    }
    
    • Anbieter: Implementiert einen Wiederholungsanbieter, der bei synchronen Vorgängen ohne ein Retrying-Ereignis einen Wiederholungsversuch durchführt. Fügt TimeoutException die vorhandenen Fehlernummern für vorübergehende SqlException-Ausnahmen hinzu.
    public class CustomProvider : SqlRetryLogicBaseProvider
    {
        // Preserve the given retryLogic on creation
        public CustomProvider(SqlRetryLogicBase retryLogic)
        {
            RetryLogic = retryLogic;
        }
    
        public override TResult Execute<TResult>(object sender, Func<TResult> function)
        {
            // Create a list to save transient exceptions to report later if necessary
            IList<Exception> exceptions = new List<Exception>();
            // Prepare it before reusing
            RetryLogic.Reset();
            // Create an infinite loop to attempt the defined maximum number of tries
            do
            {
                try
                {
                    // Try to invoke the function
                    return function.Invoke();
                }
                // Catch any type of exception for further investigation
                catch (Exception e)
                {
                    // Ask the RetryLogic object if this exception is a transient error
                    if (RetryLogic.TransientPredicate(e))
                    {
                        // Add the exception to the list of exceptions we've retried on
                        exceptions.Add(e);
                        // Ask the RetryLogic for the next delay time before the next attempt to run the function
                        if (RetryLogic.TryNextInterval(out TimeSpan gapTime))
                        {
                            Console.WriteLine($"Wait for {gapTime} before next try");
                            // Wait before next attempt
                            Thread.Sleep(gapTime);
                        }
                        else
                        {
                            // Number of attempts has exceeded the maximum number of tries
                            throw new AggregateException("The number of retries has exceeded the maximum number of attempts.", exceptions);
                        }
                    }
                    else
                    {
                        // If the exception wasn't a transient failure throw the original exception
                        throw;
                    }
                }
            } while (true);
        }
    
        public override Task<TResult> ExecuteAsync<TResult>(object sender, Func<Task<TResult>> function, CancellationToken cancellationToken = default)
        {
            throw new NotImplementedException();
        }
    
        public override Task ExecuteAsync(object sender, Func<Task> function, CancellationToken cancellationToken = default)
        {
            throw new NotImplementedException();
        }
    }
    
  2. Erstellen Sie eine Wiederholungsanbieterinstanz, die aus den definierten benutzerdefinierten Typen besteht:

    public static SqlRetryLogicBaseProvider CreateCustomProvider(SqlRetryLogicOption options)
    {
        // 1. create an enumerator instance
        CustomEnumerator customEnumerator = new CustomEnumerator(options.DeltaTime, options.MaxTimeInterval, options.MinTimeInterval);
        // 2. Use the enumerator object to create a new RetryLogic instance
        CustomRetryLogic customRetryLogic = new CustomRetryLogic(5, customEnumerator, (e) => TransientErrorsCondition(e, options.TransientErrors));
        // 3. Create a provider using the RetryLogic object
        CustomProvider customProvider = new CustomProvider(customRetryLogic);
        return customProvider;
    }
    
    • Die folgende Funktion wertet anhand der angegebenen Liste von wiederholbaren Ausnahmen und der speziellen TimeoutException-Ausnahme eine Ausnahme aus, um zu ermitteln, ob sie wiederholbar ist:
    // Return true if the exception is a transient fault.
    private static bool TransientErrorsCondition(Exception e, IEnumerable<int> retriableConditions)
    {
        bool result = false;
    
        // Assess only SqlExceptions
        if (retriableConditions != null && e is SqlException ex)
        {
            foreach (SqlError item in ex.Errors)
            {
                // Check each error number to see if it is a retriable error number
                if (retriableConditions.Contains(item.Number))
                {
                    result = true;
                    break;
                }
            }
        }
        // Other types of exceptions can also be assessed
        else if (e is TimeoutException)
        {
            result = true;
        }
        return result;
    }
    
  3. Verwenden Sie die angepasste Wiederholungslogik:

    • Definieren Sie die Parameter für Wiederholungslogik:
    // Define the retry logic parameters
    var options = new SqlRetryLogicOption()
    {
        // Tries 5 times before throwing an exception
        NumberOfTries = 5,
        // Preferred gap time to delay before retry
        DeltaTime = TimeSpan.FromSeconds(1),
        // Maximum gap time for each delay time before retry
        MaxTimeInterval = TimeSpan.FromSeconds(20),
        // SqlException retriable error numbers
        TransientErrors = new int[] { 4060, 1024, 1025}
    };
    
    • Erstellen Sie einen benutzerdefinierten Wiederholungsanbieter:
    // Create a custom retry logic provider
    SqlRetryLogicBaseProvider provider = CustomRetry.CreateCustomProvider(options);
    
    // Assumes that connection is a valid SqlConnection object 
    // Set the retry logic provider on the connection instance
    connection.RetryLogicProvider = provider;
    // Establishing the connection will trigger retry if one of the given transient failure occurs.
    connection.Open();
    

Hinweis

Vergessen Sie nicht, den Switch für konfigurierbare Wiederholungslogik zu aktivieren, bevor Sie sie verwenden. Weitere Informationen finden Sie unter Aktivieren der konfigurierbaren Wiederholungslogik.

Weitere Informationen