#5304 Added Retry/Failure Logic & Polly Integration section to the Dynamic-CSharp-API-Clients document.

docs/en/API/Dynamic-CSharp-API-Clients.md

@@ -1,10 +1,23 @@
 # Dynamic C# API Client Proxies
 
-ABP can dynamically create C# API client proxies to call remote HTTP services (REST APIs). In this way, you don't need to deal with `HttpClient` and other low level HTTP features to call remote services and get results.
+ABP can dynamically create C# API client proxies to call your remote HTTP services (REST APIs). In this way, you don't need to deal with `HttpClient` and other low level details to call remote services and get results.
+
+Dynamic C# proxies automatically handles the following stuff for you;
+
+* Maps C# **method calls** to remote server **HTTP calls** by considering the HTTP method, route, query string parameters, request payload and other details.
+* **Authenticates** the HTTP Client by adding access token to the HTTP header.
+* **Serializes** to and deserialize from JSON.
+* Handles HTTP API **versioning**.
+* Add **correlation id**, current **tenant** id and the current **culture** to the request.
+* Properly **handles the error messages** sent by the server and throws proper exceptions.
+
+This system can be used by any type of .NET client to consume your HTTP APIs.
 
 ## Service Interface
 
-Your service/controller should implement an interface that is shared between the server and the client. So, first define a service interface in a shared library project. Example:
+Your service/controller should implement an interface that is shared between the server and the client. So, first define a service interface in a shared library project, typically in the `Application.Contracts` project if you've created your solution using the startup templates.
+
+Example:
 
 ````csharp
 public interface IBookAppService : IApplicationService
@@ -13,7 +26,7 @@ public interface IBookAppService : IApplicationService
 }
 ````
 
-Your interface should implement the `IRemoteService` interface to be automatically discovered. Since the `IApplicationService` inherits the `IRemoteService` interface, the `IBookAppService` above satisfies this condition.
+> Your interface should implement the `IRemoteService` interface to be automatically discovered. Since the `IApplicationService` inherits the `IRemoteService` interface, the `IBookAppService` above satisfies this condition.
 
 Implement this class in your service application. You can use [auto API controller system](Auto-API-Controllers.md) to expose the service as a REST API endpoint.
 
@@ -55,6 +68,8 @@ public class MyClientAppModule : AbpModule
 
 `AddHttpClientProxies` method gets an assembly, finds all service interfaces in the given assembly, creates and registers proxy classes.
 
+> The startup templates already comes pre-configured for the client proxy generation, in the `HttpApi.Client` project.
+
 ### Endpoint Configuration
 
 `RemoteServices` section in the `appsettings.json` file is used to get remote service address by default. Simplest configuration is shown below:
@@ -106,7 +121,7 @@ While you can inject `IBookAppService` like above to use the client proxy, you c
 
 ### AbpRemoteServiceOptions
 
-`AbpRemoteServiceOptions` is automatically set from the `appsettings.json` by default. Alternatively, you can use `Configure` method to set or override it. Example:
+`AbpRemoteServiceOptions` is automatically set from the `appsettings.json` by default. Alternatively, you can configure it in the `ConfigureServices` method of your [module](../Module-Development-Basics.md) to set or override it. Example:
 
 ````csharp
 public override void ConfigureServices(ServiceConfigurationContext context)
@@ -162,4 +177,30 @@ context.Services.AddHttpClientProxies(
 
 Using `asDefaultServices: false` may only be needed if your application has already an implementation of the service and you do not want to override/replace the other implementation by your client proxy.
 
-> If you disable `asDefaultServices`, you can only use `IHttpClientProxy<T>` interface to use the client proxies. See the *IHttpClientProxy Interface* section above.
+> If you disable `asDefaultServices`, you can only use `IHttpClientProxy<T>` interface to use the client proxies. See the *IHttpClientProxy Interface* section above.
+
+### Retry/Failure Logic & Polly Integration
+
+If you want to add retry logic for the failing remote HTTP calls for the client proxies, you can configure the `AbpHttpClientBuilderOptions` in the `PreConfigureServices` method of your module class.
+
+**Example: Use the [Polly](https://github.com/App-vNext/Polly) library to re-try 3 times on a failure**
+
+````csharp
+public override void PreConfigureServices(ServiceConfigurationContext context)
+{
+    PreConfigure<AbpHttpClientBuilderOptions>(options =>
+    {
+        options.ProxyClientBuildActions.Add((remoteServiceName, clientBuilder) =>
+        {
+            clientBuilder.AddTransientHttpErrorPolicy(policyBuilder =>
+                policyBuilder.WaitAndRetryAsync(
+                    3,
+                    i => TimeSpan.FromSeconds(Math.Pow(2, i))
+                )
+            );
+        });
+    });
+}
+````
+
+This example uses the [Microsoft.Extensions.Http.Polly](https://www.nuget.org/packages/Microsoft.Extensions.Http.Polly) package. You also need to import the `Polly` namespace (`using Polly;`) to be able to use the `WaitAndRetryAsync` method.