Merge branch 'develop' into stable

Author: Pathoschild

Client/Client.csproj

@@ -5,34 +5,39 @@
     <RootNamespace>Pathoschild.Http.Client</RootNamespace>
     <PackageId>Pathoschild.Http.FluentClient</PackageId>
     <Title>FluentHttpClient</Title>
-    <Version>4.2.0</Version>
+    <Version>4.3.0</Version>
     <Authors>Pathoschild</Authors>
     <Description>A modern async HTTP client for REST APIs. Its fluent interface lets you send an HTTP request and parse the response in one go.</Description>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <PackageProjectUrl>https://github.com/Pathoschild/FluentHttpClient#readme</PackageProjectUrl>
     <PackageIcon>images/package-icon.png</PackageIcon>
     <RepositoryType>git</RepositoryType>
     <RepositoryUrl>https://github.com/Pathoschild/FluentHttpClient.git</RepositoryUrl>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
     <PackageReleaseNotes>See release notes at https://github.com/Pathoschild/FluentHttpClient/blob/develop/RELEASE-NOTES.md</PackageReleaseNotes>
     <PackageTags>wcf;web;webapi;HttpClient;FluentHttp;FluentHttpClient</PackageTags>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
 
     <LangVersion>latest</LangVersion>
     <Nullable>enable</Nullable>
+
+    <!-- suppress framework out of support warning (deliberate for compatibility with users' target frameworks, since .NET 5 is forward-compatible) -->
+    <CheckEolTargetFramework>false</CheckEolTargetFramework>
   </PropertyGroup>
 
   <ItemGroup Condition=" '$(TargetFramework)' != 'netstandard1.3' ">
-    <PackageReference Include="Microsoft.AspNet.WebApi.Client" Version="5.2.7" />
+    <PackageReference Include="Microsoft.AspNet.WebApi.Client" Version="5.2.9" />
   </ItemGroup>
 
   <ItemGroup Condition=" '$(TargetFramework)' == 'netstandard1.3' ">
-    <PackageReference Include="Newtonsoft.Json" Version="13.0.1" />
+    <PackageReference Include="Newtonsoft.Json" Version="13.0.2" />
     <PackageReference Include="System.Net.Http" Version="4.3.4" />
     <PackageReference Include="WinInsider.System.Net.Http.Formatting" Version="1.0.14" />
   </ItemGroup>
 
   <ItemGroup>
+    <None Include="../README.md" Pack="true" PackagePath="/" />
     <None Include="package-icon.png" Pack="true" PackagePath="images/" />
   </ItemGroup>
 </Project>

Client/FluentClient.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.Linq;
 using System.Net;
 using System.Net.Http;
@@ -14,6 +15,7 @@
 namespace Pathoschild.Http.Client
 {
     /// <inheritdoc cref="IClient" />
+    [SuppressMessage("ReSharper", "UnusedMember.Global", Justification = "This is a public API.")]
     public class FluentClient : IClient
     {
         /*********
@@ -29,7 +31,7 @@ public class FluentClient : IClient
         private readonly IList<Func<IRequest, IRequest>> Defaults = new List<Func<IRequest, IRequest>>();
 
         /// <summary>Options for the fluent client.</summary>
-        private readonly FluentClientOptions Options = new FluentClientOptions();
+        private readonly FluentClientOptions Options = new();
 
 
         /*********
@@ -42,9 +44,9 @@ public class FluentClient : IClient
         public HttpClient BaseClient { get; }
 
         /// <inheritdoc />
-        public MediaTypeFormatterCollection Formatters { get; } = new MediaTypeFormatterCollection();
+        public MediaTypeFormatterCollection Formatters { get; } = new();
 
-        /// <summary>The request coordinator.</summary>
+        /// <inheritdoc />
         public IRequestCoordinator? RequestCoordinator { get; private set; }
 
 
@@ -158,7 +160,7 @@ public virtual void Dispose()
         /// <summary>Set the default user agent header.</summary>
         private void SetDefaultUserAgent()
         {
-            Version version = typeof(FluentClient).GetTypeInfo().Assembly.GetName().Version;
+            Version version = typeof(FluentClient).GetTypeInfo().Assembly.GetName().Version!;
             this.SetUserAgent($"FluentHttpClient/{version} (+http://github.com/Pathoschild/FluentHttpClient)");
         }
 
@@ -170,7 +172,7 @@ protected virtual async Task<HttpResponseMessage> SendImplAsync(IRequest request
             this.AssertNotDisposed();
 
             // clone request (to avoid issues when resending messages)
-            HttpRequestMessage requestMessage = await request.Message.CloneAsync().ConfigureAwait(false);
+            HttpRequestMessage requestMessage = await request.Message.CloneAsync(request.CancellationToken).ConfigureAwait(false);
 
             // dispatch request
             return await this.BaseClient
@@ -220,7 +222,7 @@ private static HttpClientHandler GetDefaultHandler()
         /// <remarks>Whereas <see cref="GetDefaultHandler()"/> leaves the default proxy unchanged, this method will explicitly override it (e.g. setting a null proxy will disable the default proxy).</remarks>
         private static HttpClientHandler GetDefaultHandler(IWebProxy? proxy)
         {
-            var handler = FluentClient.GetDefaultHandler();
+            HttpClientHandler handler = FluentClient.GetDefaultHandler();
             handler.Proxy = proxy;
             handler.UseProxy = proxy != null;
             return handler;

Client/FluentClientExtensions.cs

@@ -1,9 +1,11 @@
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.IO;
 using System.Linq;
 using System.Net.Http;
 using System.Text;
+using System.Threading;
 using System.Threading.Tasks;
 using Pathoschild.Http.Client.Extensibility;
 using Pathoschild.Http.Client.Internal;
@@ -12,6 +14,7 @@
 namespace Pathoschild.Http.Client
 {
     /// <summary>Provides convenience methods for configuring the HTTP client.</summary>
+    [SuppressMessage("ReSharper", "UnusedMember.Global", Justification = "This is a public API.")]
     public static class FluentClientExtensions
     {
         /*********
@@ -127,8 +130,8 @@ public static IRequest PatchAsync<TBody>(this IClient client, string? resource,
         /// <exception cref="ObjectDisposedException">The instance has been disposed.</exception>
         public static IRequest SendAsync(this IClient client, HttpMethod method, string? resource)
         {
-            var uri = FluentClientExtensions.ResolveFinalUrl(client.BaseClient.BaseAddress, resource);
-            var message = Factory.GetRequestMessage(method, uri, client.Formatters);
+            Uri uri = FluentClientExtensions.ResolveFinalUrl(client.BaseClient.BaseAddress, resource) ?? throw new InvalidOperationException("Can't send a request with a null URL.");
+            HttpRequestMessage message = Factory.GetRequestMessage(method, uri, client.Formatters);
             return client.SendAsync(message);
         }
 
@@ -286,17 +289,23 @@ public static IRequest WithOptions(this IRequest request, bool? ignoreHttpErrors
         *********/
         /// <summary>Get a copy of the request.</summary>
         /// <param name="request">The request to copy.</param>
+        /// <param name="cancellationToken">The cancellation token.</param>
         /// <remarks>Note that cloning a request isn't possible after it's dispatched, because the content stream is automatically disposed after the request.</remarks>
-        internal static async Task<HttpRequestMessage> CloneAsync(this HttpRequestMessage request)
+        internal static async Task<HttpRequestMessage> CloneAsync(this HttpRequestMessage request, CancellationToken cancellationToken = default)
         {
-            HttpRequestMessage clone = new HttpRequestMessage(request.Method, request.RequestUri)
+            HttpRequestMessage clone = new(request.Method, request.RequestUri)
             {
-                Content = await request.Content.CloneAsync().ConfigureAwait(false),
+                Content = await request.Content.CloneAsync(cancellationToken).ConfigureAwait(false),
                 Version = request.Version
             };
 
+#if NET5_0_OR_GREATER
+            foreach ((string key, object? value) in request.Options)
+                clone.Options.Set(new HttpRequestOptionsKey<object?>(key), value);
+#else
             foreach (var prop in request.Properties)
                 clone.Properties.Add(prop);
+#endif
             foreach (var header in request.Headers)
                 clone.Headers.TryAddWithoutValidation(header.Key, header.Value);
 
@@ -305,17 +314,24 @@ internal static async Task<HttpRequestMessage> CloneAsync(this HttpRequestMessag
 
         /// <summary>Get a copy of the request content.</summary>
         /// <param name="content">The content to copy.</param>
+        /// <param name="cancellationToken">The cancellation token.</param>
         /// <remarks>Note that cloning content isn't possible after it's dispatched, because the stream is automatically disposed after the request.</remarks>
-        internal static async Task<HttpContent?> CloneAsync(this HttpContent? content)
+        internal static async Task<HttpContent?> CloneAsync(this HttpContent? content, CancellationToken cancellationToken = default)
         {
             if (content == null)
                 return null;
 
             Stream stream = new MemoryStream();
-            await content.CopyToAsync(stream).ConfigureAwait(false);
+            await content
+                .CopyToAsync(stream
+#if NET5_0_OR_GREATER
+                    , cancellationToken
+#endif
+                )
+                .ConfigureAwait(false);
             stream.Position = 0;
 
-            StreamContent clone = new StreamContent(stream);
+            StreamContent clone = new(stream);
             foreach (var header in content.Headers)
                 clone.Headers.Add(header.Key, header.Value);
 
@@ -325,12 +341,12 @@ internal static async Task<HttpRequestMessage> CloneAsync(this HttpRequestMessag
         /// <summary>Resolve the final URL for a request.</summary>
         /// <param name="baseUrl">The base URL.</param>
         /// <param name="resource">The requested resource, or <c>null</c> to use the base URL (if set).</param>
-        private static Uri ResolveFinalUrl(Uri baseUrl, string? resource)
+        private static Uri? ResolveFinalUrl(Uri? baseUrl, string? resource)
         {
             // ignore if empty or already absolute
             if (string.IsNullOrWhiteSpace(resource))
                 return baseUrl;
-            if (Uri.TryCreate(resource, UriKind.Absolute, out Uri absoluteUrl))
+            if (Uri.TryCreate(resource, UriKind.Absolute, out Uri? absoluteUrl))
                 return absoluteUrl;
 
             // can't combine if no base URL
@@ -339,7 +355,7 @@ private static Uri ResolveFinalUrl(Uri baseUrl, string? resource)
 
             // parse URLs
             resource = resource!.Trim();
-            UriBuilder builder = new UriBuilder(baseUrl);
+            UriBuilder builder = new(baseUrl);
 
             // special case: combine if either side is a fragment
             if (!string.IsNullOrWhiteSpace(builder.Fragment) || resource.StartsWith('#'))
@@ -349,11 +365,12 @@ private static Uri ResolveFinalUrl(Uri baseUrl, string? resource)
             if (resource.StartsWith('?') || resource.StartsWith('&'))
             {
                 bool baseHasQuery = !string.IsNullOrWhiteSpace(builder.Query);
-                if (baseHasQuery && resource.StartsWith('?'))
-                    throw new FormatException($"Can't add resource name '{resource}' to base URL '{baseUrl}' because the latter already has a query string.");
-                if (!baseHasQuery && resource.StartsWith('&'))
-                    throw new FormatException($"Can't add resource name '{resource}' to base URL '{baseUrl}' because the latter doesn't have a query string.");
-                return new Uri(baseUrl + resource);
+                return baseHasQuery switch
+                {
+                    true when resource.StartsWith('?') => throw new FormatException($"Can't add resource name '{resource}' to base URL '{baseUrl}' because the latter already has a query string."),
+                    false when resource.StartsWith('&') => throw new FormatException($"Can't add resource name '{resource}' to base URL '{baseUrl}' because the latter doesn't have a query string."),
+                    _ => new Uri(baseUrl + resource)
+                };
             }
 
             // else make absolute URL

Client/Formatters/PlainTextFormatter.cs

@@ -42,14 +42,14 @@ public override bool CanWriteType(Type type)
         /// <inheritdoc />
         public override object Deserialize(Type type, Stream stream, HttpContent content, IFormatterLogger formatterLogger)
         {
-            var reader = new StreamReader(stream); // don't dispose (stream disposal is handled elsewhere)
+            StreamReader reader = new(stream); // don't dispose (stream disposal is handled elsewhere)
             return reader.ReadToEnd();
         }
 
         /// <inheritdoc />
         public override void Serialize(Type type, object? value, Stream stream, HttpContent content, TransportContext transportContext)
         {
-            var writer = new StreamWriter(stream); // don't dispose (stream disposal is handled elsewhere)
+            StreamWriter writer = new(stream); // don't dispose (stream disposal is handled elsewhere)
             writer.Write(value != null ? value.ToString() : string.Empty);
             writer.Flush();
         }

Client/IBodyBuilder.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.IO;
 using System.Net.Http;
 using System.Net.Http.Formatting;
@@ -8,6 +9,7 @@
 namespace Pathoschild.Http.Client
 {
     /// <summary>Constructs HTTP request bodies.</summary>
+    [SuppressMessage("ReSharper", "UnusedMember.Global", Justification = "This is a public API.")]
     public interface IBodyBuilder
     {
         /*********

Client/IClient.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.Net.Http;
 using System.Net.Http.Formatting;
 using Pathoschild.Http.Client.Extensibility;
@@ -8,6 +9,7 @@
 namespace Pathoschild.Http.Client
 {
     /// <summary>Sends HTTP requests and receives responses from REST URIs.</summary>
+    [SuppressMessage("ReSharper", "UnusedMemberInSuper.Global", Justification = "This is a public API.")]
     public interface IClient : IDisposable
     {
         /*********
@@ -22,6 +24,9 @@ public interface IClient : IDisposable
         /// <summary>Interceptors which can read and modify HTTP requests and responses.</summary>
         ICollection<IHttpFilter> Filters { get; }
 
+        /// <summary>The request coordinator.</summary>
+        IRequestCoordinator? RequestCoordinator { get; }
+
 
         /*********
         ** Methods

Client/IRequest.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.IO;
 using System.Net.Http;
 using System.Net.Http.Formatting;
@@ -13,6 +14,8 @@
 namespace Pathoschild.Http.Client
 {
     /// <summary>Builds and dispatches an asynchronous HTTP request, and asynchronously parses the response.</summary>
+    [SuppressMessage("ReSharper", "UnusedMember.Global", Justification = "This is a public API.")]
+    [SuppressMessage("ReSharper", "UnusedMemberInSuper.Global", Justification = "This is a public API.")]
     public interface IRequest
     {
         /*********

Client/IResponse.cs

@@ -1,13 +1,17 @@
+using System.Diagnostics.CodeAnalysis;
 using System.IO;
 using System.Net;
 using System.Net.Http;
 using System.Net.Http.Formatting;
+using System.Threading;
 using System.Threading.Tasks;
 using Newtonsoft.Json.Linq;
 
 namespace Pathoschild.Http.Client
 {
     /// <summary>Asynchronously parses an HTTP response.</summary>
+    [SuppressMessage("ReSharper", "UnusedMember.Global", Justification = "This is a public API.")]
+    [SuppressMessage("ReSharper", "UnusedMemberInSuper.Global", Justification = "This is a public API.")]
     public interface IResponse
     {
         /*********
@@ -25,10 +29,18 @@ public interface IResponse
         /// <summary>The formatters used for serializing and deserializing message bodies.</summary>
         MediaTypeFormatterCollection Formatters { get; }
 
+        /// <summary>The optional token used to cancel async operations.</summary>
+        CancellationToken CancellationToken { get; }
+
 
         /*********
         ** Methods
         *********/
+        /// <summary>Specify the token that can be used to cancel the async operation.</summary>
+        /// <param name="cancellationToken">The cancellation token.</param>
+        /// <returns>Returns the response builder for chaining.</returns>
+        IResponse WithCancellationToken(CancellationToken cancellationToken);
+
         /// <summary>Asynchronously retrieve the response body as a deserialized model.</summary>
         /// <typeparam name="T">The response model to deserialize into.</typeparam>
         /// <exception cref="ApiException">An error occurred processing the response.</exception>

Client/Internal/BodyBuilder.cs

@@ -89,11 +89,11 @@ public HttpContent FileUpload(IEnumerable<FileInfo> files)
         /// <inheritdoc />
         public HttpContent FileUpload(IEnumerable<KeyValuePair<string, Stream>> files)
         {
-            var content = new MultipartFormDataContent();
+            MultipartFormDataContent content = new();
 
             foreach (var file in files)
             {
-                StreamContent streamContent = new StreamContent(file.Value);
+                StreamContent streamContent = new(file.Value);
                 content.Add(streamContent, file.Key, file.Key);
             }
 

Client/Internal/Factory.cs

@@ -24,7 +24,7 @@ public static MediaTypeFormatter GetFormatter(MediaTypeFormatterCollection forma
             if (!formatters.Any())
                 throw new InvalidOperationException("No MediaTypeFormatters are available on the fluent client.");
 
-            MediaTypeFormatter formatter = contentType != null
+            MediaTypeFormatter? formatter = contentType != null
                 ? formatters.FirstOrDefault(f => f.SupportedMediaTypes.Any(m => m.MediaType == contentType.MediaType))
                 : formatters.FirstOrDefault();
             if (formatter == null)
@@ -39,7 +39,7 @@ public static MediaTypeFormatter GetFormatter(MediaTypeFormatterCollection forma
         /// <param name="formatters">The formatters used for serializing and deserializing message bodies.</param>
         public static HttpRequestMessage GetRequestMessage(HttpMethod method, Uri resource, MediaTypeFormatterCollection formatters)
         {
-            HttpRequestMessage request = new HttpRequestMessage(method, resource);
+            HttpRequestMessage request = new(method, resource);
 
             // add default headers
             request.Headers.Add("accept", formatters.SelectMany(p => p.SupportedMediaTypes).Select(p => p.MediaType));