Use C# handlers to respond to events and execute business code - Function Compute

Un handler C# est la méthode appelée par Function Compute lors de l'invocation d'une fonction. Cette rubrique explique le format de la chaîne du handler, les signatures de méthode valides, les types de handlers pris en charge (stream et POCO), les options de sérialisation et la gestion des invocations par déclencheur HTTP.

Remarque

Pour accéder aux fonctions via des déclencheurs HTTP ou des noms de domaine personnalisés, récupérez la structure de requête avant de définir les réponses HTTP. Pour plus d'informations, consultez Utiliser un déclencheur HTTP pour invoquer une fonction.

Format de la chaîne du handler

Les chaînes de handler C# respectent le format suivant :

Assembly::Namespace.ClassName::MethodName

Paramètre	Description
`Assembly`	Nom de l'assembly
`Namespace`	Nom du namespace
`ClassName`	Nom de la classe
`MethodName`	Nom de la méthode

Par exemple, si l'assembly s'appelle HelloFcApp, le handler est HelloFcApp::Example.HelloFC::StreamHandler.

Configurez la chaîne du handler lors de la création ou de la mise à jour d'une fonction dans la console Function Compute. Pour plus d'informations, consultez Créer une fonction événementielle.

Signatures de handler valides

Une méthode de handler peut être statique ou d'instance. Toutes les signatures prises en charge sont répertoriées ci-dessous. Le paramètre IFcContext est facultatif dans tous les cas.

// Synchronous signatures
ReturnType HandlerName(InputType input, IFcContext context);
ReturnType HandlerName(InputType input);

// Asynchronous signatures
async Task<ReturnType> HandlerName(InputType input, IFcContext context);
async Task<ReturnType> HandlerName(InputType input);

Function Compute attend la fin des méthodes asynchrones avant de retourner un résultat.

Types de paramètres :

Paramètre	Types acceptés
`ReturnType`	`void`, `System.IO.Stream` ou tout objet sérialisable en JSON. Une valeur de retour de type `Stream` est écrite directement dans le corps de la réponse ; les autres types sont d'abord sérialisés en JSON.
`InputType`	`System.IO.Stream` ou tout objet désérialisable depuis du JSON
`IFcContext`	Objet de contexte de la fonction. Pour plus d'informations, consultez Contexte.

Handlers d'événements

Les handlers d'événements C# nécessitent le package NuGet Aliyun.Serverless.Core (version 1.0.1). Ajoutez-le à votre fichier .csproj :

<ItemGroup>
  <PackageReference Include="Aliyun.Serverless.Core" Version="1.0.1" />
</ItemGroup>

Ce package fournit deux types de handlers :

Handler Stream : reçoit les données d'événement brutes sous forme de flux et écrit les résultats dans un flux de sortie.
Handler POCO : utilise des objets de classe simples (POCO) pour des entrées et sorties typées, avec une sérialisation JSON automatique.

Handler Stream

Un handler Stream lit les entrées depuis un Stream et retourne un Stream.

using System.IO;
using System.Threading.Tasks;
using Aliyun.Serverless.Core;
using Microsoft.Extensions.Logging;

namespace Example
{
    public class Hello
    {
        public async Task<Stream> StreamHandler(Stream input, IFcContext context)
        {
            IFcLogger logger = context.Logger;
            logger.LogInformation("Handle request: {0}", context.RequestId);
            MemoryStream copy = new MemoryStream();
            await input.CopyToAsync(copy);
            copy.Seek(0, SeekOrigin.Begin);
            return copy;
        }

        static void Main(string[] args){}
    }
}

Pour l'assembly HelloFcApp, la chaîne du handler correspondant à cet exemple est :

HelloFcApp::Example.Hello::StreamHandler

Éléments clés :

Élément	Description
`Stream input`	Données d'événement d'entrée. Lisez ce flux dans votre handler.
`IFcContext context`	(Facultatif) Objet de contexte fournissant les métadonnées de la requête et les capacités de journalisation.
`Task<Stream>`	Type de retour. Le contenu du flux est écrit directement dans le corps de la réponse.

Handler POCO

Un handler POCO exploite des classes C# typées pour les entrées et les sorties. Function Compute sérialise et désérialise automatiquement ces objets à l'aide de JSON.Net (Newtonsoft.Json).

using Aliyun.Serverless.Core;
using Microsoft.Extensions.Logging;

namespace Example
{
    public class Hello
    {
        public class Product
        {
            public string Id { get; set; }
            public string Description { get; set; }
        }

        // Optional: specify a custom serializer class.
        // If omitted, the default JSON.Net serializer is used.
        // [FcSerializer(typeof(MySerialization))]
        public Product PocoHandler(Product product, IFcContext context)
        {
            string Id = product.Id;
            string Description = product.Description;
            context.Logger.LogInformation("Id {0}, Description {1}", Id, Description);
            return product;
        }

        static void Main(string[] args){}
    }
}

Pour l'assembly HelloFcApp, la chaîne du handler correspondant à cet exemple est :

HelloFcApp::Example.Hello::PocoHandler

Éléments clés :

Élément	Description
`Product product`	Paramètre d'entrée de type `Product`. Désérialisé à partir de la charge utile de l'événement via JSON.Net.
`IFcContext context`	(Facultatif) Objet de contexte.
`Product` (type de retour)	Sortie sérialisée en JSON via JSON.Net et écrite dans le corps de la réponse.

Sérialisation

Les handlers POCO utilisent JSON.Net (Newtonsoft.Json) par défaut, fourni par Aliyun.Serverless.Core. Cela couvre la plupart des cas d'usage sans configuration supplémentaire : Function Compute désérialise automatiquement l'événement entrant vers votre type d'entrée et sérialise la valeur de retour dans le corps de la réponse.

Quand utiliser un sérialiseur personnalisé : si vous devez gérer des types spéciaux, des conventions de nommage personnalisées ou des formats non JSON, implémentez l'interface IFcSerializer :

public interface IFcSerializer
{
    T Deserialize<T>(Stream requestStream);
    void Serialize<T>(T response, Stream responseStream);
}

Pour utiliser un sérialiseur personnalisé, appliquez l'attribut [FcSerializer] à votre méthode de handler :

[FcSerializer(typeof(MySerialization))]
public Product PocoHandler(Product product, IFcContext context) { ... }

Utiliser un déclencheur HTTP pour invoquer une fonction

Exemple de code

L'exemple suivant définit des classes typées pour la requête et la réponse d'un déclencheur HTTP, lit le corps de la requête et le renvoie tel quel.

using System;
using System.Collections.Generic;
using System.Text;
using System.Text.Json;
using Aliyun.Serverless.Core;
using Microsoft.Extensions.Logging;

namespace Example
{
    public class Hello
    {
        public class HTTPTriggerEvent
        {
            public string Version { get; set; }
            public string RawPath { get; set; }
            public string Body { get; set; }
            public bool IsBase64Encoded { get; set; }
            public RequestContext RequestContext { get; set; }
            public Dictionary<string, string> Headers { get; set; }
            public Dictionary<string, string> QueryParameters { get; set; }

            public override string ToString()
            {
                return JsonSerializer.Serialize(this);
            }
        }

        public class RequestContext
        {
            public string AccountId { get; set; }
            public string DomainName { get; set; }
            public string DomainPrefix { get; set; }
            public string RequestId { get; set; }
            public string Time { get; set; }
            public string TimeEpoch { get; set; }
            public Dictionary<string, string> Http { get; set; }
        }

        public class HTTPTriggerResponse
        {
            public int StatusCode { get; set; }
            public Dictionary<string, string> Headers { get; set; }
            public bool IsBase64Encoded { get; set; }
            public string Body { get; set; }
        }

        public HTTPTriggerResponse PocoHandler(HTTPTriggerEvent input, IFcContext context)
        {
            context.Logger.LogInformation("receive event: {0}", input.ToString());
            string requestBody = input.Body;
            if (input.IsBase64Encoded)
            {
                byte[] decodedBytes = Convert.FromBase64String(input.Body);
                requestBody = Encoding.UTF8.GetString(decodedBytes);
            }
            return new HTTPTriggerResponse
            {
                StatusCode = 200,
                IsBase64Encoded = false,
                Body = requestBody
            };
        }
        static void Main(string[] args){}
    }
}

Prérequis

Avant de commencer, assurez-vous d'avoir :

Créé une fonction C# à l'aide de l'exemple de code ci-dessus. Pour plus d'informations, consultez Créer une fonction événementielle et Configurer un déclencheur HTTP

Invoquer la fonction

Connectez-vous à la console Function Compute. Dans le volet de navigation de gauche, cliquez sur Functions.
Dans la barre de navigation supérieure, sélectionnez une région. Sur la page Functions, cliquez sur la fonction cible.
Sur la page de détails de la fonction, cliquez sur l'onglet Triggers pour obtenir l'endpoint public du déclencheur HTTP.
Exécutez la commande suivante pour invoquer la fonction. Remplacez https://test-python-ipgrwr****.cn-shanghai.fcapp.run par votre endpoint.
```
curl -i "https://test-python-ipgrwr****.cn-shanghai.fcapp.run" -d 'Hello fc3.0'
```
Réponse attendue :
```
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Length: 12
Content-Type: application/json
X-Fc-Request-Id: 1-64f7449a-127fbe39cd7681596e33ebad
Date: Tue, 05 Sep 2023 15:09:14 GMT

Hello fc3.0
```
Important
- Si le paramètre Authentication Method est défini sur No Authentication, invoquez la fonction avec Postman ou curl.
- Si le paramètre Authentication Method est défini sur Signature Authentication ou JWT Authentication, utilisez la méthode correspondante. Pour plus d'informations, consultez Authentification.

Erreurs possibles

Cet exemple est conçu pour une invocation par déclencheur HTTP ou nom de domaine personnalisé. Si vous cliquez sur Test Function dans la console et transmettez une chaîne simple telle que "Hello, FC!", la fonction retourne une erreur de désérialisation car l'entrée ne correspond pas au format HTTPTriggerEvent :

{
    "errorMessage": "Unexpected character encountered while parsing value: H. Path '', line 0, position 0.",
    "errorType": "Newtonsoft.Json.JsonReaderException",
    "stackTrace": [
        "   at Newtonsoft.Json.JsonTextReader.ParseValue()",
        "   at Newtonsoft.Json.JsonReader.ReadAndMoveToContent()",
        "   at Newtonsoft.Json.JsonReader.ReadForType(JsonContract contract, Boolean hasConverter)",
        "   at Newtonsoft.Json.Serialization.JsonSerializerInternalReader.Deserialize(JsonReader reader, Type objectType, Boolean checkAdditionalContent)",
        "   at Newtonsoft.Json.JsonSerializer.DeserializeInternal(JsonReader reader, Type objectType)",
        "   at Newtonsoft.Json.JsonSerializer.Deserialize(JsonReader reader, Type objectType)",
        "   at Newtonsoft.Json.JsonSerializer.Deserialize[T](JsonReader reader)",
        "   at Aliyun.Serverless.Core.JsonSerializer.Deserialize[T](Stream requestStream) in /dotnetcore/Libraries/src/Aliyun.Serverless.Core.Impl/JsonSerializer.cs:line 95"
    ]
}

Programmes d'exemple

Les dépôts GitHub suivants contiennent des exemples complets avec des scripts de build et de déploiement :

dotnet3-blank-stream-event : rappels d'événements utilisant le format de handler Stream
dotnet3-blank-poco-event : rappels d'événements utilisant le format de handler POCO