Overview

Overview

The purpose of this library is to extend the features provided by HTTP triggered Azure Functions. The HttpTrigger provided by the Azure Functions SDK is a rather simple interface, designed as the name implies to provide a Function triggering method via HTTP requests. However due to the "pay for what you run" nature of Consumption Plan based Functions the idea of using the Functions as a fully fledged Web API is tempting. Unfortunately the feature set you get out of the box from the SDK, namely the HttpTrigger, doesn't provide you with much of a WebAPI-like toolset to work with. The HttpExtensions project was a direct consequence of this, created with the idea of filling this gap in functionality.

Also, Swagger compatible! See NSwag.AzureFunctionsV2 for more information.

Features

The library addresses these issues by trying to provide a ASP.NET controller-like behaviour, namely:

• Enables you to define Function signatures similar to ASP.NET Controller conventions
• Automatically deserializes objects, lists and arrays, supporting JSON and XML content out of the box
• Provides basic input validation via JSON deserializer
• Provides JWT, Basic, ApiKey and OAuth2 authentication/authorization via attributes, which is also customizable
• Allows custom implementation of JWT authorization
• Provides an exception filter, allowing more control over responses
• Allows overriding default deserialization methods and exception handling with custom behaviour

In essence, the aim is to bring you a more ASP.NET like development experience and to reduce the boiler plate code you need to write inside your Functions.

Important considerations

The decision to not fully imitate ASP.NET was consciously made because of all the difficulties or even impossibilities concerning the idea. Hence why none of the ASP.NET attributes were used. Different naming was deliberately used for the attributes to not accidentally mix/confuse them with the ASP.NET attributes (eg. HttpQuery vs FromQuery).

While we do want a quite ASP.NET like workflow, assumptions should not be made that things work the same way when using the HttpExtensions as they would with ASP.NET.

Getting started

Install the Nuget package from Visual Studio or via the package manager:

PM> Install-Package AzureFunctionsV2.HttpExtensions

Additionally if you want to enable the Exception Filter (optional component), you'll need to install the Fody Nuget package:

PM> Install-Package Fody

...and also you'll need to make sure the Fody addin AzureFunctionsV2.HttpExtensions gets loaded by adding FodyWeavers.xml to your project root with the following content:

<?xml version="1.0" encoding="utf-8" ?>
<Weavers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="FodyWeavers.xsd">
  <AzureFunctionsV2.HttpExtensions />
</Weavers>

Finally if you're using authentication you'll need to configure your auth settings - you can read about this in the Authentication and authorization page.

Caveats

Due to technical constraints the usage of the generic HttpParam value holder class is an unfortunate necessity;

[FunctionName("QueryParametersDemo1")]
        public static async Task<IActionResult> QueryParametersDemo1(
            [HttpTrigger(AuthorizationLevel.Function, "get", Route = "query-basics")] HttpRequest req,
            [HttpQuery(Required = true)]HttpParam<string> someString,
            [HttpQuery(Name = "anotherString")]HttpParam<string> yetAnother,
            [HttpQuery]HttpParam<BodyParameters.MyObject> myObject,
            [HttpQuery]HttpParam<long[]> numberArray,
            [HttpQuery]HttpParam<List<string>> stringList,
            ILogger log)

All HTTP request parameters that are present (with the exception of route params) in the Function signature must be of the type HttpParam due to the inability to access the HttpRequest during parameter binding. Hence we are forced to delay the actual parameter value assignment to post-bind time using the FunctionFilter, and at this point we are able to access both the HttpRequest and all other arguments - but since the parameter binding has already been performed we're unable to actually change the actual parameters, unless of course they're instances of value holders (HttpParam) in which case we can then assign to the value within them.