Tentukan penangan fungsi Lambda di C #

Handler fungsi Lambda Anda adalah metode dalam kode fungsi Anda yang memproses peristiwa. Saat fungsi Anda diaktifkan, Lambda menjalankan metode handler. Fungsi Anda berjalan sampai handler mengembalikan respons, keluar, atau waktu habis.

Halaman ini menjelaskan cara bekerja dengan penangan fungsi Lambda di C# untuk bekerja dengan runtime terkelola .NET, termasuk opsi untuk penyiapan proyek, konvensi penamaan, dan praktik terbaik. Halaman ini juga menyertakan contoh fungsi C# Lambda yang mengambil informasi tentang pesanan, menghasilkan tanda terima file teks, dan menempatkan file ini di bucket Amazon Simple Storage Service (S3). Untuk informasi tentang cara menerapkan fungsi Anda setelah menulisnya, lihat Bangun dan terapkan fungsi C# Lambda dengan arsip file.zip atauDeploy fungsi Lambda .NET dengan gambar kontainer.

Menyiapkan proyek handler C# Anda

Saat bekerja dengan fungsi Lambda di C #, prosesnya melibatkan penulisan kode Anda, lalu menyebarkan kode Anda ke Lambda. Ada dua model eksekusi yang berbeda untuk menerapkan fungsi Lambda di .NET: pendekatan perpustakaan kelas dan pendekatan perakitan yang dapat dieksekusi.

Dalam pendekatan pustaka kelas, Anda mengemas kode fungsi Anda sebagai .NET assembly (.dll) dan menerapkannya ke Lambda dengan runtime dotnet8 terkelola .NET (). Untuk nama handler, Lambda mengharapkan string dalam format. AssemblyName::Namespace.Classname::Methodname Selama fase inisialisasi fungsi, kelas fungsi Anda diinisialisasi, dan kode apa pun dalam konstruktor dijalankan.

Dalam pendekatan perakitan yang dapat dieksekusi, Anda menggunakan fitur pernyataan tingkat atas yang pertama kali diperkenalkan di C # 9. Pendekatan ini menghasilkan perakitan yang dapat dieksekusi yang dijalankan Lambda setiap kali menerima perintah pemanggilan untuk fungsi Anda. Dalam pendekatan ini, Anda juga menggunakan .NET managed runtime (dotnet8). Untuk nama handler, Anda memberi Lambda nama rakitan yang dapat dieksekusi untuk dijalankan.

Contoh utama pada halaman ini menggambarkan pendekatan perpustakaan kelas. Anda dapat menginisialisasi proyek C# Lambda Anda dengan berbagai cara, tetapi cara termudah adalah dengan menggunakan CLI .NET dengan CLI. Amazon.Lambda.Tools Siapkan Amazon.Lambda.Tools CLI dengan mengikuti langkah-langkah di. Menyiapkan lingkungan pengembangan .NET Anda Kemudian, inisialisasi proyek Anda dengan perintah berikut:

dotnet new lambda.EmptyFunction --name ExampleCS

Perintah ini menghasilkan struktur file berikut:

/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 

Dalam struktur file ini, logika handler utama untuk fungsi Anda berada di Function.cs file.

Contoh kode fungsi C# Lambda

Contoh kode fungsi C# Lambda berikut mengambil informasi tentang pesanan, menghasilkan tanda terima file teks, dan menempatkan file ini di bucket 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.csFile ini berisi bagian kode berikut:

Karena fungsi ini memerlukan klien SDK Amazon S3, Anda harus menambahkannya ke dependensi proyek Anda. Anda dapat melakukannya dengan menavigasi ke src/ExampleCS dan menjalankan perintah berikut:

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"
}

{
  "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"
}

Agar fungsi ini berfungsi dengan baik, peran pelaksanaannya harus memungkinkan s3:PutObject tindakan. Jika Anda menggunakan dotnet lambda deploy-function perintah (yaitudotnet lambda deploy-function ExampleCS), AWSLambdaExecute kebijakan dalam prompt CLI berisi izin yang diperlukan agar Anda berhasil menjalankan fungsi ini.

Juga, pastikan bahwa

Akhirnya, pastikan bahwa Anda mendefinisikan variabel RECEIPT_BUCKET lingkungan. Setelah pemanggilan berhasil, bucket Amazon S3 harus berisi file tanda terima.

Penangan perpustakaan kelas

Contoh kode utama pada halaman ini menggambarkan handler perpustakaan kelas. Penangan perpustakaan kelas memiliki struktur sebagai berikut:

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

namespace NAMESPACE;

...

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

Saat Anda membuat fungsi Lambda, Anda perlu memberikan Lambda informasi tentang handler fungsi Anda dalam bentuk string di bidang Handler. Ini memberi tahu Lambda metode mana dalam kode Anda untuk dijalankan ketika fungsi Anda dipanggil. Di C #, untuk penangan perpustakaan kelas, format string handler adalahASSEMBLY::TYPE::METHOD, di mana:

Untuk contoh kode utama pada halaman ini, jika perakitan diberi namaExampleCS, maka string handler penuh adalahExampleCS::ExampleLambda.OrderHandler::HandleRequest.

Penangan perakitan yang dapat dieksekusi

Anda juga dapat mendefinisikan fungsi Lambda di C # sebagai perakitan yang dapat dieksekusi. Penangan perakitan yang dapat dieksekusi menggunakan fitur pernyataan tingkat atas C#, di mana kompiler menghasilkan Main() metode dan menempatkan kode fungsi Anda di dalamnya. Saat menggunakan rakitan yang dapat dieksekusi, runtime Lambda harus di-bootstrap. Untuk melakukan ini, gunakan LambdaBootstrapBuilder.Create metode dalam kode Anda. Input untuk metode ini adalah fungsi handler utama serta serializer Lambda untuk digunakan. Berikut ini menunjukkan contoh handler assembly executable di 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)
    };
};

Di bidang Handler untuk penangan perakitan yang dapat dieksekusi, string handler yang memberi tahu Lambda cara menjalankan kode Anda adalah nama perakitan. Dalam contoh ini, ituGetProductHandler.

Tanda tangan handler yang valid untuk fungsi C #

Di C #, tanda tangan penangan Lambda yang valid mengambil antara 0 dan 2 argumen. Biasanya, tanda tangan handler Anda memiliki dua argumen, seperti yang ditunjukkan pada contoh utama:

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

Saat memberikan dua argumenhts, argumen pertama harus berupa input peristiwa, dan argumen kedua harus berupa objek konteks Lambda. Kedua argumen bersifat opsional. Misalnya, berikut ini juga merupakan tanda tangan penangan Lambda yang valid di C #:

Terlepas dari sintaks dasar tanda tangan handler, ada beberapa batasan tambahan:

Konvensi penamaan handler

Penangan Lambda di C# tidak memiliki batasan penamaan yang ketat. Namun, Anda harus memastikan bahwa Anda memberikan string handler yang benar ke Lambda saat Anda menerapkan fungsi Anda. String handler kanan bergantung pada apakah Anda menggunakan handler perpustakaan kelas atau handler perakitan yang dapat dieksekusi.

Meskipun Anda dapat menggunakan nama apa pun untuk handler Anda, nama fungsi di C # umumnya masuk. PascalCase Juga, meskipun nama file tidak perlu cocok dengan nama kelas atau nama handler, umumnya praktik terbaik untuk menggunakan nama file seperti OrderHandler.cs jika nama kelas Anda. OrderHandler Misalnya, Anda dapat memodifikasi nama file dalam contoh ini dari Function.cs keOrderHandler.cs.

Serialisasi dalam fungsi C# Lambda

JSON adalah format input yang paling umum dan standar untuk fungsi Lambda. Dalam contoh ini, fungsi mengharapkan input yang mirip dengan yang berikut:

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

Di C #, Anda dapat menentukan bentuk peristiwa input yang diharapkan di kelas. Dalam contoh ini, kita mendefinisikan Order kelas untuk memodelkan masukan ini:

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

Jika fungsi Lambda Anda menggunakan jenis input atau output selain Stream objek, Anda harus menambahkan pustaka serialisasi ke aplikasi Anda. Ini memungkinkan Anda mengonversi input JSON menjadi instance dari kelas yang Anda tentukan. Ada dua metode serialisasi untuk fungsi C# di Lambda: serialisasi berbasis refleksi dan serialisasi yang dihasilkan sumber.

Serialisasi berbasis refleksi

AWS menyediakan pustaka pra-bangun yang dapat Anda tambahkan dengan cepat ke aplikasi Anda. Pustaka ini menerapkan serialisasi menggunakan refleksi. Gunakan salah satu paket berikut untuk mengimplementasikan serialisasi berbasis refleksi:

Anda juga dapat membuat pustaka serialisasi Anda sendiri dengan mengimplementasikan ILambdaSerializer antarmuka, yang tersedia sebagai bagian dari Amazon.Lambda.Core perpustakaan. Antarmuka ini mendefinisikan dua metode:

Contoh utama pada halaman ini menggunakan serialisasi berbasis refleksi. Serialisasi berbasis refleksi bekerja di luar kotak dengan AWS Lambda dan tidak memerlukan pengaturan tambahan, menjadikannya pilihan yang baik untuk kesederhanaan. Namun, itu memang membutuhkan lebih banyak penggunaan memori fungsi. Anda juga dapat melihat latensi fungsi yang lebih tinggi karena refleksi runtime.

Serialisasi yang dihasilkan sumber

Dengan serialisasi yang dihasilkan sumber, kode serialisasi dihasilkan pada waktu kompilasi. Ini menghilangkan kebutuhan akan refleksi dan dapat meningkatkan kinerja fungsi Anda. Untuk menggunakan serialisasi yang dihasilkan sumber dalam fungsi Anda, Anda harus melakukan hal berikut:

Contoh berikut menunjukkan bagaimana Anda dapat memodifikasi contoh utama pada halaman ini, yang menggunakan serialisasi berbasis refleksi, untuk menggunakan serialisasi yang dihasilkan sumber sebagai gantinya.

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);
    
    ...
    
    }

}

Serialisasi yang dihasilkan sumber membutuhkan lebih banyak pengaturan daripada serialisasi berbasis refleksi. Namun, fungsi yang menggunakan sumber yang dihasilkan cenderung menggunakan lebih sedikit memori dan memiliki kinerja yang lebih baik karena pembuatan kode waktu kompilasi. Untuk membantu menghilangkan fungsi cold start, pertimbangkan untuk beralih ke serialisasi yang dihasilkan sumber.

Mengakses dan menggunakan objek konteks Lambda

Objek konteks Lambda berisi informasi tentang lingkungan pemanggilan, fungsi, dan eksekusi. Dalam contoh ini, objek konteks bertipeAmazon.Lambda.Core.ILambdaContext, dan merupakan argumen kedua dari fungsi pengendali utama.

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

Objek konteks adalah input opsional. Untuk informasi selengkapnya tentang tanda tangan handler yang diterima valid, lihat. Tanda tangan handler yang valid untuk fungsi C #

Objek konteks berguna untuk memproduksi log fungsi ke Amazon CloudWatch. Anda dapat menggunakan context.getLogger() metode ini untuk mendapatkan LambdaLogger objek untuk logging. Dalam contoh ini, kita dapat menggunakan logger untuk mencatat pesan kesalahan jika pemrosesan gagal karena alasan apa pun:

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

Di luar logging, Anda juga dapat menggunakan objek konteks untuk pemantauan fungsi. Untuk informasi selengkapnya tentang objek konteks, lihatMenggunakan objek konteks Lambda untuk mengambil informasi fungsi C #.

Menggunakan SDK untuk .NET v3 di handler Anda

Seringkali, Anda akan menggunakan fungsi Lambda untuk berinteraksi dengan atau membuat pembaruan ke sumber daya lain AWS . Cara paling sederhana untuk berinteraksi dengan sumber daya ini adalah dengan menggunakan SDK untuk .NET v3.

Anda dapat menambahkan dependensi SDK ke project menggunakan perintah berikut: Amazon.Lambda.Tools

dotnet add package <package_name>

Misalnya, dalam contoh utama di halaman ini, kita perlu menggunakan Amazon S3 API untuk mengunggah tanda terima ke S3. Kami dapat mengimpor klien SDK Amazon S3 dengan perintah berikut:

dotnet add package AWSSDK.S3

Perintah ini menambahkan ketergantungan ke proyek Anda. Anda juga harus melihat baris yang mirip dengan yang berikut di .csproj file proyek Anda:

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

Kemudian, impor dependensi langsung di kode C# Anda:

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

Kode contoh kemudian menginisialisasi klien Amazon S3 (menggunakan rantai penyedia kredensi default) sebagai berikut:

private static readonly AmazonS3Client s3Client = new();

Dalam contoh ini, kami menginisialisasi klien Amazon S3 kami di luar fungsi pengendali utama untuk menghindari keharusan menginisialisasi setiap kali kami menjalankan fungsi kami. Setelah menginisialisasi klien SDK, Anda dapat menggunakannya untuk berinteraksi dengan layanan lain AWS . Kode contoh memanggil Amazon S3 PutObject API sebagai berikut:

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

await s3Client.PutObjectAsync(putRequest);

Mengakses variabel lingkungan

Dalam kode handler Anda, Anda dapat mereferensikan variabel lingkungan apa pun dengan menggunakan System.Environment.GetEnvironmentVariable metode ini. Dalam contoh ini, kami mereferensikan variabel RECEIPT_BUCKET lingkungan yang ditentukan menggunakan baris kode berikut:

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

Menggunakan status global

Lambda menjalankan kode statis Anda dan konstruktor kelas selama fase inisialisasi sebelum menjalankan fungsi Anda untuk pertama kalinya. Sumber daya yang dibuat selama inisialisasi tetap berada di memori di antara pemanggilan, sehingga Anda dapat menghindari keharusan membuatnya setiap kali Anda menjalankan fungsi Anda.

Dalam kode contoh, kode inisialisasi klien S3 berada di luar metode handler utama. Runtime menginisialisasi klien sebelum fungsi menangani peristiwa pertamanya, yang dapat menyebabkan waktu pemrosesan lebih lama. Peristiwa selanjutnya jauh lebih cepat karena Lambda tidak perlu menginisialisasi klien lagi.

Sederhanakan kode fungsi dengan kerangka kerja Anotasi Lambda

Anotasi Lambda adalah kerangka kerja untuk.NET 8 yang menyederhanakan penulisan fungsi Lambda menggunakan C #. Kerangka kerja Anotasi menggunakan generator sumber untuk menghasilkan kode yang diterjemahkan dari model pemrograman Lambda ke kode yang disederhanakan. Dengan kerangka kerja Anotasi, Anda dapat mengganti banyak kode dalam fungsi Lambda yang ditulis menggunakan model pemrograman biasa. Kode yang ditulis menggunakan kerangka kerja menggunakan ekspresi sederhana yang memungkinkan Anda untuk fokus pada logika bisnis Anda. Lihat Amazon.Lambda.Annotations di dokumentasi nuget untuk contoh.

Untuk contoh aplikasi lengkap yang menggunakan Anotasi Lambda, lihat contoh PhotoAssetManagerdi repositori. awsdocs/aws-doc-sdk-examples GitHub Function.csFile utama dalam PamApiAnnotations direktori menggunakan Anotasi Lambda. Sebagai perbandingan, PamApi direktori memiliki file setara yang ditulis menggunakan model pemrograman Lambda biasa.

Injeksi ketergantungan dengan kerangka kerja Anotasi Lambda

Anda juga dapat menggunakan kerangka kerja Anotasi Lambda untuk menambahkan injeksi ketergantungan ke fungsi Lambda Anda menggunakan sintaks yang Anda kenal. Saat Anda menambahkan [LambdaStartup] atribut ke Startup.cs file, kerangka kerja Anotasi Lambda akan menghasilkan kode yang diperlukan pada waktu kompilasi.

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

Fungsi Lambda Anda dapat menyuntikkan layanan menggunakan injeksi konstruktor atau dengan menyuntikkan ke dalam metode individual menggunakan atribut. [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);
    }
}

Praktik terbaik kode untuk fungsi C# Lambda

Patuhi pedoman dalam daftar berikut untuk menggunakan praktik pengkodean terbaik saat membangun fungsi Lambda Anda: