fix: do not dispose caller-supplied HttpClients

Author: anthonyreilly

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ### 2026-10-06 v6.0.1
 
+* fix: ForceClient, JsonClient and AuthenticationClient no longer dispose an HttpClient passed in by the caller - the caller owns it
+    - AuthenticationClient still disposes the HttpClient it creates when none is passed
+    - ForceClient now disposes the AuthenticationClient it uses internally to log in
+
 ### 2026-10-06 v6.0.0
 
 * **breaking** build: remove EOL target frameworks

docs/auth.md

@@ -123,6 +123,8 @@ HttpClient proxyClient = HttpClientFactory.CreateHttpClient(true, "http://your-p
 ForceClient client = new ForceClient("your-client-id", "your-client-secret", "your-username", "your-password", "https://login.salesforce.com/services/oauth2/token", httpClient: proxyClient);
 ```
 
+The caller owns an `HttpClient` passed in this way - disposing `ForceClient`, `JsonClient` or `AuthenticationClient` does not dispose it, so a single long-lived instance can be shared across clients.
+
 ---
 
 ## Error Handling

src/NetCoreForce.Client.Tests/DisposeTests.cs

@@ -0,0 +1,66 @@
+using System;
+using System.Net;
+using System.Net.Http;
+using System.Threading.Tasks;
+using NetCoreForce.Client;
+using Xunit;
+
+namespace NetCoreForce.Client.Tests
+{
+    /// <summary>
+    /// A caller-supplied HttpClient is owned by the caller, and should still be usable after the client using it is disposed
+    /// </summary>
+    public class DisposeTests
+    {
+        const string TestUrl = "http://example.org/test";
+
+        [Fact]
+        public async Task ForceClientDisposeLeavesCallerHttpClientUsable()
+        {
+            HttpClient httpClient = CreateHttpClient();
+
+            ForceClient client = new ForceClient("https://na15.salesforce.com", "v57.0", "dummyToken", httpClient);
+            client.Dispose();
+
+            await AssertHttpClientUsable(httpClient);
+        }
+
+        [Fact]
+        public async Task JsonClientDisposeLeavesCallerHttpClientUsable()
+        {
+            HttpClient httpClient = CreateHttpClient();
+
+            JsonClient client = new JsonClient("dummyToken", httpClient);
+            client.Dispose();
+
+            await AssertHttpClientUsable(httpClient);
+        }
+
+        [Fact]
+        public async Task AuthenticationClientDisposeLeavesCallerHttpClientUsable()
+        {
+            HttpClient httpClient = CreateHttpClient();
+
+            AuthenticationClient client = new AuthenticationClient(httpClient: httpClient);
+            client.Dispose();
+
+            await AssertHttpClientUsable(httpClient);
+        }
+
+        private static HttpClient CreateHttpClient()
+        {
+            var mockHandler = new MockHttpClientHandler();
+            mockHandler.AddMockResponse(new Uri(TestUrl), new HttpResponseMessage(HttpStatusCode.OK));
+
+            return new HttpClient(mockHandler);
+        }
+
+        private static async Task AssertHttpClientUsable(HttpClient httpClient)
+        {
+            // throws ObjectDisposedException if the HttpClient was disposed
+            var response = await httpClient.GetAsync(TestUrl);
+
+            Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+        }
+    }
+}

src/NetCoreForce.Client/AuthenticationClient.cs

@@ -24,6 +24,7 @@ public class AuthenticationClient : IDisposable
         private const string IntrospectTokenEndpointUrl = "https://login.salesforce.com/services/oauth2/introspect";
         private const string TokenRequestEndpointUrl = "https://login.salesforce.com/services/oauth2/token";
         private readonly HttpClient _httpClient;
+        private readonly bool _disposeHttpClient;
 
         /// <summary>
         /// Initialize the AuthenticationClient with the libary's default Salesforce API version, and default HttpClient
@@ -35,7 +36,7 @@ public AuthenticationClient() : this(null, null) { }
         /// Initialize the AuthenticationClient with the specified Salesforce API version and/or HttpClient
         /// </summary>
         /// <param name="apiVersion">Target Salesforce API version</param>
-        /// <param name="httpClient">Custom HttpClient (Optional)</param>
+        /// <param name="httpClient">Custom HttpClient (Optional). Not disposed by this client; the caller retains ownership.</param>
         public AuthenticationClient(string apiVersion = null, HttpClient httpClient = null)
         {
             if (!string.IsNullOrEmpty(apiVersion))
@@ -47,6 +48,8 @@ public AuthenticationClient(string apiVersion = null, HttpClient httpClient = nu
                 ApiVersion = DefaultApiVersion;
             }
 
+            //only dispose the HttpClient if this client created it
+            _disposeHttpClient = httpClient == null;
             _httpClient = httpClient ?? new HttpClient();
         }
 
@@ -365,9 +368,16 @@ public async Task ClientCredentialsAsync(string clientId, string clientSecret,st
             }
         }
 
+        /// <summary>
+        /// Dispose client - only disposes the HttpClient if this client created it.
+        /// <para>A caller-supplied HttpClient is owned by the caller, and is left as-is.</para>
+        /// </summary>
         public void Dispose()
         {
-            _httpClient.Dispose();
+            if (_disposeHttpClient)
+            {
+                _httpClient.Dispose();
+            }
         }
     }
 }

src/NetCoreForce.Client/ForceClient.cs

@@ -113,25 +113,31 @@ public ForceClient(string instanceUrl, string apiVersion, string accessToken, Ht
         /// <param name="httpClient">Optional HttpClient object. Defaults to a shared static instance for best performance, but a custom HttpClient can be specified when custom properties are needed e.g. proxy settings.</param>
         public static async Task<ForceClient> FromClientCredentialsAsync(string clientId, string clientSecret, string tokenRequestEndpoint, string apiVersion = null, HttpClient httpClient = null)
         {
-            AuthenticationClient authClient = new AuthenticationClient(apiVersion, httpClient);
-            await authClient.ClientCredentialsAsync(clientId, clientSecret, tokenRequestEndpoint).ConfigureAwait(false);
-            return new ForceClient(authClient.AccessInfo.InstanceUrl, authClient.ApiVersion, authClient.AccessInfo.AccessToken, httpClient, authClient.AccessInfo);
+            using (AuthenticationClient authClient = new AuthenticationClient(apiVersion, httpClient))
+            {
+                await authClient.ClientCredentialsAsync(clientId, clientSecret, tokenRequestEndpoint).ConfigureAwait(false);
+                return new ForceClient(authClient.AccessInfo.InstanceUrl, authClient.ApiVersion, authClient.AccessInfo.AccessToken, httpClient, authClient.AccessInfo);
+            }
         }
 
         private async Task Login(string clientId, string clientSecret, string username, string password, string tokenRequestEndpoint, string apiVersion = null, HttpClient httpClient = null)
         {
-            AuthenticationClient authClient = new AuthenticationClient(apiVersion, httpClient);
-            await authClient.UsernamePasswordAsync(clientId, clientSecret, username, password, tokenRequestEndpoint).ConfigureAwait(false);
+            using (AuthenticationClient authClient = new AuthenticationClient(apiVersion, httpClient))
+            {
+                await authClient.UsernamePasswordAsync(clientId, clientSecret, username, password, tokenRequestEndpoint).ConfigureAwait(false);
 
-            Initialize(authClient.AccessInfo.InstanceUrl, authClient.ApiVersion, authClient.AccessInfo.AccessToken, httpClient, authClient.AccessInfo);
+                Initialize(authClient.AccessInfo.InstanceUrl, authClient.ApiVersion, authClient.AccessInfo.AccessToken, httpClient, authClient.AccessInfo);
+            }
         }
 
         private async Task LoginClientCredentials(string clientId, string clientSecret, string tokenRequestEndpoint, string apiVersion = null, HttpClient httpClient = null)
         {
-            AuthenticationClient authClient = new AuthenticationClient(apiVersion, httpClient);
-            await authClient.ClientCredentialsAsync(clientId, clientSecret, tokenRequestEndpoint).ConfigureAwait(false);
+            using (AuthenticationClient authClient = new AuthenticationClient(apiVersion, httpClient))
+            {
+                await authClient.ClientCredentialsAsync(clientId, clientSecret, tokenRequestEndpoint).ConfigureAwait(false);
 
-            Initialize(authClient.AccessInfo.InstanceUrl, authClient.ApiVersion, authClient.AccessInfo.AccessToken, httpClient, authClient.AccessInfo);
+                Initialize(authClient.AccessInfo.InstanceUrl, authClient.ApiVersion, authClient.AccessInfo.AccessToken, httpClient, authClient.AccessInfo);
+            }
         }
 
         private void Initialize(string instanceUrl, string apiVersion, string accessToken, HttpClient httpClient = null, AccessTokenResponse accessInfo = null)
@@ -988,15 +994,11 @@ public async Task<DescribeGlobal> DescribeGlobal()
         #endregion
 
         /// <summary>
-        /// Dispose client - only disposes instance HttpClient, if any. Shared static HttpClient is left as-is.
+        /// Dispose client - does not dispose the HttpClient.
+        /// <para>A caller-supplied HttpClient is owned by the caller, and the shared static HttpClient is left as-is.</para>
         /// </summary>
         public void Dispose()
         {
-            //only dispose instance member, if any
-            if (_httpClient != null)
-            {
-                _httpClient.Dispose();
-            }
         }
     }
 }

src/NetCoreForce.Client/JsonClient.cs

@@ -355,15 +355,11 @@ private IEnumerable<string> GetHeaderValues(HttpHeaders headers, string headerNa
         }
 
         /// <summary>
-        /// Dispose client - only disposes instance HttpClient, if any. Shared static HttpClient is left as-is.
+        /// Dispose client - does not dispose the HttpClient.
+        /// <para>A caller-supplied HttpClient is owned by the caller, and the shared static HttpClient is left as-is.</para>
         /// </summary>
         public void Dispose()
         {
-            //only dispose instance member, if any
-            if (_httpClient != null)
-            {
-                _httpClient.Dispose();
-            }
         }
     }
 }