Unleashing the Power of the Lambda Annotations Framework for .NET

We are excited to announce the general availability of the Lambda Annotations Framework for .NET. This innovative programming model offers a more natural experience for .NET developers when writing AWS Lambda functions in C#. By leveraging C# Source Generators, the Lambda Annotations Framework simplifies the process, making it more idiomatic for developers familiar with the .NET environment.

What is the Lambda Annotations Framework?

The Lambda Annotations Framework introduces a seamless programming model specifically designed for .NET developers, aimed at creating AWS Lambda functions. The framework utilizes custom attributes in C# alongside Source Generators to convert annotated Lambda functions into the traditional Lambda programming model. This translation occurs at compile time, ensuring no adverse effects on Lambda startup times.

Source Generators integrate directly with the C# compiler for code generation during project compilation. This means all you need to use Lambda Annotations is the Lambda Annotations NuGet package. Compatible deployment tools, including the AWS Toolkit for Visual Studio, the Lambda .NET CLI, and AWS SAM, can effectively leverage Lambda Annotations.

To illustrate the difference, let’s examine a simple Lambda function. Below, you’ll find a sample function that processes REST API requests from the Amazon API Gateway:

Traditional Lambda Function

csharp
public class Functions
{
public APIGatewayProxyResponse LambdaMathPlus(APIGatewayProxyRequest request, ILambdaContext context)
{
if (!request.PathParameters.TryGetValue(“x”, out var xs))
{
return new APIGatewayProxyResponse
{
StatusCode = (int)HttpStatusCode.BadRequest
};
}
if (!request.PathParameters.TryGetValue(“y”, out var ys))
{
return new APIGatewayProxyResponse
{
StatusCode = (int)HttpStatusCode.BadRequest
};
}

    var x = int.Parse(xs);
    var y = int.Parse(ys);

    return new APIGatewayProxyResponse
    {
        StatusCode = (int)HttpStatusCode.OK,
        Body = (x + y).ToString(),
        Headers = new Dictionary<string, string> { { "Content-Type", "text/plain" } }
    };
} 

}

The same functionality implemented using the Lambda Annotations Framework is much simpler:

Using the Lambda Annotations Framework

csharp
public class Functions
{
[LambdaFunction]
[RestApi(“/plus/{x}/{y}”)]
public int Plus(int x, int y)
{
return x + y;
}
}

As shown, the Annotations Framework minimizes boilerplate code and makes your Lambda functions look more concise and easier to understand.

Key Features of the Lambda Annotations Framework

The Lambda Annotations Framework incorporates several advantageous features:

• Dependency Injection: Facilitate scenario-based dependencies akin to ASP.NET Core applications.
• AWS CloudFormation Syncing: Automatically manages and maintains CloudFormation templates.
• Code Generation: Reduces boilerplate through intelligent code generation.
• JSON and YAML CloudFormation Template Support: Ensures compatibility with various CloudFormation formats.

Getting Started with the Lambda Annotations Framework

Creating a new AWS Serverless Application using Lambda Annotations Framework is straightforward. To follow this guide, ensure you have the following tools installed and configured:

1. Visual Studio: If you prefer a CLI approach, you can use the Amazon.Lambda.Templates NuGet package to create a project.

Here’s how to create a new serverless application via CLI:

bash
dotnet new install Amazon.Lambda.Templates
dotnet new serverless.Annotations –output LambdaAnnotations

Creating a Serverless Application in Visual Studio

To get started using the AWS Toolkit for Visual Studio:

1. Open Visual Studio and create a new AWS Serverless Application.
2. Name your project LambdaAnnotations.
3. On the Select Blueprint page, choose Annotations Framework, then click Finish.

The generated project will include a collection of Lambda functions within the Function.cs file, simulating a calculator as a REST API. In the Add Lambda function, the [LambdaFunction] attribute identifies the function, while the [HttpApi] attribute sets the API Gateway event configuration in the corresponding CloudFormation template.

Sample Function with Annotations

csharp
[LambdaFunction()]
[HttpApi(LambdaHttpMethod.Get, “/add/{x}/{y}”)]
public int Add(int x, int y, ILambdaContext context)
{
var sum = _calculatorService.Add(x, y);
context.Logger.LogInformation($”{x} plus {y} is {sum}”);
return sum;
}

If you’re building Lambda functions that aren’t for API Gateway, you can still use the LambdaFunction attribute along with configurations in the CloudFormation template.

Building a Serverless Application from Scratch

To illustrate using the Lambda Annotations Framework more practically, let’s create a serverless application that utilizes the Amazon Translate service to translate text into different languages.

Initializing Your Functions

You’ll begin by removing the calculator APIs in the Functions.cs file. Afterward, recompile the project, which will eliminate any declared Lambda functions in the serverless.template.

Dependency Injection

Dependency Injection (DI) is a fundamental feature of the Lambda Annotations Framework. The framework allows you to set up DI exactly as you would in ASP.NET Core applications, through LambdaStartup and LambdaFunction attributes.

Configuring Services

Open the Startup.cs file. In the ConfigureServices method, add the AWS SDK service client necessary for Amazon Translate.

1. Include the following NuGet packages in your LambdaAnnotations project:

   • AWSSDK.Translate
   • AWSSDK.Extensions.NETCore.Setup

2. In the ConfigureServices method, add:

csharp
services.AddAWSService();

This setup declares the Startup class as the dependency configuration class.

Injecting Dependencies

You can inject dependencies into your Lambda functions efficiently—either through a function constructor or directly within the method signature. Constructor injection is ideal for services shared across invocations.

Example Constructor Injection

Here’s how your Functions class might look after injecting the translate client into the constructor:

csharp
public class Functions
{
private IAmazonTranslate _translateClient;

public Functions(IAmazonTranslate translateClient)
{
    _translateClient = translateClient;
} 

}

Writing the Translation Function

Now, let’s craft the primary logic to perform translations. In the TranslateFromEnglish method:

csharp
public async Task TranslateFromEnglish(string targetLanguageCode, string text)
{
var request = new TranslateTextRequest
{
SourceLanguageCode = “en-US”,
TargetLanguageCode = targetLanguageCode,
Text = text
};

var response = await _translateClient.TranslateTextAsync(request);
return response.TranslatedText;

}

Defining Lambda Attributes

Decorate this method with the [LambdaFunction] attribute to specify IAM policies and sync with API Gateway:

csharp
[LambdaFunction(Policies = “TranslateReadOnly, AWSLambdaBasicExecutionRole”)]
[HttpApi(LambdaHttpMethod.Post, “/translate/{targetLanguageCode}”)]
public async Task TranslateFromEnglish(string targetLanguageCode, [FromBody] string text)

This setup binds the method to handle POST requests, where the translated text resides in the body.

Error Handling and Logging

Handling errors and producing meaningful logs are crucial in a production environment. The updated translation function now captures potential exceptions and logs pertinent details using ILambdaContext.

csharp
catch (UnsupportedLanguagePairException)
{
context.Logger.LogWarning($”Invalid target language code: {targetLanguageCode}”);
return HttpResults.BadRequest($”Translating from English to {targetLanguageCode} is not supported”);
}
catch (Exception ex)
{
context.Logger.LogError(“Unknown error performing translate”);
context.Logger.LogError(ex.ToString());
return HttpResults.InternalServerError();
}

This structured error handling enhances the stability of your Lambda function.

Deployment

Once everything is set up, deploying the function to AWS Lambda is simple. Right-click the .NET project and choose Publish to AWS Lambda… The AWS Toolkit for Visual Studio handles deployment via CloudFormation, synchronously updating the CloudFormation template you’ve been working with.

Source Generation Features

The Lambda Annotations Framework significantly improves the development experience by minimizing redundancy through source generation. You can view the generated functions via Solution Explorer in Visual Studio under the Analyzers.

The framework automates:

• Adjustments to method signatures for API Gateway compliance
• Parameter checks and error handling
• Updates to the return type for compatibility with API Gateway

With these features, you can focus on delivering business value instead of wrestling with boilerplate code.

The Lambda Annotations Framework for .NET unlocks compelling capabilities and a smoother development journey, allowing you to harness AWS Lambda’s power with the elegance of C#. Whether you’re building simple functions or complex serverless applications, the framework provides the tools you need to succeed effortlessly.