Plinth.AzureFunction 1.5.9-b172.dfc6e7bd

README

Plinth.AzureFunction

Utility framework and enhancements for Azure Function projects

Adds enhancements and facilities for Azure Function projects with HTTP triggers including logging using the Plinth framework and Application Insights integration. This parallels the Plinth.AspNetCore package.

Function Setup

1. Logging Settings

• In host.json or a custom loaded funcsettings.json, this configuration must be supplied.
  👉 It is important to set the default level for both the LogLevel and the ApplicationInsights blocks. 👉 Log levels set for application insights are the most important. The top level LogLevel block only controls local console logging

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Debug",
        "Microsoft": "Warning",
        "System": "Warning"
      }
    }
  }
}

2. Loading custom config

In Program.cs, if you choose to load a custom funcsettings.json, here is an example of doing that. This should be done first before any other host configuration.

var host = new HostBuilder()
    .ConfigureAppConfiguration((hostingContext, config) =>
    {
        var context = hostingContext.HostingEnvironment;
        config
            .AddJsonFile(Path.Combine(context.ContentRootPath, "funcsettings.json"), optional: false, reloadOnChange: false)
            .AddJsonFile(Path.Combine(context.ContentRootPath, $"funcsettings.{context.EnvironmentName}.json"), optional: true, reloadOnChange: false)
            .AddEnvironmentVariables();
    })

3. Enable Plinth service logging

Next, this enables middleware to provide service logging and exception handling for http triggered functions

    .ConfigureFunctionsWorkerDefaults((config, builder) =>
    {
        builder.UsePlinthServiceLogging();
    })

You may pass an Action to this call to configure some logging parameters

• MaxRequestBody - maximum amount of the request body to be logged (default 25000)
• MaxResponseBody - maximum amount of the response body to be logged (default 25000)
• RequestProcessors - a mapping of api prefixes to callbacks for processing the request body to be logged before it is logged, for sanitation or filtering.
• ResponseProcessors - a mapping of api prefixes to callbacks for processing the response body to be logged before it is logged, for sanitation or filtering.

4. Enabling Application Insights

Next, this enables application insights integration with the function runtime and configures ILogger to send traces

    .ConfigureServices((hostingContext, services) =>
    {
        services.AddPlinthAppInsightsTelemetry(hostingContext.Configuration);
    })

👉 The connection string for Application Insights will be retrieved from the configuration variable "APPLICATIONINSIGHTS_CONNECTION_STRING"

👉 The Cloud Role Name for Application Insights will be retrieved from the configuration variable "WEBSITE_CLOUD_ROLENAME"

When running locally, these can be set in local.settings.json. They should be supplied in the Azure Portal when running on Azure.

5. ILogger configuration

Next, this ensures that your settings from host.json or a custom loaded funcsettings.json are applied to ILogger

    .ConfigureLogging((hostingContext, logging) =>
    {
        logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
    })

6. Attaching Plinth static loggers to Application Insights

Once your IHost is built, in order to include all logging done by Plinth components (such as Plinth.HttpApiClient), you must add Plinth logging to the host. This can be done by calling .AddPlinthLogging() before running the host.

    await host
        .AddPlinthLogging()
        .RunAsync();

Complete Setup Example

    var host = new HostBuilder()
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            var context = hostingContext.HostingEnvironment;
            config
                .AddJsonFile(Path.Combine(context.ContentRootPath, "funcsettings.json"), optional: false, reloadOnChange: false)
                .AddJsonFile(Path.Combine(context.ContentRootPath, $"funcsettings.{context.EnvironmentName}.json"), optional: true, reloadOnChange: false)
                .AddEnvironmentVariables();
        })
        .ConfigureFunctionsWorkerDefaults((config, builder) =>
        {
            builder.UsePlinthServiceLogging();
        })
        .ConfigureServices((hostingContext, services) =>
        {
            services.AddPlinthAppInsightsTelemetry(hostingContext.Configuration);
        })
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
        })
        .Build();

    await host
        .AddPlinthLogging()
        .RunAsync();

Function Example

[Function("MyFunction")]
public async Task<ActionResult> MyFunction([HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequest req)
{
    var data = await SomeDataThing.GetDataAsync();
    return new OkObjectResult(data);
}