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 中首次推出的顶级语句功能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 存储桶中。
例 Function.cs Lambda 函数
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 文件包含以下代码部分：
-
using语句：使用这些语句可导入 Lambda 函数所需的 C# 类。 -
[assembly: LambdaSerializer(...)]：LambdaSerializer是一个程序集属性，告诉 Lambda 在将 JSON 事件负载传递给函数之前自动将其转换为 C# 对象。 -
namespace ExampleLambda：用于定义命名空间。在 C# 中，命名空间名称不必与文件名一致。 -
public class Order {...}：用于定义预期输入事件的形状。 -
public class OrderHandler {...}：用于定义您的 C# 类。在其中，您可以定义主处理程序方法和任何其他帮助程序方法。 -
private static readonly AmazonS3Client s3Client = new();：用于在主处理程序方法之外使用默认凭证提供程序链来初始化 Amazon S3 客户端。这会导致 Lambda 在初始化阶段运行此代码。 -
public async ... HandleRequest (Order order, ILambdaContext context)：这是包含主应用程序逻辑的主处理程序方法。 -
private async Task UploadReceiptToS3(...) {}：这是主handleRequest处理程序方法引用的帮助程序方法。
由于此函数需要 Amazon S3 SDK 客户端，因此您必须将其添加到项目的依赖项中。您可以导航到 src/ExampleCS 并使用以下命令来执行此操作：
dotnet add package AWSSDK.S3默认情况下，生成的 aws-lambda-tools-defaults.json 文件不包含函数的 profile 或 region 信息。此外，请将 function-handler 字符串更新为正确的值（ExampleCS::ExampleLambda.OrderHandler::HandleRequest）。您可以手动进行此更新并添加必要的元数据，以便将特定的凭证配置文件和区域用于您的函数。例如，您的 aws-lambda-tools-defaults.json 文件应如下所示：
{
"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 操作。如果您使用的是 dotnet lambda deploy-function 命令（即 dotnet lambda deploy-function ExampleCS），则 CLI 提示中的 AWSLambdaExecute 策略会包含成功调用此函数所需的权限。
另外，请确保
最后，请确保您定义了 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，其中：
-
ASSEMBLY是您的应用程序的 .NET 程序集文件的名称。如果您使用Amazon.Lambda.ToolsCLI 来构建应用程序，但未使用.csproj文件中的AssemblyName属性来设置程序集名称，则ASSEMBLY只是.csproj文件的名称。 -
TYPE是处理程序类型的全称，即NAMESPACE.CLASSNAME。 -
METHOD是代码中主处理程序方法的名称，即METHODNAME。
对于本页上的主要示例代码，如果程序集被命名为 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 处理程序签名：
-
public async Task<string> HandleRequest() -
public async Task<string> HandleRequest(Order order) -
public async Task<string> HandleRequest(ILambdaContext context)
除了处理程序签名的基本语法外，还有一些额外限制：
-
您不能在处理程序签名中使用
unsafe关键字。但是，您可以在处理程序方法及其依赖项中使用unsafe上下文。有关更多信息，请参阅 Microsoft 文档网站上的 unsafe（C# 参考）。 -
处理程序不得使用
params关键字，也不能使用ArgIterator作为输入或返回参数。这些关键字支持可变数量的参数。处理程序可以接受的参数最多为两个。 -
处理程序不能是泛型方法。换句话说，它不能使用泛型类型参数，例如
<T>。 -
Lambda 不支持签名中带有
async void的异步处理程序。
处理程序命名约定
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# 函数有两种序列化方法：基于反射的序列化和源生成的序列化。
基于反射的序列化
AWS 提供了预先构建的库，您可以快速将其添加到您的应用程序中。这些库使用反射
-
Amazon.Lambda.Serialization.SystemTextJson– 在后端，此程序包使用System.Text.Json来执行序列化任务。 -
Amazon.Lambda.Serialization.Json– 在后端，此程序包使用Newtonsoft.Json来执行序列化任务。
您还可以通过实施 ILambdaSerializer 接口（作为 Amazon.Lambda.Core 库的一部分提供）创建您自己的序列化库。该接口定义了两种方法：
-
T Deserialize<T>(Stream requestStream);通过实施此方法，您可以将请求负载从
InvokeAPI 反序列化至传递到 Lambda 函数处理程序的对象中。 -
T Serialize<T>(T response, Stream responseStream);通过实施此方法，您可以将从 Lambda 函数处理程序中返回的结果序列化到
InvokeAPI 操作返回的响应负载中。
本页的主要示例使用了基于反射的序列化。基于反射的序列化与 AWS Lambda 一起开箱即用，无需进行额外设置，因此，如果想要操作简单，这是一个不错的选择。但是，它确实需要使用更多的函数内存。由于运行时反射，您可能还会遭遇更高的函数延迟。
源生成的序列化
使用源生成的序列化，序列化代码会在编译时生成。这种序列化消除了反射需求，可以提高函数性能。要在函数中使用源生成的序列化，请执行以下操作：
-
创建一个继承自
JsonSerializerContext的新部分类，为所有需要序列化或反序列化的类型添加JsonSerializable属性。 -
配置
LambdaSerializer以使用SourceGeneratorLambdaJsonSerializer<T>。 -
更新应用程序代码中的任何手动序列化和反序列化，以使用新创建的类。
以下示例说明了如何修改本页上的主要示例（该示例使用了基于反射的序列化），改为使用源生成的序列化。
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);
...
}
}与基于反射的序列化相比，源生成的序列化需要进行更多设置。但是，由于编译时生成代码，使用源生成的函数往往会占用更少的内存并具备更好的性能。要消除函数冷启动，可以考虑切换到源生成的序列化。
注意
如果您想将本机提前编译（AOT）与 Lambda 结合使用，则必须使用源生成的序列化。
访问和使用 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 的 SDK v3
通常，您将使用 Lambda 函数与其他 AWS 资源进行交互或对其进行更新。与此类资源最简单的交互方法是使用 适用于 .NET 的 SDK v3。
注意
适用于 .NET 的 SDK（v2）已弃用。建议您只使用 适用于 .NET 的 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 客户端后，您可以使用该客户端与其他 AWS 服务进行交互。示例代码按如下方式调用 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 注释
有关使用 Lambda 注释的完整应用示例，请参阅 awsdocs/aws-doc-sdk-examples GitHub 存储库中的 PhotoAssetManagerPamApiAnnotations 目录中的 主 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 函数时，请遵循以下列表中的指南，采用最佳编码实践：
-
从核心逻辑中分离 Lambda 处理程序。这样您可以创建更容易进行单元测试的函数。
-
控制函数部署程序包中的依赖关系。AWS Lambda 执行环境包含许多库。Lambda 会定期更新这些库，以支持最新的功能组合和安全更新。这些更新可能会使 Lambda 函数的行为发生细微变化。要完全控制您的函数所用的依赖项，请使用部署程序包来打包所有依赖项。
-
将依赖关系的复杂性降至最低。首选在执行环境启动时可以快速加载的更简单的框架。
-
将部署程序包大小精简为只包含运行时必要的部分。这样会减少调用前下载和解压缩部署程序包所需的时间。对于用 .NET 编写的函数，请不要将整个 AWS SDK 库作为部署程序包的一部分上传。而是要根据所需的模块有选择地挑选软件开发工具包中的组件（例如 DynamoDB、Simple Storage Service (Amazon S3) 软件开发工具包模块和 Lambda 核心库）。
-
利用执行环境重用来提高函数性能。连接软件开发工具包 (SDK) 客户端和函数处理程序之外的数据库，并在
/tmp目录中本地缓存静态资产。由函数的同一实例处理的后续调用可重用这些资源。这样就可以通过缩短函数运行时间来节省成本。为了避免调用之间潜在的数据泄露，请不要使用执行环境来存储用户数据、事件或其他具有安全影响的信息。如果您的函数依赖于无法存储在处理程序的内存中的可变状态，请考虑为每个用户创建单独的函数或单独的函数版本。
-
使用 keep-alive 指令来维护持久连接。Lambda 会随着时间的推移清除空闲连接。在调用函数时尝试重用空闲连接会导致连接错误。要维护您的持久连接，请使用与运行时关联的 keep-alive 指令。有关示例，请参阅在 Node.js 中通过 Keep-Alive 重用连接。
-
使用环境变量将操作参数传递给函数。例如，您在写入 Amazon S3 存储桶时，不应对要写入的存储桶名称进行硬编码，而应将存储桶名称配置为环境变量。
-
避免在 Lambda 函数中使用递归调用，在这种情况下，函数会调用自己或启动可能再次调用该函数的进程。这可能会导致意想不到的函数调用量和升级成本。如果您看到意外的调用量，请立即将函数保留并发设置为
0来限制对函数的所有调用，同时更新代码。 -
Lambda 函数代码中不要使用非正式的非公有 API。对于 AWS Lambda 托管式运行时，Lambda 会定期为 Lambda 的内部 API 应用安全性和功能更新。这些内部 API 更新可能不能向后兼容，会导致意外后果，例如，假设您的函数依赖于这些非公有 API，则调用会失败。请参阅 API 参考以查看公开发布的 API 列表。
-
编写幂等代码。为您的函数编写幂等代码可确保以相同的方式处理重复事件。您的代码应该正确验证事件并优雅地处理重复事件。有关更多信息，请参阅如何使我的 Lambda 函数具有幂等性？
。
