Definire l'handler della funzione Lambda in C#

Il gestore di funzioni Lambda è il metodo nel codice della funzione che elabora gli eventi. Quando viene richiamata la funzione, Lambda esegue il metodo del gestore. La funzione viene eseguita fino a quando il gestore non restituisce una risposta, termina o scade.

Questa pagina descrive come lavorare con i gestori di funzioni Lambda in C# per operare con il runtime gestito da .NET, incluse le opzioni per la configurazione del progetto, le convenzioni di denominazione e le best practice. Questa pagina include anche un esempio di funzione Lambda C# che raccoglie informazioni su un ordine, produce una ricevuta in un file di testo e inserisce questo file in un bucket Amazon Simple Storage Service (S3). Per informazioni su come distribuire una funzione dopo averla scritta, consulta o. Crea e implementa le funzioni Lambda C# con gli archivi di file .zip Distribuzione delle funzioni .NET Lambda con immagini di container

Configurazione del progetto del gestore C#

Quando lavori con le funzioni Lambda in C#, il processo prevede la scrittura del codice, quindi l’implementazione del codice in Lambda. Esistono due diversi modelli di esecuzione per l’implementazione delle funzioni Lambda in .NET: l'approccio della libreria di classi e l'approccio dell'assembly eseguibile.

Quando segui l'approccio della libreria di classi, impacchetti il codice della funzione come assembly .NET (.dll) e lo implementi in Lambda con il runtime gestito da .NET (dotnet8). Per il nome del gestore, Lambda si aspetta una stringa nel formato AssemblyName::Namespace.Classname::Methodname. Durante la fase di inizializzazione della funzione, la classe della funzione viene inizializzata e viene eseguito qualsiasi codice nel costruttore.

Quando segui l'approccio dell'assembly eseguibile, utilizzi la funzionalità delle istruzioni di primo livello introdotta per la prima volta in C# 9. Questo approccio genera un assembly eseguibile che Lambda esegue ogni volta che riceve un comando invoke per la tua funzione. Con questo approccio, utilizzi anche il runtime gestito da .NET (dotnet8). Per il nome del gestore, fornisci a Lambda il nome dell'assembly eseguibile da eseguire.

L'esempio principale in questa pagina illustra l'approccio delle librerie di classi. Puoi inizializzare il progetto C# Lambda in vari modi, ma il modo più semplice è utilizzare l'interfaccia CLI .NET con la CLI Amazon.Lambda.Tools. Configura la CLI Amazon.Lambda.Tools seguendo i passaggi indicati in Configurazione dell'ambiente di sviluppo .NET. Quindi, inizializza il progetto con il seguente comando.

dotnet new lambda.EmptyFunction --name ExampleCS

Questo comando genera la seguente struttura di file:

/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 

In questa struttura di file, la logica del gestore principale per la funzione risiede nel file Function.cs.

Esempio di codice della funzione Lambda C#

Il seguente esempio di codice della funzione Lambda C# raccoglie le informazioni su un ordine, produce una ricevuta in un file di testo e inserisce questo file in un 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);
        }
    }
}

Questo file Function.cs contiene le sezioni seguenti:

Poiché questa funzione richiede un client SDK Amazon S3, devi aggiungerlo alle dipendenze del progetto. Puoi farlo andando in src/ExampleCS e impartendo il comando seguente:

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

Affinché questa funzione funzioni correttamente, il suo ruolo di esecuzione deve consentire l's3:PutObjectazione. Inoltre, assicuratevi di definire la variabile di RECEIPT_BUCKET ambiente. Dopo una chiamata riuscita, il bucket Amazon S3 dovrebbe contenere un file di ricevuta.

Gestori di librerie di classi

Il codice di esempio principale in questa pagina illustra un gestore di librerie di classi. I gestori di librerie di classi hanno la seguente struttura:

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

namespace NAMESPACE;

...

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

Quando crei una funzione Lambda, devi fornire a Lambda informazioni sul gestore della funzione sotto forma di stringa nel campo Gestore. Questo indica a Lambda quale metodo del codice eseguire quando la funzione viene richiamata. In C#, per i gestori di librerie di classi, il formato della stringa del gestore è ASSEMBLY::TYPE::METHOD, dove:

Per il codice di esempio principale, se l'assembly è denominato ExampleCS, la stringa completa del gestore è ExampleCS::ExampleLambda.OrderHandler::HandleRequest.

Gestori di assembly eseguibili

È inoltre possibile definire le funzioni Lambda in C# come assembly eseguibile. I gestori di assembly eseguibili utilizzano la funzionalità delle istruzioni di primo livello di C#, in cui il compilatore genera il metodo Main() e inserisce il codice della funzione al suo interno. Quando si utilizzano assembly eseguibili, è necessario avviare il runtime Lambda. Per far ciò, utilizza il metodo LambdaBootstrapBuilder.Create nel codice. Gli input per questo metodo sono la funzione del gestore principale e il serializzatore Lambda da utilizzare. Di seguito viene illustrato un esempio di gestore di assembly eseguibile in 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)
    };
};

Nel campo Gestore per i gestori di assembly eseguibili, la stringa del gestore che indica a Lambda come eseguire il codice è il nome dell'assembly. In questo esempio è GetProductHandler.

Firme del gestore valide per le funzioni C#

In C#, le firme del gestore Lambda valide richiedono da 0 a 2 argomenti. In genere, la firma del gestore ha due argomenti, come mostrato nell'esempio principale:

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

Quando si forniscono due argomenti, il primo argomento deve essere l'input dell'evento e il secondo deve essere l'oggetto del contesto Lambda. Entrambi gli argomenti sono facoltativi. Ad esempio, le seguenti sono anche firme valide di gestori Lambda in C#:

Oltre alla sintassi di base della firma del gestore, esistono alcune restrizioni aggiuntive:

Convenzioni di denominazione dei gestori

I gestori Lambda in C# non hanno restrizioni di denominazione rigide. Tuttavia, devi assicurarti di fornire la stringa del gestore corretta a Lambda quando implementi la funzione. La stringa del gestore corretta dipende da se stai implementando un gestore di libreria di classi o un gestore di assembly eseguibile.

Sebbene tu possa utilizzare qualsiasi nome per il gestore, i nomi delle funzioni in C# sono generalmente in PascalCase. Inoltre, sebbene non sia necessario che il nome del file corrisponda al nome della classe o del gestore, in genere è consigliabile utilizzare un nome di file come OrderHandler.cs se il nome della classe è OrderHandler. Ad esempio, è possibile modificare il nome del file in questo esempio da Function.cs a OrderHandler.cs.

Serializzazione nelle funzioni Lambda C#

JSON è il formato di input più comune e standard per le funzioni Lambda. In questo esempio, la funzione prevede un input simile a quanto segue:

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

In C#, puoi definire la forma dell'evento di input previsto in una classe. In questo esempio, definiamo la classe Order per modellare questo input:

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

Se la funzione Lambda utilizza i tipi di input/output diversi da un oggetto Stream, è necessario aggiungere una libreria di serializzazione all'applicazione. Ciò ti consente di convertire l'input JSON in un'istanza della classe definita. Esistono due metodi di serializzazione per le funzioni C# in Lambda: serializzazione basata sulla riflessione e serializzazione generata dal codice sorgente.

Serializzazione basata sulla riflessione

AWS fornisce librerie predefinite che puoi aggiungere rapidamente all'applicazione. Queste librerie implementano la serializzazione utilizzando la riflessione. Utilizza uno dei seguenti pacchetti per implementare la serializzazione basata sulla riflessione:

È possibile inoltre creare una libreria di serializzazione personalizzata implementando l'interfaccia ILambdaSerializer, disponibile come parte della libreria Amazon.Lambda.Core. L'interfaccia definisce due metodi:

L'esempio principale in questa pagina utilizza la serializzazione basata sulla riflessione. La serializzazione basata sulla riflessione funziona immediatamente con AWS Lambda e non richiede alcuna configurazione aggiuntiva, il che la rende una buona scelta in termini di semplicità. Tuttavia, richiede un maggiore utilizzo della memoria funzionale. È inoltre possibile che si verifichino latenze di funzioni più elevate a causa della riflessione del runtime.

Serializzazione generata dal codice sorgente

Con la serializzazione generata dal codice sorgente, il codice di serializzazione viene generato in fase di compilazione. Ciò elimina la necessità di riflessione e può migliorare le prestazioni della tua funzione. Per utilizzare la serializzazione generata dal codice sorgente nella tua funzione, devi procedere come indicato di seguito:

L'esempio seguente mostra come puoi modificare l'esempio principale di questa pagina, che utilizza la serializzazione basata sulla riflessione, in modo da utilizzare invece la serializzazione generata dal codice sorgente.

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

}

La serializzazione generata dal codice sorgente richiede più impostazioni rispetto alla serializzazione basata sulla riflessione. Tuttavia, le funzioni che utilizzano la generazione da codice sorgente tendono a utilizzare meno memoria e offrono prestazioni migliori grazie alla generazione di codice in fase di compilazione. Per contribuire a eliminare gli avvii a freddo delle funzioni, prendi in considerazione la possibilità di passare alla serializzazione generata dal codice sorgente.

Accesso e utilizzo dell'oggetto contestuale Lambda

L'oggetto contesto: contiene informazioni sulla chiamata, sulla funzione e sull'ambiente di esecuzione. In questo esempio, l'oggetto contesto è di tipo Amazon.Lambda.Core.ILambdaContext ed è il secondo argomento della funzione del gestore principale.

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

L'oggetto contesto è un input opzionale. Per ulteriori informazioni sulle firme valide accettate del gestore, consulta Firme del gestore valide per le funzioni C#.

L'oggetto contesto è utile per produrre log di funzioni su Amazon CloudWatch. Puoi usare il metodo context.getLogger() per ottenere un oggetto LambdaLogger per la registrazione. In questo esempio, possiamo usare il logger per registrare il log di un messaggio di errore se l'elaborazione fallisce per qualche motivo:

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

Oltre alla registrazione di log, puoi anche utilizzare l'oggetto contesto per il monitoraggio delle funzioni. Per ulteriori informazioni sulla copia di oggetti, consulta la sezione Utilizzo dell'oggetto del contesto Lambda per recuperare le informazioni sulla funzione C#.

Utilizzo della SDK per .NET versione v3 nell'handler

Spesso, utilizzerai le funzioni Lambda per interagire o aggiornare altre AWS risorse. Il modo più semplice per interfacciarsi con queste risorse è usare la SDK per .NET v3.

Puoi aggiungere dipendenze SDK al tuo progetto usando il comando Amazon.Lambda.Tools seguente:

dotnet add package <package_name>

Ad esempio, nell'esempio principale di questa pagina, è necessario utilizzare l'API Amazon S3 per caricare una ricevuta su S3. Possiamo importare il client SDK Amazon S3 con il seguente comando:

dotnet add package AWSSDK.S3

Questo comando aggiunge la dipendenza al tuo progetto. Dovresti anche vedere una riga simile alla seguente nel file .csproj del tuo progetto:

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

Quindi, importa le dipendenze direttamente nel tuo codice C#:

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

Il codice di esempio inizializza quindi un client Amazon S3 (utilizzando la catena di provider delle credenziali predefinita) come indicato di seguito:

private static readonly AmazonS3Client s3Client = new();

In questo esempio, abbiamo inizializzato il nostro client Amazon S3 all’esterno della funzione del gestore principale per evitare di doverlo inizializzare ogni volta che invochiamo la nostra funzione. Dopo aver inizializzato il client SDK, puoi utilizzarlo per interagire con altri servizi AWS. Il codice di esempio richiama l'PutObjectAPI Amazon S3 nel modo seguente:

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

await s3Client.PutObjectAsync(putRequest);

Accesso alle variabili d'ambiente

Nel codice dell'handler, puoi fare riferimento a qualsiasi variabile di ambiente utilizzando il metodo System.Environment.GetEnvironmentVariable. In questo esempio, facciamo riferimento alla variabile di ambiente RECEIPT_BUCKET definita utilizzando le seguenti righe di codice:

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

Utilizzo dello stato globale

Lambda esegue il codice statico e il costruttore della classe durante la fase di inizializzazione prima di richiamare la funzione per la prima volta. Le risorse create durante l'inizializzazione restano in memoria tra le invocazioni, in modo da evitare di doverle creare ogni volta che si invoca la funzione.

Nel codice di esempio, il codice di inizializzazione del client S3 non rientra nel metodo del gestore principale. Il runtime inizializza il client prima che la funzione gestisca il suo primo evento, il che può portare a tempi di elaborazione più lunghi. Gli eventi successivi sono molto più veloci perché Lambda non ha bisogno di inizializzare nuovamente il client.

Semplificazione del codice delle funzioni con il framework Lambda Annotations

Lambda Annotations è un framework per .NET 8 che semplifica la scrittura di funzioni Lambda utilizzando C#. Il framework Annotations utilizza generatori di codice sorgente per generare codice che si traduce dal modello di programmazione Lambda al codice semplificato. Con il framework Annotations, è possibile sostituire gran parte del codice in una funzione Lambda scritta utilizzando il normale modello di programmazione. Il codice scritto utilizzando il framework utilizza espressioni più semplici che consentono di concentrarsi sulla logica aziendale. Per alcuni esempi, consulta Amazon.Lambda.Annotations nella documentazione NuGet.

Per un esempio di applicazione completa che utilizza Lambda Annotations, consulta l'esempio PhotoAssetManager nel repository GitHub awsdocs/aws-doc-sdk-examples. Il file Function.cs principale nella directory PamApiAnnotations usa Lambda Annotations. Per fare un confronto, la directory PamApi contiene file equivalenti scritti utilizzando il normale modello di programmazione Lambda.

Iniezione delle dipendenze con il framework Lambda Annotations

Puoi utilizzare il framework Lambda Annotations anche per aggiungere l'iniezione di dipendenze alle tue funzioni Lambda utilizzando una sintassi che conosci. Quando aggiungi un attributo [LambdaStartup] a un file Startup.cs, il framework Lambda Annotations genererà il codice richiesto in fase di compilazione.

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

La tua funzione Lambda può iniettare servizi utilizzando l'iniezione del costruttore o iniettandoli in metodi individuali utilizzando l'attributo [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);
    }
}

Best practice di codice per le funzioni Lambda con C#

Segui le linee guida riportate nell'elenco seguente per utilizzare le best practice di codifica durante la creazione delle funzioni Lambda:

Sfruttare il riutilizzo del contesto di esecuzione per migliorare le prestazioni della funzione. Inizializzare i client SDK e le connessioni al database all'esterno del gestore di funzioni e memorizzare localmente nella cache gli asset statici nella directory /tmp. Le chiamate successive elaborate dalla stessa istanza della funzione possono riutilizzare queste risorse. Ciò consente di risparmiare sui costi riducendo i tempi di esecuzione delle funzioni.

Per evitare potenziali perdite di dati tra le chiamate, non utilizzare il contesto di esecuzione per archiviare dati utente, eventi o altre informazioni con implicazioni di sicurezza. Se la funzione si basa su uno stato mutabile che non può essere archiviato in memoria all'interno del gestore, considerare la possibilità di creare una funzione separata o versioni separate di una funzione per ogni utente.

Utilizzare una direttiva keep-alive per mantenere le connessioni persistenti. Lambda elimina le connessioni inattive nel tempo. Se si tenta di riutilizzare una connessione inattiva quando si richiama una funzione, si verificherà un errore di connessione. Per mantenere la connessione persistente, utilizzare la direttiva keep-alive associata al runtime. Per un esempio, vedere Riutilizzo delle connessioni con Keep-Alive in Node.js.

Utilizzare le variabili di ambiente per passare i parametri operativi alla funzione. Se ad esempio si scrive in un bucket Amazon S3 anziché impostare come hard-coded il nome del bucket in cui si esegue la scrittura, configurare tale nome come una variabile di ambiente.

Evita di usare invocazioni ricorsive nella tua funzione Lambda, in cui la funzione si richiama da sola o avvia un processo che potrebbe richiamare nuovamente la funzione. Ciò potrebbe provocare un volume non desiderato di invocazioni della funzione e un aumento dei costi. Se noti un volume indesiderato di invocazioni, imposta immediatamente la simultaneità riservata della funzione su 0 per interrompere tutte le invocazioni della funzione mentre si aggiorna il codice.

Non utilizzare API non documentate e non pubbliche nel codice della funzione Lambda. Per i tempi di esecuzione gestiti AWS Lambda, Lambda applica periodicamente aggiornamenti di sicurezza e funzionalità alle API interne di Lambda. Questi aggiornamenti API interni potrebbero essere incompatibili con le versioni precedenti, causando conseguenze indesiderate come errori di chiamata se la funzione ha una dipendenza su queste API non pubbliche. Consulta il riferimento all'API per un elenco di API disponibili pubblicamente.

Scrivi un codice idempotente. La scrittura di un codice idempotente per le tue funzioni garantisce che gli eventi duplicati vengano gestiti allo stesso modo. Il tuo codice dovrebbe convalidare correttamente gli eventi e gestire con garbo gli eventi duplicati. Per ulteriori informazioni, consulta Come posso rendere idempotente la mia funzione Lambda?.