Skip to content

configurable-retry-logic-sqlclient-introduction.md

Latest commit

 

History

History
55 lines (38 loc) · 4 KB

configurable-retry-logic-sqlclient-introduction.md

File metadata and controls

55 lines (38 loc) · 4 KB
title Configurable retry logic in SqlClient introduction
description Learn about the different aspects of configurable retry logic in Microsoft.Data.SqlClient and how to make your application resilient to transient errors.
author David-Engel
ms.author davidengel
ms.reviewer v-deshtehari
ms.date 03/22/2021
ms.service sql
ms.subservice connectivity
ms.topic concept-article

Configurable retry logic in SqlClient introduction

[!INCLUDE dotnet-all]

[!INCLUDEDriver_ADONET_Download]

Configurable retry logic lets developers and administrators manage application behavior when transient faults happen. The feature adds controls during connection or execution of a command. The controls can be defined through code or an application configuration file. Transient error numbers and retry properties can be defined to control retry behavior. Also, regular expressions can be used to filter specific SQL statements.

Feature components

This feature consists of three main components:

  1. Core APIs: Developers can use these interfaces to implement their own retry logic on xref:Microsoft.Data.SqlClient.SqlConnection and xref:Microsoft.Data.SqlClient.SqlCommand objects. For more information, see Configurable retry logic core APIs in SqlClient.
  2. Pre-defined configurable retry logic: Built-in retry logic methods using the core APIs are accessible from the xref:Microsoft.Data.SqlClient.SqlConfigurableRetryFactory class. For more information, see Internal retry logic providers in SqlClient.
  3. Configuration file schema: To specify the default retry logic for xref:Microsoft.Data.SqlClient.SqlConnection and xref:Microsoft.Data.SqlClient.SqlCommand in an application. For more information, see Configurable retry logic configuration file with SqlClient.

Quick start

To use this feature, follow these steps:

  1. Define the retry logic options using xref:Microsoft.Data.SqlClient.SqlRetryLogicOption.
    In this sample, some of the retry parameters are set and the rest of them will use the default values.

    [!code-csharpSqlConfigurableRetryLogic_StepByStep_OpenConnection#1]

  2. Create a retry logic provider using your xref:Microsoft.Data.SqlClient.SqlRetryLogicOption object.

    [!code-csharpSqlConfigurableRetryLogic_StepByStep_OpenConnection#2]

  3. Assign the xref:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider instance to the xref:Microsoft.Data.SqlClient.SqlConnection.RetryLogicProvider%2A?displayProperty=nameWithType or xref:Microsoft.Data.SqlClient.SqlCommand.RetryLogicProvider%2A?displayProperty=nameWithType.
    In this sample, the connection open command will retry if it hits one of the transient errors in the xref:Microsoft.Data.SqlClient.SqlConfigurableRetryFactory internal list for a maximum of five times.

    [!code-csharpSqlConfigurableRetryLogic_StepByStep_OpenConnection#3]

Note

These steps are the same for a command execution, except you would instead assign the retry provider to the xref:Microsoft.Data.SqlClient.SqlCommand.RetryLogicProvider%2A?displayProperty=nameWithType property before executing the command.

See also