simplified & documented error-handling.

Author: Pathoschild

Client/ApiException.cs

@@ -13,23 +13,27 @@ public class ApiException : Exception
 		/// <summary>The HTTP status of the response.</summary>
 		public HttpStatusCode Status { get; protected set; }
 
-		/// <summary>The HTTP response which caused the exception.</summary>
-		public HttpResponseMessage Response { get; protected set; }
+		/// <summary>The HTTP response which caused the exception. (This provides response body deserialization for further handling, but you should probably make sure <see cref="IResponse.RaiseErrors"/> is <c>false</c> before using it.)</summary>
+		public IResponse Response { get; protected set; }
+
+		/// <summary>The HTTP response message which caused the exception.</summary>
+		public HttpResponseMessage ResponseMessage { get; protected set; }
 
 
 		/*********
 		** Public methods
 		*********/
 		/// <summary>Construct an instance.</summary>
 		/// <param name="response">The HTTP response which caused the exception.</param>
-		/// <param name="status">The HTTP status of the response.</param>
+		/// <param name="responseMessage">The HTTP response message which caused the exception.</param>
 		/// <param name="message">The error message that explains the reason for the exception.</param>
 		/// <param name="innerException">The exception that is the cause of the current exception (or <c>null</c> for no inner exception).</param>
-		public ApiException(HttpResponseMessage response, HttpStatusCode status, string message, Exception innerException = null)
+		public ApiException(IResponse response, HttpResponseMessage responseMessage, string message, Exception innerException = null)
 			: base(message, innerException)
 		{
 			this.Response = response;
-			this.Status = status;
+			this.ResponseMessage = responseMessage;
+			this.Status = responseMessage.StatusCode;
 		}
 	}
 }

Client/Client.csproj

@@ -54,6 +54,7 @@
     <Compile Include="IClient.cs" />
     <Compile Include="IFactory.cs" />
     <Compile Include="IRequest.cs" />
+    <Compile Include="IResponse.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />
   </ItemGroup>
   <ItemGroup />

Client/Default/Request.cs

@@ -12,7 +12,7 @@
 
 namespace Pathoschild.Http.Client.Default
 {
-	/// <summary>Builds and dispatches an asynchronous HTTP request.</summary>
+	/// <summary>Builds and dispatches an asynchronous HTTP request, and asynchronously parses the response.</summary>
 	public class Request : IRequest
 	{
 		/*********
@@ -35,7 +35,7 @@ public class Request : IRequest
 		public MediaTypeFormatterCollection Formatters { get; set; }
 
 		/// <summary>Whether to handle errors from the upstream server by throwing an exception.</summary>
-		public bool ThrowError { get; set; }
+		public bool RaiseErrors { get; set; }
 
 
 		/*********
@@ -52,7 +52,7 @@ public Request(HttpRequestMessage message, MediaTypeFormatterCollection formatte
 			this.Formatters = formatters;
 			this.ResponseBuilder = dispatcher;
 			this.Factory = factory ?? new Factory();
-			this.ThrowError = true;
+			this.RaiseErrors = true;
 		}
 
 		/***
@@ -105,7 +105,7 @@ public virtual IRequest WithHeader(string key, string value)
 		/// <returns>Returns the request builder for chaining.</returns>
 		public virtual IRequest WithArgument(string key, object value)
 		{
-			return this.WithArguments(new Dictionary<string, object>(1) { {key, value} });
+			return this.WithArguments(new Dictionary<string, object>(1) { { key, value } });
 		}
 
 		/// <summary>Add HTTP query string arguments.</summary>
@@ -139,9 +139,9 @@ public virtual IRequest WithCustom(Action<HttpRequestMessage> request)
 		***/
 		/// <summary>Asynchronously retrieve the HTTP response.</summary>
 		/// <exception cref="ApiException">An error occurred processing the response.</exception>
-		public virtual Task<HttpResponseMessage> AsMessage()
+		public virtual async Task<HttpResponseMessage> AsMessage()
 		{
-			return this.ValidateResponse(this.ResponseBuilder(this));
+			return await this.ValidateResponse(this.ResponseBuilder(this)).ConfigureAwait(false);
 		}
 
 		/// <summary>Asynchronously retrieve the response body as a deserialized model.</summary>
@@ -194,7 +194,7 @@ public virtual async Task<Stream> AsStream()
 		** Synchronize
 		***/
 		/// <summary>Block the current thread until the asynchronous request completes. This method should only be called if you can't <c>await</c> instead, and may cause thread deadlocks in some circumstances (see https://github.com/Pathoschild/Pathoschild.FluentHttpClient#synchronous-use ).</summary>
-		/// <exception cref="AggregateException">The HTTP response returned a non-success <see cref="HttpStatusCode"/> and <see cref="ThrowError"/> is <c>true</c>.</exception>
+		/// <exception cref="AggregateException">The HTTP response returned a non-success <see cref="HttpStatusCode"/> and <see cref="RaiseErrors"/> is <c>true</c>.</exception>
 		public void Wait()
 		{
 			this.AsMessage().Wait();
@@ -205,7 +205,7 @@ public void Wait()
 		*********/
 		/// <summary>Validate the HTTP response and raise any errors in the response as exceptions.</summary>
 		/// <param name="request">The response message to validate.</param>
-		/// <exception cref="ApiException">The HTTP response returned a non-success <see cref="HttpStatusCode"/> and <see cref="ThrowError"/> is <c>true</c>.</exception>
+		/// <exception cref="ApiException">The HTTP response returned a non-success <see cref="HttpStatusCode"/> and <see cref="RaiseErrors"/> is <c>true</c>.</exception>
 		protected async Task<HttpResponseMessage> ValidateResponse(Task<HttpResponseMessage> request)
 		{
 			// fetch request
@@ -216,11 +216,11 @@ protected async Task<HttpResponseMessage> ValidateResponse(Task<HttpResponseMess
 
 		/// <summary>Validate the HTTP response and raise any errors in the response as exceptions.</summary>
 		/// <param name="message">The response message to validate.</param>
-		/// <exception cref="ApiException">The HTTP response returned a non-success <see cref="HttpStatusCode"/> and <see cref="ThrowError"/> is <c>true</c>.</exception>
+		/// <exception cref="ApiException">The HTTP response returned a non-success <see cref="HttpStatusCode"/> and <see cref="RaiseErrors"/> is <c>true</c>.</exception>
 		protected virtual void ValidateResponse(HttpResponseMessage message)
 		{
-			if (this.ThrowError && !message.IsSuccessStatusCode)
-				throw new ApiException(message, message.StatusCode, String.Format("The API query failed with status code {0}: {1}", message.StatusCode, message.ReasonPhrase));
+			if (this.RaiseErrors && !message.IsSuccessStatusCode)
+				throw new ApiException(this, message, String.Format("The API query failed with status code {0}: {1}", message.StatusCode, message.ReasonPhrase));
 		}
 
 		/// <summary>Get the key=>value pairs represented by a dictionary or anonymous object.</summary>

Client/Delegating/DelegatingRequest.cs

@@ -37,10 +37,10 @@ public virtual MediaTypeFormatterCollection Formatters
 		}
 
 		/// <summary>Whether to handle errors from the upstream server by throwing an exception.</summary>
-		public bool ThrowError
+		public bool RaiseErrors
 		{
-			get { return this.Implementation.ThrowError; }
-			set { this.Implementation.ThrowError = value; }
+			get { return this.Implementation.RaiseErrors; }
+			set { this.Implementation.RaiseErrors = value; }
 		}
 
 
@@ -174,7 +174,7 @@ public virtual Task<Stream> AsStream()
 		** Synchronize
 		***/
 		/// <summary>Block the current thread until the asynchronous request completes.</summary>
-		/// <exception cref="ApiException">The HTTP response returned a non-success <see cref="HttpStatusCode"/>, and <see cref="IRequest.ThrowError"/> is <c>true</c>.</exception>
+		/// <exception cref="ApiException">The HTTP response returned a non-success <see cref="HttpStatusCode"/>, and <see cref="IResponse.RaiseErrors"/> is <c>true</c>.</exception>
 		public void Wait()
 		{
 			this.Implementation.Wait();

Client/IRequest.cs

@@ -1,29 +1,20 @@
 using System;
-using System.Collections.Generic;
-using System.IO;
 using System.Net;
 using System.Net.Http;
 using System.Net.Http.Formatting;
 using System.Net.Http.Headers;
-using System.Threading.Tasks;
 
 namespace Pathoschild.Http.Client
 {
-	/// <summary>Builds and dispatches an asynchronous HTTP request.</summary>
-	public interface IRequest
+	/// <summary>Builds and dispatches an asynchronous HTTP request, and asynchronously parses the response.</summary>
+	public interface IRequest : IResponse
 	{
 		/*********
 		** Accessors
 		*********/
 		/// <summary>The underlying HTTP request message.</summary>
 		HttpRequestMessage Message { get; set; }
 
-		/// <summary>The formatters used for serializing and deserializing message bodies.</summary>
-		MediaTypeFormatterCollection Formatters { get; set; }
-
-		/// <summary>Whether to handle errors from the upstream server by throwing an exception.</summary>
-		bool ThrowError { get; set; }
-
 
 		/*********
 		** Methods
@@ -73,38 +64,6 @@ public interface IRequest
 		/// <returns>Returns the request builder for chaining.</returns>
 		IRequest WithCustom(Action<HttpRequestMessage> request);
 
-		/***
-		** Retrieve response
-		***/
-		/// <summary>Asynchronously retrieve the HTTP response.</summary>
-		/// <exception cref="ApiException">An error occurred processing the response.</exception>
-		Task<HttpResponseMessage> AsMessage();
-
-		/// <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>
-		Task<T> As<T>();
-
-		/// <summary>Asynchronously retrieve the response body as a list of deserialized models.</summary>
-		/// <typeparam name="T">The response model to deserialize into.</typeparam>
-		/// <exception cref="ApiException">An error occurred processing the response.</exception>
-		Task<List<T>> AsList<T>();
-
-		/// <summary>Asynchronously retrieve the response body as an array of <see cref="byte"/>.</summary>
-		/// <returns>Returns the response body, or <c>null</c> if the response has no body.</returns>
-		/// <exception cref="ApiException">An error occurred processing the response.</exception>
-		Task<byte[]> AsByteArray();
-
-		/// <summary>Asynchronously retrieve the response body as a <see cref="string"/>.</summary>
-		/// <returns>Returns the response body, or <c>null</c> if the response has no body.</returns>
-		/// <exception cref="ApiException">An error occurred processing the response.</exception>
-		Task<string> AsString();
-
-		/// <summary>Asynchronously retrieve the response body as a <see cref="Stream"/>.</summary>
-		/// <returns>Returns the response body, or <c>null</c> if the response has no body.</returns>
-		/// <exception cref="ApiException">An error occurred processing the response.</exception>
-		Task<Stream> AsStream();
-
 		/***
 		** Synchronize
 		***/

Client/IResponse.cs

@@ -0,0 +1,54 @@
+using System.Collections.Generic;
+using System.IO;
+using System.Net.Http;
+using System.Net.Http.Formatting;
+using System.Threading.Tasks;
+
+namespace Pathoschild.Http.Client
+{
+	/// <summary>Asynchronously parses an HTTP response.</summary>
+	public interface IResponse
+	{
+		/*********
+		** Accessors
+		*********/
+		/// <summary>The formatters used for serializing and deserializing message bodies.</summary>
+		MediaTypeFormatterCollection Formatters { get; set; }
+
+		/// <summary>Whether to handle errors from the upstream server by throwing an exception.</summary>
+		bool RaiseErrors { get; set; }
+
+
+		/*********
+		** Methods
+		*********/
+		/// <summary>Asynchronously retrieve the HTTP response.</summary>
+		/// <exception cref="ApiException">An error occurred processing the response.</exception>
+		Task<HttpResponseMessage> AsMessage();
+
+		/// <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>
+		Task<T> As<T>();
+
+		/// <summary>Asynchronously retrieve the response body as a list of deserialized models.</summary>
+		/// <typeparam name="T">The response model to deserialize into.</typeparam>
+		/// <exception cref="ApiException">An error occurred processing the response.</exception>
+		Task<List<T>> AsList<T>();
+
+		/// <summary>Asynchronously retrieve the response body as an array of <see cref="byte"/>.</summary>
+		/// <returns>Returns the response body, or <c>null</c> if the response has no body.</returns>
+		/// <exception cref="ApiException">An error occurred processing the response.</exception>
+		Task<byte[]> AsByteArray();
+
+		/// <summary>Asynchronously retrieve the response body as a <see cref="string"/>.</summary>
+		/// <returns>Returns the response body, or <c>null</c> if the response has no body.</returns>
+		/// <exception cref="ApiException">An error occurred processing the response.</exception>
+		Task<string> AsString();
+
+		/// <summary>Asynchronously retrieve the response body as a <see cref="Stream"/>.</summary>
+		/// <returns>Returns the response body, or <c>null</c> if the response has no body.</returns>
+		/// <exception cref="ApiException">An error occurred processing the response.</exception>
+		Task<Stream> AsStream();
+	}
+}

Client/package.nuspec

@@ -14,9 +14,10 @@
 			   - made all asynchronous methods async;
 			   - merged IRequestBuilder and IResponse into IRequest;
 			   - made IRequest awaitable;
-			   - eliminated the now-obsolete synchronous wrappers;
+			   - eliminated the now-obsolete synchronous wrappers.
 			* Added default User-Agent header and auto-generated Accept headers.
 			* Added support for anonymous object arguments: .WithArguments(new { id = 14, tenant = "example" }).
+			* Simplified error-handling with new exception properties.
 		</releaseNotes>
 		<frameworkAssemblies>
 			<frameworkAssembly assemblyName="System.Net.Http" />

README.md

@@ -1,4 +1,4 @@
-**Pathoschild.FluentHttpClient** is a strongly-typed easy-to-use asynchronous REST API client, built on top of the .NET 4.5 [HttpClient][]. The client provides a single fluent interface that lets you create an HTTP request, dispatch and wait for it, and process the response. (The client will automatically inject any required HTTP configuration, like `User-Agent` and `Accept` headers.)
+**Pathoschild.FluentHttpClient** is a strongly-typed easy-to-use asynchronous REST API client, built on top of the .NET 4.5 [HttpClient][]. The client provides a single fluent interface that lets you create an HTTP request, dispatch and wait for it, and process the response. The client will automatically inject any required HTTP configuration (like `User-Agent` and `Accept` headers) and handle the plumbing code.
 
 ## Usage
 You start by creating a client, and chain methods to configure your request and response:
@@ -50,7 +50,43 @@ You can even configure a range of features like credentials and cookies using th
 Not every feature is shown in these examples, but every method is fully code-documented for IntelliSense so it's easy to just use the client.
 
 ### Error handling
-By default HTTP errors will be raised as `ApiException` (or `AggregateException` if you explicitly call `.Result` or `.Wait()`), and you can add your own validation by overriding `IRequest.ValidateResponse`. For example, you could raise an exception if the API returns a non-HTTP error. (You can disable this by setting `IRequest.ThrowErrors = false`.)
+HTTP errors (such as HTTP Not Found) will be raised as `ApiException`, and you can add your own validation by overriding `Request.ValidateResponse`. For example, you could raise application errors from the API as client exceptions. (You can disable these exceptions by setting `IRequest.RaiseErrors = false`.)
+
+When an HTTP request fails, you can find out why by checking the exception object. This contains the `HttpResponseMessage` (which includes the HTTP details like the request message, HTTP status code, headers, and response body) and `IResponse` (which provides a convenient way to read the response body).
+
+For example:
+```c#
+     /// <summary>Get a value from the API.</summary>
+	 /// <param name="key">The value key.</param>
+	 /// <exception cref="KeyNotFoundException">The key could not be found.</exception>
+	 /// <exception cref="CustomApiExeption">The remote application returned an error message.</exception>
+     public async Task<string> GetValue(string key)
+     {
+        try
+        {
+           return await client
+              .Get("api/dictionary")
+              .WithArgument("key", key)
+              .AsString();
+        }
+        catch(ApiException exception)
+        {
+           // key not found
+           if(exception.ResponseMessage.StatusCode == HttpStatusCode.NotFound)
+              throw new KeyNotFoundException("The key could not be found.")
+           
+           // remote application error
+           if(exception.ResponseMessage.Content != null)
+           {
+              exception.Response.RaiseErrors = false; // disable validation so we can read response content
+              throw new CustomApiException(await exception.Response.AsString(), exception);
+           }
+           
+           // unhandled exception
+           throw;
+        }
+     }
+```
 
 ### Synchronous use
 The client is designed to take advantage of the `async` and `await` keywords in .NET 4.5, but you can use the client synchronously:
@@ -68,6 +104,8 @@ Or if you don't need the response:
      client.PostAsync("ideas", new Idea()).Wait();
 ```
 
+Note: `Result` and `Await()` will wrap any exceptions thrown by the client into an `AggregateException`.
+
 **Beware:** mixing blocking and asynchronous code within UI applications (like a web project) can lead to deadlocks. (If the only asynchronous code is the client itself, you should be fine doing this.) For further information, see _[Parallel Programming with .NET: Await, and UI, and deadlocks! Oh my!](http://blogs.msdn.com/b/pfxteam/archive/2011/01/13/10115163.aspx)_ (Stephen Toub, MSDN) and _[Don't Block on Async Code](http://nitoprograms.blogspot.ca/2012/07/dont-block-on-async-code.html)_ (Stephen Cleary).
 
 ## Installation