定义采用 C# 的 Lambda 函数处理程序

Lambda 函数处理程序是函数代码中处理事件的方法。当调用函数时，Lambda 运行处理程序方法。您的函数会一直运行，直到处理程序返回响应、退出或超时。

本页介绍如何将 C# Lambda 函数处理程序与 .NET 托管运行时配合使用，包括项目设置选项、命名约定和最佳实践。本页还包括 C# Lambda 函数的示例，在示例中该函数接收订单信息，生成文本文件收据，然后将此文件放入 Amazon Simple Storage Service（S3）存储桶中。有关如何在编写函数后部署函数的信息，请参阅使用 .zip 文件归档构建和部署 C# Lambda 函数或使用容器映像部署 .NET Lambda 函数。

设置 C# 处理程序项目

使用 C# Lambda 函数时，此过程包括编写代码，然后将代码部署到 Lambda。在 .NET 中部署 Lambda 函数有两种不同的执行模型：类库方法和可执行程序集方法。

在类库方法中，您可以将函数代码打包为 .NET 程序集（.dll），然后使用 .NET 托管运行时（dotnet8）将其部署到 Lambda。对于处理程序名称，Lambda 需要采用格式为 AssemblyName::Namespace.Classname::Methodname 的字符串。在函数的初始化阶段，会初始化函数的类，构造函数中的所有代码都会运行。

在可执行程序集方法中，您可以使用 C# 9 中首次推出的顶级语句功能。这种方法会生成一个可执行程序集，每当 Lambda 收到函数的调用命令时，它就会运行该程序集。在这种方法中，您还可以使用 .NET 托管运行时（dotnet8）。对于处理程序名称，您可以向 Lambda 提供要运行的可执行程序集的名称。

本页的主要示例说明了类库方法。您可以通过多种方式初始化 C# Lambda 项目，但最简单的方法是将 .NET CLI 与 Amazon.Lambda.Tools CLI 结合使用。按照 设置 .NET 开发环境 中的步骤设置 Amazon.Lambda.Tools CLI。然后使用以下命令来初始化您的项目：

dotnet new lambda.EmptyFunction --name ExampleCS

此命令会生成以下文件结构：

/project-root 
    └ src
        └ ExampleCS
            └ Function.cs (contains main handler)
            └ Readme.md
            └ aws-lambda-tools-defaults.json
            └ ExampleCS.csproj          
    └ test
         └ ExampleCS.Tests
            └ FunctionTest.cs (contains main handler)
            └ ExampleCS.Tests.csproj 

在此文件结构中，函数的主处理程序逻辑位于 Function.cs 文件中。

示例 C# Lambda 函数代码

以下示例 C# Lambda 函数代码接收有关订单的信息，生成文本文件接收，并将此文件放入 Amazon S3 存储桶中。

using System;
using System.Text;
using System.Threading.Tasks;
using Amazon.Lambda.Core;
using Amazon.S3;
using Amazon.S3.Model;

// Assembly attribute to enable Lambda function logging
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

namespace ExampleLambda;

public class Order
{
    public string OrderId { get; set; } = string.Empty;
    public double Amount { get; set; }
    public string Item { get; set; } = string.Empty;
}

public class OrderHandler
{
    private static readonly AmazonS3Client s3Client = new();

    public async Task<string> HandleRequest(Order order, ILambdaContext context)
    {
        try
        {
            string? bucketName = Environment.GetEnvironmentVariable("RECEIPT_BUCKET");
            if (string.IsNullOrWhiteSpace(bucketName))
            {
                throw new ArgumentException("RECEIPT_BUCKET environment variable is not set");
            }

            string receiptContent = $"OrderID: {order.OrderId}\nAmount: ${order.Amount:F2}\nItem: {order.Item}";
            string key = $"receipts/{order.OrderId}.txt";

            await UploadReceiptToS3(bucketName, key, receiptContent);

            context.Logger.LogInformation($"Successfully processed order {order.OrderId} and stored receipt in S3 bucket {bucketName}");
            return "Success";
        }
        catch (Exception ex)
        {
            context.Logger.LogError($"Failed to process order: {ex.Message}");
            throw;
        }
    }

    private async Task UploadReceiptToS3(string bucketName, string key, string receiptContent)
    {
        try
        {
            var putRequest = new PutObjectRequest
            {
                BucketName = bucketName,
                Key = key,
                ContentBody = receiptContent,
                ContentType = "text/plain"
            };

            await s3Client.PutObjectAsync(putRequest);
        }
        catch (AmazonS3Exception ex)
        {
            throw new Exception($"Failed to upload receipt to S3: {ex.Message}", ex);
        }
    }
}

此 Function.cs 文件包含以下代码部分：

由于此函数需要 Amazon S3 SDK 客户端，因此您必须将其添加到项目的依赖项中。您可以导航到 src/ExampleCS 并使用以下命令来执行此操作：

dotnet add package AWSSDK.S3

{
  "Information": [
    "This file provides default values for the deployment wizard inside Visual Studio and the AWS Lambda commands added to the .NET Core CLI.",
    "To learn more about the Lambda commands with the .NET Core CLI execute the following command at the command line in the project root directory.",
    "dotnet lambda help",
    "All the command line options for the Lambda command can be specified in this file."
  ],
  "profile": "default",
  "region": "us-east-1",
  "configuration": "Release",
  "function-architecture": "x86_64",
  "function-runtime": "dotnet8",
  "function-memory-size": 512,
  "function-timeout": 30,
  "function-handler": "ExampleCS::ExampleLambda.OrderHandler::HandleRequest"
}

要使此函数正常运行，其执行角色必须允许 s3:PutObject 操作。此外，请确保您定义了 RECEIPT_BUCKET 环境变量。成功调用后，Amazon S3 存储桶应包含接收文件。

类库处理程序

本页的主要示例代码说明了类库处理程序。类库处理程序具有以下结构：

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

namespace NAMESPACE;

...

public class CLASSNAME {
    public async Task<string> METHODNAME (...) {
    ...
    }
}

创建 Lambda 函数时，您需要在处理程序字段中以字符串的形式向 Lambda 提供有关您的函数处理程序的信息。这会告知 Lambda 在函数被调用时运行代码中的哪个方法。在 C# 中，对于类库处理程序，处理程序字符串的格式为 ASSEMBLY::TYPE::METHOD，其中：

对于本页上的主要示例代码，如果程序集被命名为 ExampleCS，则完整的处理程序字符串将为 ExampleCS::ExampleLambda.OrderHandler::HandleRequest。

可执行程序集处理程序

您也可以在 C# 中将 Lambda 函数定义为可执行程序集。可执行程序集处理程序利用了 C# 的顶级语句功能，在该功能中，编译器会生 成Main() 方法并将您的函数代码放入其中。使用可执行程序集时，必须引导 Lambda 运行时系统。为此，请在代码中使用 LambdaBootstrapBuilder.Create 方法。此方法的输入是要使用的主处理程序函数和 Lambda 序列化程序。以下是 C# 中可执行程序集处理程序的示例：

namespace GetProductHandler;

IDatabaseRepository repo = new DatabaseRepository();

await LambdaBootstrapBuilder.Create<APIGatewayProxyRequest>(Handler, new DefaultLambdaJsonSerializer())
    .Build()
    .RunAsync();

async Task<APIGatewayProxyResponse> Handler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
{
    var id = apigProxyEvent.PathParameters["id"];
    var databaseRecord = await this.repo.GetById(id);
    
    return new APIGatewayProxyResponse 
    {
        StatusCode = (int)HttpStatusCode.OK,
        Body = JsonSerializer.Serialize(databaseRecord)
    };
};

在可执行程序集处理程序的处理程序字段中，告知 Lambda 如何运行代码的处理程序字符串是程序集的名称。在此示例中为 GetProductHandler。

C# 函数的有效处理程序签名

在 C# 中，有效的 Lambda 处理程序签名需要 0 到 2 个参数。通常，处理程序签名具有两个参数，如主示例所示：

public async Task<string> HandleRequest(Order order, ILambdaContext context)

提供两个参数时，第一个参数必须是事件输入，第二个参数则必须是 Lambda 上下文对象。两个参数都为选填。例如，以下示例也是 C# 中有效的 Lambda 处理程序签名：

除了处理程序签名的基本语法外，还有一些额外限制：

处理程序命名约定

C# 中的 Lambda 处理程序并没有严格的命名限制。但是，您必须确保在部署函数时向 Lambda 提供正确的处理程序字符串。正确的处理程序字符串取决于您部署的是类库处理程序还是可执行程序集处理程序。

尽管处理程序可以使用任意名称，但 C# 中的函数名称通常采用 PascalCase。此外，尽管文件名不需要与类名或处理程序名称一致，但通常情况下，如果类名是 OrderHandler，最佳做法是使用像 OrderHandler.cs 这样的文件名。例如，您可以将本示例中的文件名从 Function.cs 修改为 OrderHandler.cs。

C# Lambda 函数中的序列化

JSON 是 Lambda 函数最常用且最标准的输入格式。在此示例中，该函数需要类似于下方的输入：

{
    "orderId": "12345",
    "amount": 199.99,
    "item": "Wireless Headphones"
}

在 C# 中，您可以在类中定义预期输入事件的形状。在此示例中，我们定义了 Order 类来为此输入建模：

public class Order
{
    public string OrderId { get; set; } = string.Empty;
    public double Amount { get; set; }
    public string Item { get; set; } = string.Empty;
}

如果您的 Lambda 函数使用 Stream 对象以外的输入或输出类型，您必须向应用程序中添加一个序列化库。这样您就可以将 JSON 输入转换为您定义的类的实例。Lambda 中的 C# 函数有两种序列化方法：基于反射的序列化和源生成的序列化。

基于反射的序列化

Amazon 提供了预先构建的库，您可以快速将其添加到您的应用程序中。这些库使用反射来实现序列化。使用以下程序包之一可实现基于反射的序列化：

您还可以通过实施 ILambdaSerializer 接口（作为 Amazon.Lambda.Core 库的一部分提供）创建您自己的序列化库。该接口定义了两种方法：

本页的主要示例使用了基于反射的序列化。基于反射的序列化与 Amazon Lambda 一起开箱即用，无需进行额外设置，因此，如果想要操作简单，这是一个不错的选择。但是，它确实需要使用更多的函数内存。由于运行时反射，您可能还会遭遇更高的函数延迟。

源生成的序列化

使用源生成的序列化，序列化代码会在编译时生成。这种序列化消除了反射需求，可以提高函数性能。要在函数中使用源生成的序列化，请执行以下操作：

以下示例说明了如何修改本页上的主要示例（该示例使用了基于反射的序列化），改为使用源生成的序列化。

using System.Text.Json;
using System.Text.Json.Serialization;

...

public class Order
{
    public string OrderId { get; set; } = string.Empty;
    public double Amount { get; set; }
    public string Item { get; set; } = string.Empty;
}

[JsonSerializable(typeof(Order))]
public partial class OrderJsonContext : JsonSerializerContext {}

public class OrderHandler
{

    ...

    public async Task<string> HandleRequest(string input, ILambdaContext context)
    {
    
    var order = JsonSerializer.Deserialize(input, OrderJsonContext.Default.Order);
    
    ...
    
    }

}

与基于反射的序列化相比，源生成的序列化需要进行更多设置。但是，由于编译时生成代码，使用源生成的函数往往会占用更少的内存并具备更好的性能。要消除函数冷启动，可以考虑切换到源生成的序列化。

访问和使用 Lambda 上下文对象

Lambda 上下文对象包含有关调用、函数和执行环境的信息。在此示例中，上下文对象的类型为 Amazon.Lambda.Core.ILambdaContext，是主处理程序函数的第二个参数。

public async Task<string> HandleRequest(Order order, ILambdaContext context) {
    ...
}

上下文对象是可选输入。有关有效接受处理程序签名的更多信息，请参阅C# 函数的有效处理程序签名。

上下文对象对于向 Amazon CloudWatch 生成函数日志非常有用。您可以使用 context.getLogger() 方法获取用于日志记录的 LambdaLogger 对象。在此示例中，如果由于任何原因处理失败，我们可以使用记录器记录错误消息：

context.Logger.LogError($"Failed to process order: {ex.Message}");

除了日志记录之外，您还可以使用上下文对象进行函数监控。有关上下文对象的更多信息，请参阅使用 Lambda 上下文对象检索 C# 函数信息。

在处理程序中使用 适用于 .NET 的 Amazon SDK v3

通常，您将使用 Lambda 函数与其他 Amazon 资源进行交互或对其进行更新。与此类资源最简单的交互方法是使用 适用于 .NET 的 Amazon SDK v3。

您可以使用以下 Amazon.Lambda.Tools 命令将 SDK 依赖项添加到您的项目中：

dotnet add package <package_name>

例如，在本页的主要示例中，我们需要使用 Amazon S3 API 将收据上传到 S3。我们可以使用以下命令导入 Amazon S3 SDK 客户端：

dotnet add package AWSSDK.S3

此命令可将依赖项添加到您的项目中。您还会在项目的 .csproj 文件中看到如下所示的行：

<PackageReference Include="AWSSDK.S3" Version="3.7.2.18" />

然后，直接在 C# 代码中导入这些依赖项：

using Amazon.S3;
using Amazon.S3.Model;

然后，示例代码将初始化 Amazon S3 客户端（使用默认凭证提供程序链），如下所示：

private static readonly AmazonS3Client s3Client = new();

在此示例中，我们在主处理程序函数之外初始化了 Amazon S3 客户端，以免每次调用函数时都必须对其进行初始化。初始化 SDK 客户端后，您可以使用该客户端与其他 Amazon 服务进行交互。示例代码按如下方式调用 Amazon S3 PutObject API：

var putRequest = new PutObjectRequest
{
    BucketName = bucketName,
    Key = key,
    ContentBody = receiptContent,
    ContentType = "text/plain"
};

await s3Client.PutObjectAsync(putRequest);

评估环境变量

在处理程序代码中，您可以使用 System.Environment.GetEnvironmentVariable 方法引用任何环境变量。在此示例中，我们使用以下代码行来引用已定义的 RECEIPT_BUCKET 环境变量：

string? bucketName = Environment.GetEnvironmentVariable("RECEIPT_BUCKET");
if (string.IsNullOrWhiteSpace(bucketName))
{
    throw new ArgumentException("RECEIPT_BUCKET environment variable is not set");
}

使用全局状态

在首次调用您的函数之前，Lambda 会在初始化阶段运行您的静态代码和类构造函数。初始化期间创建的资源在两次调用之间保留在内存中，因此您可以避免每次调用函数时都必须创建这些资源的情况。

在示例代码中，S3 客户端初始化代码位于主处理程序方法之外。运行时会在函数处理其第一个事件之前初始化客户端，这可能会导致更长的处理时间。后续事件的处理速度则要快得多，因为 Lambda 不需要再次初始化客户端。

使用 Lambda 注释框架简化函数代码

Lambda 注释是一个适用于 .NET 8 的框架，它简化了使用 C# 编写 Lambda 函数的过程。注释框架使用源生成器来生成从 Lambda 编程模型转换为简化代码所的代码。使用注释框架，您可以替换使用常规编程模型所编写的 Lambda 函数中的大部分代码。使用该框架所编写的代码使用了更简单的表达式，使您可以专注于业务逻辑。有关示例，请参阅 nuget 文档中的 Amazon.Lambda.Annotations。

有关使用 Lambda 注释的完整应用示例，请参阅 awsdocs/aws-doc-sdk-examples GitHub 存储库中的 PhotoAssetManager 示例。PamApiAnnotations 目录中的 主 Function.cs 文件中使用了 Lambda 注释。相比之下，PamApi 目录包含使用常规 Lambda 编程模型编写的等效文件。

使用 Lambda 注释框架进行依赖关系注入

您还可以使用 Lambda 注释框架，使用您熟悉的语法向 Lambda 函数添加依赖关系注入。当您向 Startup.cs 文件添加 [LambdaStartup] 属性时，Lambda 注释框架将在编译时生成所需的代码。

[LambdaStartup]
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddSingleton<IDatabaseRepository, DatabaseRepository>();
    }
}

您的 Lambda 函数可以使用构造函数注入或使用 [FromServices] 属性注入到各个方法中来注入服务。

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

namespace GetProductHandler;

public class Function
{
    private readonly IDatabaseRepository _repo;
    
    public Function(IDatabaseRepository repo)
    {
        this._repo = repo;
    }
    
    [LambdaFunction]
    [HttpApi(LambdaHttpMethod.Get, "/product/{id}")]
    public async Task<Product> FunctionHandler([FromServices] IDatabaseRepository repository, string id)
    {
        return await this._repo.GetById(id);
    }
}

C# Lambda 函数的代码最佳实践

在构建 Lambda 函数时，请遵循以下列表中的指南，采用最佳编码实践：