feat: add IHttpClientFactory support for FileMaker clients (#417)

Author: fuzzzerd

README.md

@@ -83,43 +83,76 @@ public class Model
 }
 ```
 
-### Using IHttpClientFactory
+### Using Dependency Injection (Recommended)
 
-Constructors take an `HttpClient` and you can setup the DI pipeline in Startup.cs like so for standard use:
+The simplest way to register FMData with dependency injection is using the built-in extension method. This sets up `IHttpClientFactory`, registers `ConnectionInfo`, and configures the client as a singleton (preserving auth token state across requests):
 
 ```csharp
-services.AddSingleton<FMData.ConnectionInfo>(ci => new FMData.ConnectionInfo
+services.AddFMDataRest(conn =>
 {
-    FmsUri = "https://example.com",
-    Username = "user",
-    Password = "password",
-    Database = "FILE_NAME"
+    conn.FmsUri = "https://example.com";
+    conn.Database = "FILE_NAME";
+    conn.Username = "user";
+    conn.Password = "password";
+});
+```
+
+This registers both `IFileMakerApiClient` and `IFileMakerRestClient`. You can also pass a callback to configure the underlying `HttpClient` (e.g., to set timeouts):
+
+```csharp
+services.AddFMDataRest(
+    conn =>
+    {
+        conn.FmsUri = "https://example.com";
+        conn.Database = "FILE_NAME";
+        conn.Username = "user";
+        conn.Password = "password";
+    },
+    httpClient =>
+    {
+        httpClient.Timeout = TimeSpan.FromSeconds(30);
+    });
+```
+
+The method returns an `IHttpClientBuilder`, so you can chain additional configuration like retry policies.
+
+For the XML client, use `AddFMDataXml` from the `FMData.Xml` namespace:
+
+```csharp
+services.AddFMDataXml(conn =>
+{
+    conn.FmsUri = "https://example.com";
+    conn.Database = "FILE_NAME";
+    conn.Username = "user";
+    conn.Password = "password";
 });
-services.AddHttpClient<IFileMakerApiClient, FileMakerRestClient>();
 ```
 
-If you prefer to use a singleton instance of `IFileMakerApiClient` you have to do a little bit more work in startup. This can improve performance if you're making lots of hits to the Data API over a single request to your application:
+> **Note:** The `AddFMDataRest` and `AddFMDataXml` extension methods require netstandard2.0 or later. If you are targeting netstandard1.3 or net45, use the manual approach below.
+
+#### Manual Registration
+
+You can also construct the client with an `IHttpClientFactory` directly:
+
+```csharp
+var factory = serviceProvider.GetRequiredService<IHttpClientFactory>();
+var client = new FileMakerRestClient(factory, connectionInfo);
+```
+
+Or use the traditional `HttpClient`-based approach:
 
 ```csharp
-services.AddHttpClient(); // setup IHttpClientFactory in the DI container
 services.AddSingleton<FMData.ConnectionInfo>(ci => new FMData.ConnectionInfo
 {
     FmsUri = "https://example.com",
     Username = "user",
     Password = "password",
     Database = "FILE_NAME"
 });
-// Keep the FileMaker client as a singleton for speed
-services.AddSingleton<IFileMakerApiClient, FileMakerRestClient>(s => {
-    var hcf = s.GetRequiredService<IHttpClientFactory>();
-    var ci = s.GetRequiredService<ConnectionInfo>();
-    return new FileMakerRestClient(hcf.CreateClient(), ci);
-});
+services.AddHttpClient<IFileMakerApiClient, FileMakerRestClient>();
 ```
 
-Behind the scenes, the injected `HttpClient` is kept alive for the lifetime of the FMData client (rest/xml) and reused throughout. This is useful to manage the lifetime of `IFileMakerApiClient` as a singleton, since it stores data about FileMaker Data API tokens and reuses them as much as possible. Simply using `services.AddHttpClient<IFileMakerApiClient, FileMakerRestClient>();` keeps the lifetime of our similar to that of a 'managed `HttpClient`' which works for simple scenarios.
-
-Test both approaches in your solution and use what works.
+Behind the scenes, the injected `HttpClient` is kept alive for the lifetime of the FMData client (rest/xml) and reused throughout. The client stores FileMaker Data API tokens and reuses them as much as possible.
 
 ### Authentication with FileMaker Cloud
 

docs/configuration.md

@@ -36,11 +36,75 @@ conn.RestTargetVersion = RestTargetVersion.vLatest;
 var client = new FileMakerRestClient(new HttpClient(), conn);
 ```
 
+Or using `IHttpClientFactory` (available on netstandard2.0+):
+
+```csharp
+var client = new FileMakerRestClient(httpClientFactory, conn);
+```
+
+When constructed with `IHttpClientFactory`, the client uses factory-managed clients for container downloads, avoiding connection pool exhaustion from creating ad-hoc `HttpClient` instances.
+
 ### Using Dependency Injection
 
-#### Standard (Scoped) Lifetime
+#### Using Extension Methods (Recommended)
+
+The simplest approach uses the built-in `AddFMDataRest` extension method, which handles all registration in one call:
+
+```csharp
+services.AddFMDataRest(conn =>
+{
+    conn.FmsUri = "https://your-server.com";
+    conn.Database = "YourDatabase";
+    conn.Username = "admin";
+    conn.Password = "password";
+});
+```
+
+This registers:
+
+- `ConnectionInfo` as a singleton
+- `IAuthTokenProvider` (using `DefaultAuthTokenProvider`)
+- A named `HttpClient` via `IHttpClientFactory`
+- `FileMakerRestClient` as a singleton, available as both `IFileMakerApiClient` and `IFileMakerRestClient`
+
+You can optionally configure the underlying `HttpClient`:
+
+```csharp
+services.AddFMDataRest(
+    conn =>
+    {
+        conn.FmsUri = "https://your-server.com";
+        conn.Database = "YourDatabase";
+        conn.Username = "admin";
+        conn.Password = "password";
+    },
+    httpClient =>
+    {
+        httpClient.Timeout = TimeSpan.FromSeconds(30);
+    });
+```
+
+The method returns `IHttpClientBuilder`, which lets you chain additional configuration such as retry policies or custom message handlers.
+
+For the XML/CWP client, use `AddFMDataXml` from the `FMData.Xml` namespace:
+
+```csharp
+services.AddFMDataXml(conn =>
+{
+    conn.FmsUri = "https://your-server.com";
+    conn.Database = "YourDatabase";
+    conn.Username = "admin";
+    conn.Password = "password";
+});
+```
+
+> **Note:** The `AddFMDataRest` and `AddFMDataXml` extension methods require netstandard2.0 or later.
+
+#### Manual Registration
+
+If you prefer manual control or are targeting netstandard1.3/net45, you can wire up registration yourself.
 
-Register `IFileMakerApiClient` with `AddHttpClient` for managed `HttpClient` lifetime:
+**Standard (Scoped) Lifetime:**
 
 ```csharp
 services.AddSingleton<ConnectionInfo>(new ConnectionInfo
@@ -56,7 +120,7 @@ services.AddHttpClient<IFileMakerApiClient, FileMakerRestClient>();
 
 This creates a new `FileMakerRestClient` per scope (typically per HTTP request in ASP.NET Core).
 
-#### Singleton Lifetime
+**Singleton Lifetime:**
 
 For better performance when making many Data API calls per request, register as a singleton:
 

src/FMData.Rest/FMData.Rest.csproj

@@ -63,4 +63,8 @@
   <ItemGroup Condition="$(TargetFramework) == 'net45'">
     <PackageReference Include="System.ValueTuple" Version="4.5.0" />
   </ItemGroup>
+
+  <ItemGroup Condition="'$(TargetFramework)' != 'netstandard1.3' AND '$(TargetFramework)' != 'net45'">
+    <PackageReference Include="Microsoft.Extensions.Http" Version="8.0.0" />
+  </ItemGroup>
 </Project>

src/FMData.Rest/FileMakerRestClient.cs

@@ -12,6 +12,9 @@
 using FMData.Rest.Responses;
 using Newtonsoft.Json;
 using Newtonsoft.Json.Linq;
+#if NETSTANDARD2_0_OR_GREATER || NET6_0_OR_GREATER
+using Microsoft.Extensions.DependencyInjection;
+#endif
 
 namespace FMData.Rest
 {
@@ -55,7 +58,40 @@ public class FileMakerRestClient : FileMakerApiClientBase, IFileMakerRestClient
         private readonly bool _useNewClientForContainers = false;
         private readonly string _targetVersion = "v1";
 
+#if NETSTANDARD2_0_OR_GREATER || NET6_0_OR_GREATER
+        private readonly IHttpClientFactory _httpClientFactory;
+#endif
+
         #region Constructors
+
+#if NETSTANDARD2_0_OR_GREATER || NET6_0_OR_GREATER
+        /// <summary>
+        /// FM Data Constructor with IHttpClientFactory and ConnectionInfo.
+        /// Uses the factory to create the primary HttpClient and for container downloads.
+        /// </summary>
+        /// <param name="httpClientFactory">The IHttpClientFactory to use for creating HttpClient instances.</param>
+        /// <param name="conn">The connection information for FMS.</param>
+        public FileMakerRestClient(
+            IHttpClientFactory httpClientFactory,
+            ConnectionInfo conn)
+            : this(httpClientFactory, new DefaultAuthTokenProvider(conn))
+        { }
+
+        /// <summary>
+        /// FM Data Constructor with IHttpClientFactory and an authentication provider.
+        /// Uses the factory to create the primary HttpClient and for container downloads.
+        /// </summary>
+        /// <param name="httpClientFactory">The IHttpClientFactory to use for creating HttpClient instances.</param>
+        /// <param name="authTokenProvider">Authentication provider.</param>
+        public FileMakerRestClient(
+            IHttpClientFactory httpClientFactory,
+            IAuthTokenProvider authTokenProvider)
+            : this(httpClientFactory.CreateClient(), authTokenProvider, false)
+        {
+            _httpClientFactory = httpClientFactory;
+        }
+#endif
+
         /// <summary>
         /// Create a FileMakerRestClient with a new instance of HttpClient.
         /// </summary>
@@ -1137,11 +1173,20 @@ protected override async Task<byte[]> GetContainerOnClient(string containerEndPo
             // build the request message
             var requestMessage = new HttpRequestMessage(HttpMethod.Get, containerEndPoint);
 
+            // determine the client to use for container downloads
+#if NETSTANDARD2_0_OR_GREATER || NET6_0_OR_GREATER
+            // prefer factory-created clients when available (proper handler pooling)
+            var client = _httpClientFactory != null
+                ? _httpClientFactory.CreateClient()
+                : (_useNewClientForContainers
+                    ? new HttpClient(new HttpClientHandler() { CookieContainer = new CookieContainer() })
+                    : Client);
+#else
             // if we're supposed to use new clients for processing containers or not
-            var client = _useNewClientForContainers ? new HttpClient(new HttpClientHandler()
-            {
-                CookieContainer = new CookieContainer()
-            }) : Client;
+            var client = _useNewClientForContainers
+                ? new HttpClient(new HttpClientHandler() { CookieContainer = new CookieContainer() })
+                : Client;
+#endif
 
             // send the request out
             var data = await client.SendAsync(requestMessage).ConfigureAwait(false);
@@ -1214,18 +1259,12 @@ private async Task<HttpResponseMessage> RetryOnUnauthorizedAsync(Func<Task<HttpR
             return response;
         }
 
-        /// <summary>
-        /// Converts a JToken instance and maps it to the generic type.
-        /// </summary>
-        /// <typeparam name="T"></typeparam>
-        /// <param name="fmId">FileMaker Record Id map function.</param>
-        /// <param name="modId">Modification Id map function.</param>
-        /// <param name="input">JSON.NET JToken instance from Data Api Response.</param>
-        /// <returns></returns>
         /// <summary>
         /// Extracts script result fields (including pre-request and pre-sort) from a response JToken.
         /// Handles dotted property names that cannot be mapped via attributes.
         /// </summary>
+        /// <param name="target">The <see cref="ActionResponse"/> to populate with script results.</param>
+        /// <param name="responseToken">JSON.NET JToken from the Data API response body.</param>
         private static void PopulateScriptResults(ActionResponse target, JToken responseToken)
         {
             if (target == null || responseToken == null) return;

src/FMData.Rest/ServiceCollectionExtensions.cs

@@ -0,0 +1,68 @@
+#if NETSTANDARD2_0_OR_GREATER || NET6_0_OR_GREATER
+using System;
+using System.Net;
+using System.Net.Http;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace FMData.Rest
+{
+    /// <summary>
+    /// Extension methods for registering FileMakerRestClient with dependency injection.
+    /// </summary>
+    public static class ServiceCollectionExtensions
+    {
+        /// <summary>
+        /// Adds a <see cref="FileMakerRestClient"/> to the service collection using <see cref="IHttpClientFactory"/>.
+        /// Registers the client as both <see cref="IFileMakerApiClient"/> and <see cref="IFileMakerRestClient"/>.
+        /// </summary>
+        /// <param name="services">The service collection.</param>
+        /// <param name="configureConnection">Action to configure the connection info.</param>
+        /// <returns>The <see cref="IHttpClientBuilder"/> for further HTTP client configuration.</returns>
+        public static IHttpClientBuilder AddFMDataRest(
+            this IServiceCollection services,
+            Action<ConnectionInfo> configureConnection)
+        {
+            return AddFMDataRest(services, configureConnection, null);
+        }
+
+        /// <summary>
+        /// Adds a <see cref="FileMakerRestClient"/> to the service collection using <see cref="IHttpClientFactory"/>.
+        /// Registers the client as both <see cref="IFileMakerApiClient"/> and <see cref="IFileMakerRestClient"/>.
+        /// </summary>
+        /// <param name="services">The service collection.</param>
+        /// <param name="configureConnection">Action to configure the connection info.</param>
+        /// <param name="configureHttpClient">Optional action to configure the HttpClient (e.g., set timeouts or default headers).</param>
+        /// <returns>The <see cref="IHttpClientBuilder"/> for further HTTP client configuration.</returns>
+        public static IHttpClientBuilder AddFMDataRest(
+            this IServiceCollection services,
+            Action<ConnectionInfo> configureConnection,
+            Action<HttpClient> configureHttpClient)
+        {
+            var conn = new ConnectionInfo();
+            configureConnection(conn);
+
+            services.AddSingleton(conn);
+            services.AddSingleton<IAuthTokenProvider>(new DefaultAuthTokenProvider(conn));
+
+            // Register the main FMData named client
+            var builder = services.AddHttpClient("FMData", client =>
+            {
+                configureHttpClient?.Invoke(client);
+            });
+
+            // Register FileMakerRestClient as singleton (preserves auth token state across requests)
+            services.AddSingleton<FileMakerRestClient>(sp =>
+            {
+                var factory = sp.GetRequiredService<IHttpClientFactory>();
+                var authProvider = sp.GetRequiredService<IAuthTokenProvider>();
+                return new FileMakerRestClient(factory, authProvider);
+            });
+
+            services.AddSingleton<IFileMakerApiClient>(sp => sp.GetRequiredService<FileMakerRestClient>());
+            services.AddSingleton<IFileMakerRestClient>(sp => sp.GetRequiredService<FileMakerRestClient>());
+
+            return builder;
+        }
+    }
+}
+#endif

src/FMData.Xml/FMData.Xml.csproj

@@ -63,4 +63,8 @@
   <ItemGroup Condition="$(TargetFramework) == 'net45'">
     <PackageReference Include="System.ValueTuple" Version="4.5.0" />
   </ItemGroup>
+
+  <ItemGroup Condition="'$(TargetFramework)' != 'netstandard1.3' AND '$(TargetFramework)' != 'net45'">
+    <PackageReference Include="Microsoft.Extensions.Http" Version="8.0.0" />
+  </ItemGroup>
 </Project>