Kanject.Core.CloudFunction.Provider.AwsLambda 3.8.0

Kanject.Core.CloudFunction.Provider.AwsLambda

The AWS Lambda host for Kanject services. Derive your Lambda class from CloudFunction. Once per execution environment, it builds a Microsoft.Extensions.Hosting container that holds:

• configuration from appsettings*.json and environment variables;
• console logging, which Lambda forwards to CloudWatch;
• the services you register in ConfigureServices.

Your handler methods then resolve services from a ready ServiceProvider. Pair the package with the Kanject.Core.CloudFunction.Aws.Annotations source generator and the host class shrinks to a single ConfigureServices method.

Installation

dotnet add package Kanject.Core.CloudFunction.Provider.AwsLambda
dotnet add package Amazon.Lambda.Serialization.SystemTextJson

Recommended setup, with the source generator:

<ItemGroup>
  <PackageReference Include="Kanject.Core.CloudFunction.Provider.AwsLambda" />
  <PackageReference Include="Kanject.Core.CloudFunction.Aws.Annotations" PrivateAssets="all" />
  <PackageReference Include="Amazon.Lambda.Serialization.SystemTextJson" />
</ItemGroup>

Targets .NET 8, .NET 9 and .NET 10. Native AOT / trimming compatible (see Native AOT). The package brings in Kanject.Core.CloudFunction.Abstractions, Amazon.Lambda.Core and Amazon.Lambda.SNSEvents. It also depends on the generator package. Reference that package yourself, as shown above, so the generator version is explicit.

Quick start

A Lambda project usually splits the host class into two partial files: one that configures it and one that holds the handlers.

// Functions.Configuration.cs
using Kanject.Core.CloudFunction.Abstractions.Attributes;
using Kanject.Core.CloudFunction.Abstractions.Enums;
using Microsoft.Extensions.DependencyInjection;

namespace Orders.Lambda;

public sealed class AppSettings
{
    public string TableName { get; set; } = string.Empty;
}

[CloudFunctionHost(DebugEnvironment = CloudFunctionEnvironment.Development)]
[RequireConfigSection<AppSettings>("AppSettings")]
public partial class Functions
{
    public override void ConfigureServices(IServiceCollection services)
    {
        services.AddSingleton(AppSettings);   // generated, bound and validated at cold start
        services.AddScoped<OrderService>();
    }
}

// Functions.cs
using Amazon.Lambda.Core;
using Microsoft.Extensions.DependencyInjection;

namespace Orders.Lambda;

public partial class Functions
{
    public async Task<OrderReceipt> PlaceOrderAsync(PlaceOrderRequest request, ILambdaContext context)
    {
        using var scope = ServiceScope;
        var orders = scope.ServiceProvider.GetRequiredService<OrderService>();

        return await orders.PlaceAsync(request);
    }
}

OrderService, PlaceOrderRequest and OrderReceipt are your own types. The generator supplies the base class, constructor, OnStartup and [assembly: LambdaSerializer(...)]; the Kanject.Core.CloudFunction.Aws.Annotations package shows the exact output.

Configuration comes from appsettings.json next to the deployed assembly:

{
  "AppSettings": { "TableName": "orders" }
}

Make sure the settings files are included in the publish output:

<ItemGroup>
  <None Update="appsettings*.json" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>

Point the Lambda function's handler at the method, using the class-library form Assembly::Namespace.Type::Method, for example Orders.Lambda::Orders.Lambda.Functions::PlaceOrderAsync. To choose appsettings.{Environment}.json, set ASPNETCORE_LAMBDA_ENVIRONMENT (or ASPNETCORE_ENVIRONMENT) on the function.

How the host starts

When Lambda constructs your Functions instance, the base constructor calls Build(). The host lives in a static field and is built once per process under a lock, so later instances and warm invocations reuse the same container. The build runs these steps in order:

1. Environment. The environment name comes from ASPNETCORE_LAMBDA_ENVIRONMENT, then ASPNETCORE_ENVIRONMENT; surrounding quotes are trimmed. If you pass a CloudFunctionEnvironment to the base constructor, its member name (for example Staging) overrides both.
2. Configuration. The host loads appsettings.json, appsettings.{Environment}.json and environment variables (all optional, read from the current directory), then calls OnStartup(configurationBuilder) so you can add sources.
3. Logging. It clears the default providers, adds the console provider, then calls ConfigureLogging(ILoggingBuilder).
4. Services. It calls AddOptions(), then RegisterFrameworkServices(services), then your ConfigureServices(services). In the Development environment, the container validates scopes and registrations as it is built.
5. Start. The host is started, so every IHostedService and BackgroundService you or a framework service registered runs its StartAsync — for example the PrintInConsole logging that [CloudFunctionHost(EnablePrintInConsoleLogging = true)] wires. The constructor waits until they have all started.
6. Post-build. Configure(IServiceProvider) runs once per process, after the host has started. Override it for cold-start warm-up; by default it does nothing.

Every instance, including ones constructed after the first, gets the same ServiceProvider and Configuration. Kanject's SQS queue consumers are hosted services too, but they only poll when their queue sets WatchQueue = true, so starting the host in Lambda doesn't make them compete with the event source mapping. Any other hosted service you register does run, for as long as the execution environment is active.

Members available to your class:

Hand-written host

You don't need the generator. Derive from CloudFunction and implement its two abstract members yourself:

using Amazon.Lambda.Core;
using Kanject.Core.CloudFunction.Abstractions.Enums;
using Kanject.Core.CloudFunction.Provider.AwsLambda;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

namespace Orders.Lambda;

public partial class Functions : CloudFunction
{
#if DEBUG
    public Functions() : base(CloudFunctionEnvironment.Development) { }
#else
    public Functions() : base() { }
#endif

    public override void OnStartup(IConfigurationBuilder configurationBuilder) { }

    public override void ConfigureServices(IServiceCollection services)
    {
        var settings = Configuration.GetSection("AppSettings").Get<AppSettings>()
                       ?? throw new InvalidOperationException("'AppSettings' is required.");

        services.AddSingleton(settings);
        services.AddScoped<OrderService>();
    }
}

OnStartup and ConfigureServices are abstract. Configure, ConfigureLogging and RegisterFrameworkServices are virtual no-ops that you can override. If the generator package is installed, its KANCF100 suggestion offers to convert a host of this shape to [CloudFunctionHost].

SQS-triggered functions

Kanject.Core.Queue.Provider.AwsSqs doesn't depend on this package. The two connect through IServiceProvider:

1. Register your queue consumers in ConfigureServices, as that package describes.
2. Dispatch each SQSEvent from a handler through the host's ServiceProvider.

using Amazon.Lambda.SQSEvents;
using Kanject.Core.Queue.Provider.AwsSqs.Abstractions.Extensions;
using Kanject.Core.Queue.Provider.AwsSqs.Extensions;

namespace Orders.Lambda;

public partial class Functions
{
    // One queue, one consumer.
    public Task<SQSBatchResponse> OrderPlacedAsync(SQSEvent sqsEvent)
        => ServiceProvider.ProcessSqsEventWithQueueConsumerAsync<OrderPlacedConsumer>(sqsEvent);

    // One queue carrying several message types, fanned out to route consumers.
    public Task<SQSBatchResponse> OrderEventsAsync(SQSEvent sqsEvent)
        => ServiceProvider.RouteIncomingSqsQueueEventAsync(sqsEvent, queue: "order-events");
}

OrderPlacedConsumer is a queue consumer declared with Kanject.Core.Queue.Provider.AwsSqs. Both calls return an SQSBatchResponse that lists the failed messages. Enable ReportBatchItemFailures on the event source mapping so that SQS retries only those messages.

Native AOT

The package is annotated for trimming and Native AOT. For an AOT-published function, derive from Kanject.Core.CloudFunction.Provider.AwsLambda.Aot.CloudFunction, or set [CloudFunctionHost(EnableAot = true)] when you use the generator. The AOT variant has the same members and lifecycle (it starts the host and calls Configure once per process), but builds on HostApplicationBuilder and resolves environment names without reflection. Every CloudFunctionEnvironment member maps to its own name.

Your own registrations and your Lambda serializer must also be AOT-safe. SnsTopicHelper.GetEventTopicPayload<TEventArgs> uses reflection-based System.Text.Json and is marked [RequiresUnreferencedCode] / [RequiresDynamicCode].

Health checks

CloudFunction implements ICloudFunctionHealthCheck<CloudFunction>, so you can register checks once and run them from a handler:

namespace Orders.Lambda;

public partial class Functions
{
    public override void Configure(IServiceProvider serviceProvider)
    {
        AddHealthCheckEndpoint("orders-api", "https://orders.example.com/health");
    }

    public void HealthCheck() => PerformHealthCheck();
}

An endpoint check sends an HTTP GET and logs whether it succeeded. Endpoints that require a token get a bearer header from the delegate you pass, or from AddHealthCheckEndpointAccessTokenFunc; the token is fetched before the request is sent. AddHealthCheckFunction<T> registers a named delegate; the check awaits its task and reports a failure when the delegate throws or its task faults. The checks run concurrently. PerformHealthCheck() returns once all of them have finished, blocking the calling thread; await PerformHealthCheckAsync(cancellationToken) is the non-blocking form. Results go to the console log and are not returned, and a failing check never throws.

Public surface at a glance

Namespaces: Kanject.Core.CloudFunction.Provider.AwsLambda (and .Aot, .Extensions, .Helpers).

Related packages

License

Licensed under the Kanject Code Libraries License Agreement (KCLLA); the full text ships in this package as LICENSE.md. Organizations whose trailing-twelve-month gross revenue and total funding raised are each below US$250,000 may use it at no cost under the Free Tier. At or above either threshold a commercial license is required — contact commercial@kanjectbusiness.com.