Design Doc: Lambda Annotation

[normj]

The AWS .NET team is working on a new library for constructing .NET Lambda functions. The design doc can be viewed and commented on in this PR https://github.com/aws/aws-lambda-dotnet/pull/961.

The high level overview of the new library is to use .NET source generator support to translating from the low level single event object programming model of Lambda to an experience similar to ASP.NET Core but with minimal overhead. The initial work is focused on REST API Lambda functions but the technology is applicable for other Lambda event types.

For example developers will be able to write a Lambda function like the following with the ICalculator service being injected by dependency injection and and the LambdaFunction and HttpApi attributes directing the source generator to generator the compatible Lambda boiler plate code and sync with the CloudFormation template.

public class Functions
{
    ICalculator _calulator;

    public Functions(ICalculator calculator)
    {
        _calulator = calculator;
    }

    [LambdaFunction]
    [HttpApi(HttpMethod.Get, HttpApiVersion.V2, "/add/{x}/{y}")]
    public int Add(int x, int y)
    {
        return _calulator.Add(x, y);
    }
}

We would appreciate feedback on the design. What use cases what you like this library to help solve and what boiler plate code can we remove from your applications to make it simple to write Lambda functions.

---

Update 12/21/2021

We are excited to announce that Lambda Annotations first preview is here. Developers using the preview version of Amazon.Lambda.Annotations NuGet package can start using the simplified programming model to write REST and HTTP API Lambda functions on .NET 6. (Only Image package type is supported as of now)

Example (sample project)

[LambdaFunction(Name = "CalculatorAdd", PackageType = LambdaPackageType.Image)]
[RestApi(HttpMethod.Get, "/Calculator/Add/{x}/{y}")]
public int Add(int x, int y, [FromServices]ICalculatorService calculatorService)
{
    return calculatorService.Add(x, y);
}

[LambdaStartup]
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddScoped<ICalculatorService, CalculatorService>();
    }
}

Learn more about the Lambda Annotations and supported feature set here.

We cannot overstate how critical your feedback is as we move forward in the development. Let us know your experience working with Lambda Annotations in GitHub issues.

[CalvinAllen]

Dependency Injection is a huge plus, to me. I've had to roll that myself to support it - same with logging and configuration / environmental configuration.

EDIT: Why confused, @normj ?

[Lanayx]

Source generators is not dotnet, but csharp technology, so will be applicable only to csharp, with fsharp it won't be usable.

[mtschneiders]

Would it also generate the code needed for manual invocation via Lambda Test Tool?

 public static async Task Main()
  {
      var func = new Startup().FunctionHandler;
      using var handlerWrapper = HandlerWrapper.GetHandlerWrapper(func, new DefaultLambdaJsonSerializer());
      using var bootstrap = new LambdaBootstrap(handlerWrapper);
      await bootstrap.RunAsync();
  }

[normj]

Dependency Injection is a huge plus, to me. I've had to roll that myself to support it - same with logging and configuration / environmental configuration.

EDIT: Why confused, @normj ?

@CalvinAllen Sorry clicked the wrong emoji

[CalvinAllen]

@normj Ha, okay. I was a little confused myself, trying to figure out what I said, lol.

[Kralizek]

It would be great to see more of the plumbing, which happened to be the weakest point of Lambda development.

As @CalvinAllen wrote, logging, configuration and service registration are all concerns that required some time to work in a vanilla function.

But I generally love the idea of seeing multi-function packages becoming first class citizen of the new toolkit.

[petarrepac]

why is this being introduced ? what problems it solves ? what are expected benefits over the current approach? what are the downsides ?

[normj]

why is this being introduced ? what problems it solves ? what are expected benefits over the current approach? what are the downsides ?

@petarrepac Are you saying these questions are not answered in the design doc?

[Dreamescaper]

It would be great to design DI container setup in such a way so it would be possible to replace some dependencies for testing after initial container setup. I mean not unit tests, but more like functional tests, similar to ASP.NET Core's WebApplicationFactory. https://docs.microsoft.com/en-us/aspnet/core/test/integration-tests?view=aspnetcore-6.0

[Dreamescaper]

Would it be possible to customize parsing the request somehow? For example, if I have not a JSON body, but application/x-www-form-urlencoded ?

Another question - would it be possible to add [From...] attributes not on method parameters, but on type properties? So I'd be able to have single MyEndpointRequest parameter, and add [FromQuery], [FromHeader], etc on corresponding properties in MyEndpointRequest type?

[petarrepac]

why is this being introduced ? what problems it solves ? what are expected benefits over the current approach? what are the downsides ?

@petarrepac Are you saying these questions are not answered in the design doc?

took a look at one of our latest projects. Found this:

public async Task FunctionHandlerAsync(Stream stream, ILambdaContext context)

and also this

namespace MyProject.Api.Http
{
    public class LambdaEntryPoint : ApplicationLoadBalancerFunction
    {
        protected override void Init(IWebHostBuilder builder)
        {
            builder.ConfigureLogging((hostingContext, logging) =>
                {
                    logging.SetMinimumLevel(LogLevel.Warning);
                })
                .UseStartup<Startup>();
        }
    }
}

This are the entry points to 2 different lambdas. The 2nd one being a full REST API with many endpoints.

The nice thing is that only this code is "lambda specific". Everything else is the same code as you would have when running as a standalone app. So, you can run it locally, run integration tests, and so on.

The new approach seems more opinionated (for example CloudFormation and ApiGateway are mentioned, we use CDK and ALB instead). So, in REST API case what is the benefit? The amount of code is already very small. Is it faster with cold starts? Will the current way still work or it will be left behind going forward?

[ganeshnj]

Would it be possible to customize parsing the request somehow? For example, if I have not a JSON body, but application/x-www-form-urlencoded ?

Another question - would it be possible to add [From...] attributes not on method parameters, but on type properties? So I'd be able to have single MyEndpointRequest parameter, and add [FromQuery], [FromHeader], etc on corresponding properties in MyEndpointRequest type?

That's a cool idea, thanks for the feedback.

[normj]

@petarrepac The approach of running ASP.NET Core application's as Lambda functions will still be fully supported. I even did some work to support ASP.NET Core .NET 6 minimal style although that will be more useful once we get the .NET 6 managed runtime out. The ASP.NET Core approach does make development more familiar and keeps your code abstracted from Lambda.

The con of using that approach is there is a slower cold start due to initializing ASP.NET Core and you kind of miss out some of the API Gateway features because you are relying on ASP.NET Core to do the work. That isn't an issue for you because you are using ALB. We also want this new library to support more than just REST API scenarios even through that is our initial focus.

So if you are happy with ASP.NET Core approach keeping doing and we will continue to support you with it. This library is for developers that want something lighter and covers more scenarios than REST API.

[petarrepac]

Thanks. I'm more clear on this development now.

[BoundedChenn31]

Would it be possible to provide a fallback to reflection to make this API available for any .NET language? As described in design doc performance isn't the only goal. Experience of writing Lambda functions would still be improved though at cost of worse cold start.

[normj]

@Lanayx You are right. We are using a C# specific technology. I'll update the doc to reflect that. I have wondered if F# type providers could provide a similar experience.

@BoundedChenn31 I'm not sure how reflection would help. The Lambda programming model isn't changing. Lambda is still executing a parameterless constructor, it an instance method, and then invoking the method that takes in the event object. If we don't have the source generator to generate the translation layer from the Lambda programming model to this libraries programming model at compile time then both the Lambda programming model and the this library programming model have to be coded. Also at compile time is the syncing with CloudFormation that couldn't be done at runtime with reflection. Is F# your main concern when it comes to other .NET languages?

[BoundedChenn31]

@normj Ah, sorry, I overlooked these implementation details. In this case reflection doesn't really make sense. And yes, I'm mostly worried about F#. Well, in worst scenario F#-community can come up with alternative implementation using it's own source generation tool — Myriad 😊

[RichiCoder1]

Would it also generate the code needed for manual invocation via Lambda Test Tool?

 public static async Task Main()
  {
      var func = new Startup().FunctionHandler;
      using var handlerWrapper = HandlerWrapper.GetHandlerWrapper(func, new DefaultLambdaJsonSerializer());
      using var bootstrap = new LambdaBootstrap(handlerWrapper);
      await bootstrap.RunAsync();
  }

Was this question answered? I'm extremely bullish on this, but would want to make sure there's still some way to locally invoke and/or E2E test functions.

Edit: on the note of minimal apis, is there a world where you can do something like the below? Pardon if should be a separate discussion or thread.

var lambda = AwsLambdaBuilder.Create(args);

lambda.HandleApiGatewayV2(async (event) => {
  // do function stuff
 return obj;
});

lambda.Run();

Would be a neat way to have sorta parity with JavaScript while not having to opt too deeply into the CDK.

[DerekBeattieCG]

This is interesting, I thought about doing something similar, generating pulumi C# apigateway code based on attributes on a function.

[normj]

@RichiCoder1 The CloudFormation template will still have the correct function handler value for the source generated method. So SAM and the .NET Lambda Test Tool would work just as they do today.

[ganeshnj]

We are excited to announce that Lambda Annotations first preview is here. Developers using the preview version of Amazon.Lambda.Annotations NuGet package can start using the simplified programming model to write REST and HTTP API Lambda functions on .NET 6. (Only Image package type is supported as of now)

Example (sample project)

[LambdaFunction(Name = "CalculatorAdd", PackageType = LambdaPackageType.Image)]
[RestApi(HttpMethod.Get, "/Calculator/Add/{x}/{y}")]
public int Add(int x, int y, [FromServices]ICalculatorService calculatorService)
{
    return calculatorService.Add(x, y);
}

[LambdaStartup]
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddScoped<ICalculatorService, CalculatorService>();
    }
}

Learn more about the Lambda Annotations and supported feature set here.

We cannot overstate how critical your feedback is as we move forward in the development. Let us know your experience working with Lambda Annotations in GitHub issues.

[genifycom]

For many of our current workloads, we run the same code locally and in Lambda. Our clients can then run either on an on-premise machine or in the cloud (e.g. via a tablet).

Is this going to run in both environments or Lambda only?

Thanks

[ganeshnj]

It depends on the how you are calling the target method in your local environment.

For example an attributed Lambda Function

[LambdaFunction(Name = "SimpleCalculatorAdd", PackageType = LambdaPackageType.Image)]
[RestApi(HttpMethod.Get, "/SimpleCalculator/Add")]
public int Add([FromQuery]int x, [FromQuery]int y)
{
    return _simpleCalculatorService.Add(x, y);
}

The generated code is https://github.com/aws/aws-lambda-dotnet/blob/master/Libraries/test/Amazon.Lambda.Annotations.SourceGenerators.Tests/Snapshots/SimpleCalculator_Add_Generated.g.cs

In short, you can write tests, local debug using Lambda Test Tool or instantiate (your class or generated class) & call the target method.

In short, yes assuming your local environment have ability to instantiate and call.

[Kralizek]

Will there be a way to customize the Configuration section like it seems to be possible to customize the services?

[lukeemery]

@ganeshnj I see you've been working on the lambda annotations to build the serverless.template. Trying to figure out where we'd be able to inject environment variables for which stage it is in (i.e. prod, staging, dev) so that we can control which dynamodb tables we connect to.

Any guidance here?

[ganeshnj]

@Kralizek If understood it correctly, we plan to support Startup.Configure method which will be used to configure the request pipeline.

[ganeshnj]

@lukeemery serverless.template writer only updates the configuration that are updatable from C# code, rest of the of the configuration is not altered. Anything added outside the scope, will stay as part of template.

You can setup environment variable using existing Environment property

"Environment": {
  "Variables": {
    "Foo": "Bar"
  }
}

[Kralizek]

That's great to hear but I was referring to the steps necessary to customize the IConfigurationBuilder.

Use case:

• I want to pick up values from the parameter store and/or secrets manager
• I want to load some values from a file stored in S3

[ganeshnj]

I see what you mean. I have not tested it myself but this should still work. It can go to Startup.ConfigureServices method.

[Kralizek]

I'm not sure I can see how I would be able to customize the IConfigurationBuilder from the ConfigureServices method you suggest.

[normj]

@Kralizek IConfiguration is not in the IServiceProvider by default. Since startup is such a concern we want to keep everything as lean as possible by default and you choose what you want added. Assuming you want IConfiguration in there then in the ConfigureServices you would create your own ConfigurationBuilder and add whatever providers you want. Then add the resulting IConfiguration to the IServiceCollection.

[Kralizek]

Oh I see what you're suggesting now. Thanks @normj

[bruceharrison1984]

Is support for SAM templates on the roadmap for this?

Nevermind, using these annotations works fine. Just place your solution within a SAM template and change the resources to be a nested template and point at serverless.template.

I did need to run through the guided setup the first time, otherwise it puts the entire source-code and publish directory in the final artifact. Once I did the guided setup, the functions deploy flawlessly via SAM.

[normj]

As part of the .NET 6 managed runtime release we added a blueprint in Visual Studio that uses this preview library.

[jaknor]

Hey @normj ! First of all great work on this! Looks like a really intersting approach.

In the announcement blog post it says This means you don’t have to worry about function handler strings not being set correctly in CloudFormation templates or lose focus while coding to also update your CloudFormation JSON or YAML template.. However, looking at the task list here I don't think YAML support has been implemented yet? I got a few weird errors when trying to use YAML so might be a good idea to update the blog post to avoid confusion.

Also, will there be a way of specifying the template path (or get it to search upwards until it finds it) and the template file name?

[normj]

@jaknor you are correct we haven't added YAML support but it is planned to be added.

You can configure the location of the CloudFormation template using the aws-lambda-tools-defaults.json file and setting the template property to the CloudFormation template. Do you think you need more control then that to configure the location of the CloudFormation template?

[jaknor]

Thanks for that @normj At the moment we don't really use the aws-lambda-tools-defaults.json file for anything but I think it should give us enough control over the template location for our needs.

I did run into another issue though. If I set the template location to a different folder (I.E. "template": "..\\template.yaml") then the CodeUri property of the lambdas does not appear to take this into account so instead of pointing to the folder with the project of the lambda they are pointing to .. which doesn't work as there is no code there. Is there a way we could get the CodeUri generation to be aware of the template location and be set correctly?

[normj]

@jaknor The CodeUri properties in the template should be relative to the location of the template file. If that is not what you are seeing then can you file a separate issue so we don't lose that bug in this thread?

[jwarhurst]

Are you forced into CloudFormation template? I love the built in DI, but would prefer to use CDK.

[normj]

We want to support more then CloudFormation. CDK is tricky because then we have to figure out how to generate the CDK code within project, so we might have to make some assumptions. One of things we have thought of is to to generate a metadata JSON file that would contain all of the function handler strings generated. Then you could use that metadata to update your CDK code with the generated function handler strings to tie the source generation with the deployment tech.

[RichiCoder1]

A nice MVP would just be a simple way/package that maps generated handler and function information to something easily consumuble by the CDK. Agree that full on generating CDK code would be very hard, and possibly undesirable as I imagine if you're using the CDK you're doing it for full control.

In theory you could probably do this today by reading the mangled handle and src that are generated from CDK, but it's not a super nice dev UX.

And for the question "why annotations if you're handling everything in CDK", the handler code generation experience is still super nice and desireable from a CDK perspective.

[normj]

Agree that Annotations library should be useful users to more then just CloudFormation users. We also want to use the Annotations and source generators to make it easier for coding event handling as well. We have been doing that for API based functions but we should be able to do this for other event types.

I thought if we wrote the metadata in JSON you could read that JSON in your CDK code and do the appropriate work based on that.

[bjorg]

The problem with CDK is that it is not language agnostic. So, in what language should be used to generated it? If it's C# then you will not be able to compose with most of the other CDK constructs. Sadly, this situation could have been avoided if the CloudFormation team had defined a way to compose templates.

[RichiCoder1]

Agree that Annotations library should be useful users to more then just CloudFormation users. We also want to use the Annotations and source generators to make it easier for coding event handling as well. We have been doing that for API based functions but we should be able to do this for other event types.

I thought if we wrote the metadata in JSON you could read that JSON in your CDK code and do the appropriate work based on that.

That would def be a path forward! It'd be pretty easy to make (and I could PoC as a community contribution) a package which knows how to consume that and pass it to Function from the lambda lib. And maybe do some verification that there are constructs present in the current stack that align with what's attribute'd, if that makes sense.

The problem with CDK is that it is not language agnostic. So, in what language should be used to generated it? If it's C# then you will not be able to compose with most of the other CDK constructs. Sadly, this situation could have been avoided if the CloudFormation team had defined a way to compose templates.

You sorta can with CDK include, but it's pretty hacky for sure.

[cchen-ownit]

Are there plans for more types of annotations?

This starts to resemble Azure Functions in the best way possible given how easy it is to "snap together" Azure Blob Storage to Azure Functions to Azure CosmosDB to Azure Service Bus, etc.

[Simonl9l]

@normj et al beyond the CDK there is potentially another similar issue if one wants to deploy the lambda in a docker container as it seems the Dockerfile CMD requires the generated lambda name per the CF template.

[normj]

Version 0.6.0-preview has been released. It contains a breaking change to move the API Gateway .NET attributes to a new Amazon.Lambda.Annotations.APIGateway namespace. We wanted to make sure when we add more services that we would not make the root namespace Amazon.Lambda.Annotations too confusing or run into conflicts.

Due to the breaking change and the way source generators work if you update your project you might need to restart Visual Studio after updating. Otherwise the events section in the CloudFormation template might disappear.

Note, we avoid making breaking changes as much as possible but since this is in preview and it is important we set our selves up for the future we think this breaking change is warranted.

There are also a couple other fixes dealing with functions that return null and making sure the CloudFormation is synced when all of the LambdaFunctionAttribute are removed.

[Simonl9l]

@normj thanks for the update.

For the time being we’re sticking with the dotnet 6 minimal API setup given need for ALB bindings, and related issues below.

We figure it’s minimal effort to switch over to the annotations library as it progresses…

Our main issues as it stand is not the annotations library itself but the tool support either via the lambda test tools - not supporting the lambda lifecycle, or the Rider AWS toolkit support at all in a reliable way we can use access the dev team.

We have issues opened on both.

We’re also interested to see where any CDK integration goes. Including Docker and Extensions support. We’ve been experimenting with Local Stack such that our dev env fully replicates our eventual production deployment stack, and have been able to deploy and test lambdas locally.

We realize you have limited capacity/resources in the dotnet space, but are exited at your continued efforts and your ongoing commitment to make it’s support equivalent of other languages.

[ryanpsm]

@normj If I want to return different HTTP status codes and error messages depending on the issue that arose during processing the request, is that possible with the Annotations API?

The regular Lambda model has returns such as:

return new APIGatewayHttpApiV2ProxyResponse {
    StatusCode = (int)HttpStatusCode.BadRequest,
    Body = "Failed to process request due to invalid type parameter."
    Headers = new Dictionary<string, string> { { "Content-Type", "text/plain" } }
};

return new APIGatewayHttpApiV2ProxyResponse {
        StatusCode = (int)HttpStatusCode.OK,
        Body = "Successfully sent message.",
        Headers = new Dictionary<string, string> { { "Content-Type", "text/plain" } }
};

And the new version from the examples is as far as I can tell just:

return "Successfully sent message.";

[normj]

@ryanpsm With the Annotations library you can still return the APIGatewayHttpApiV2ProxyResponse to customize the status codes and headers returned. I have thought about creating an optional base class that could have the familiar Ok, NotFound and other base methods for a better experience. Curious what others thoughts are on that.