Added documentation for Web package

Author: jamesmcroft

docs/articles/available-packages.md

@@ -226,12 +226,12 @@ Taking advantage of the Data Validation library, you can simply and easily setup
 
 ## Web
 
-The Web library contains a collection of helpers and extensions that sit on top of ASP.NET Core, to provide useful components to compliment your web applications.
+The Web library contains a collection of helpers and extensions that sit on top of ASP.NET Core, to provide useful components to complement your web applications.
 
 This includes features such as:
 
 - PaginatedRequest, a simple request object that provides the expected return type, with properties for the current `Page`, the `PageSize`, and the number of items to `Skip` and `Take`.
-- PaginatedResponse, a complimentary response return type for the `PaginatedRequest`, with properties including the `Items` collection, the current `Page` and `PageSize`, plus the `AvailableCount` of requestable items, and the `TotalPages` based on the available count and page size requested.
+- PaginatedResponse, a complementary response return type for the `PaginatedRequest`, with properties including the `Items` collection, the current `Page` and `PageSize`, plus the `AvailableCount` of requestable items, and the `TotalPages` based on the available count and page size requested.
 - HttpContextExceptionsMiddleware, a middleware that manages the handling of exceptions thrown within a `HttpContext` to serve up meaningful exception details to the requesting client using exception handlers.
 
 <span class="button">
@@ -242,7 +242,7 @@ This includes features such as:
 
 ## Web.Mvc
 
-The Web MVC library is a complimentary extension package to ASP.NET Core MVC applications, providing additional helpers for building applications following the MVC pattern.
+The Web MVC library is a complementary extension package to ASP.NET Core MVC applications, providing additional helpers for building applications following the MVC pattern.
 
 Included in this package is:
 

docs/articles/features/collections.md

@@ -5,6 +5,8 @@ title: Using the Collections package | MADE.NET
 
 # Using the Collections package
 
+The Collections package is designed to provide helpful extensions and additional types for working with enumerable objects in your applications.
+
 ## Comparing objects using the GenericEqualityComparer
 
 The `MADE.Collections.Compare.GenericEqualityComparer` is a simple to use `IEqualityComparer` that takes a function as a parameter when constructed.

docs/articles/features/data-converters.md

@@ -5,6 +5,8 @@ title: Using the Data Converters package | MADE.NET
 
 # Using the Data Converters package
 
+The Data Converters package provides a collection of value converters and extensions to manipulate data in your applications.
+
 ## Converting a DateTime to a String using the DateTimeToStringValueConverter
 
 Value converters are a common coding practice for building XAML applications that allow values to be bound to a view, converted to a different type and back depending on the binding mode.

docs/articles/features/data-validation.md

@@ -5,6 +5,8 @@ title: Using the Data Validation package | MADE.NET
 
 # Using the Data Validation package
 
+The Data Validation package is designed to provide out-of-the-box data validation to applications built with C#. 
+
 ## Validating an object using the ValidatorCollection
 
 Data validation can be implemented in so many different ways. MADE provides the capability to perform data validation through it's own `IValidator` interface which can be used to create consistent data validators.

docs/articles/features/diagnostics.md

@@ -5,6 +5,8 @@ title: Using the Diagnostics package | MADE.NET
 
 # Using the Diagnostics package
 
+The Diagnostic package contains a set of simple application logging mechanisms for applications.
+
 ## Logging events to files on disk with FileEventLogger
 
 Using the `MADE.Diagnostics.Logging.FileEventLogger`, you can quickly and easily get up and running with event logging for your application's diagnostic needs.

docs/articles/features/media-image.md

@@ -5,6 +5,8 @@ title: Using the Media Image package | MADE.NET
 
 # Using the Media Image package
 
+The Media Image package is designed to be used in applications that require image processing.
+
 ## Loading Windows StorageFile thumbnails into an Image with LoadStorageFileThumbnailImageBehavior
 
 The `MADE.Media.Image.Behaviors.LoadStorageFileThumbnailImageBehavior` is a custom behavior built on the [Microsoft XAML behaviors SDK](https://github.com/Microsoft/XamlBehaviors). 

docs/articles/features/networking.md

@@ -5,6 +5,8 @@ title: Using the Networking package | MADE.NET
 
 # Using the Networking package
 
+The Networking package contains a collection of helpers for applications that use `HttpClient` for making network requests to APIs.
+
 ## Making simple network requests using NetworkRequest instances
 
 The Network package comes with a variety of `NetworkRequest` types that can be used to perform network requests without a lot of additional overhead.

docs/articles/features/runtime.md

@@ -5,6 +5,8 @@ title: Using the Runtime package | MADE.NET
 
 # Using the Runtime package
 
+The Runtime package provides additional types for .NET to provide extensibility over existing `System` types.
+
 ## Improving callback memory management with WeakReferenceCallback
 
 The `MADE.Runtime.WeakReferenceCallback` is a wrapper type for a `WeakReference`. It is capable of taking a delegate action and ensuring that it is available to be garbage collected if the referring object is disposed. 

docs/articles/features/threading.md

@@ -5,6 +5,8 @@ title: Using the Threading package | MADE.NET
 
 # Using the Threading package
 
+The Threading package contains a collection of `System.Threading` extensions and helpers to improve the developer experience.
+
 ## Modernizing System.Threading.Timer with the MADE.Threading.Timer
 
 Setting up and managing a `System.Threading.Timer` can sometimes be cumbersome. How do you control the start and stop state? 

docs/articles/features/web.md

@@ -5,3 +5,71 @@ title: Using the Web package | MADE.NET
 
 # Using the Web package
 
+The Web library contains a collection of helpers and extensions that sit on top of ASP.NET Core, to provide useful components to complement your web applications.
+
+## Improved HttpContext exception handling with HttpContextExceptionsMiddleware
+
+The Web package contains a `MADE.Web.Exceptions.HttpContextExceptionsMiddleware` which can be used with your ASP.NET Core application to manage how exceptions are handled and errors are returned using JSON responses.
+
+Using the `UseHttpContextExceptionHandling` extension method on your `IApplicationBuilder` instance in the `Startup` of your web application, you can start taking advantage of improved error handling with MADE.
+
+Under the hood, exceptions are handled using `IHttpContextExceptionHandler` types which are registered with your application's `IServiceCollection`.
+
+The implementation has a basic catch-all `Exception` handler which returns an internal server error (500) when an unhandled exception is thrown. This can be registered alongside your own exception handlers in your `Startup` class.
+
+### Registering the HttpContextExceptionsMiddleware and handlers
+
+Below is an example of configuring the exception handling middleware and exception handlers in your application's `Startup` class.
+
+```csharp
+// Startup.cs
+
+public void Configure( IApplicationBuilder app )
+{
+    // Registers the middleware for exception handling
+    app.
+    UseHttpContextExceptionHandling();
+}
+
+public void ConfigureServices( IServiceCollection services )
+{
+    // Registers the default exception handler.
+    services.AddHttpContextExceptionHandler<Exception, DefaultExceptionHandler>
+
+    services.AddHttpContextExceptionHandler<MyCustomException, MyCustomExceptionHandler>
+}
+```
+
+And this is an example of a custom exception handler.
+
+```csharp
+namespace MyApp.Exceptions
+{
+    using System;
+    using System.Net;
+    using System.Threading.Tasks;
+    using MADE.Web.Exceptions;
+    using MADE.Web.Extensions;
+    using Microsoft.AspNetCore.Http;
+
+    public class MyCustomExceptionHandler : IHttpContextExceptionHandler<MyCustomException>
+    {
+        public async Task HandleAsync(HttpContext context, MyCustomException exception)
+        {
+            var response = new ExceptionResponse<MyCustomException>("MyCustomExceptionError", "An error occurred causing my custom exception to be thrown.", exception);
+
+            await context.Response.WriteJsonAsync(HttpStatusCode.InternalServerError, response);
+        }
+    }
+}
+```
+
+## Improving pagination support with PaginatedRequest and PaginatedResponse
+
+Pagination is a common concept for web requests to help improve performance of UIs and reduce network traffic by querying a subset of data.
+
+The `PaginatedRequest` and `PaginatedResponse` can be used together to help you achieve these performance improvements in your own web applications.
+
+The `PaginatedRequest` takes a page and page size parameter when constructed, and it automatically provides you with the `Skip` and `Take` properties that you can provide to your data queries.
+
+When you have your data from your request, you can construct a response using the `PaginatedResponse` which takes the data, the original page and page size parameters, and the number of available items. It will also provide the `TotalPages` that are available to allow a UI to generate a pagination user experience.