C# handler

To use C# in Function Compute, you must first define a C# function as a handler. This topic describes the C# handlers that can be used and their definitions.

Overview

To easily handle HTTP requests, Function Compute supports the use of HTTP triggers to call C# functions. The HTTP triggered function is known as a handler with an HTTP trigger. Currently, the C# runtime (.NET Core 2.1) supports two types of handlers:

• Common handlers

  • Handler definition
  • Handler method example
  • Handler specification
  • Complete operation example of common handlers
  • Initializer handler

• Handlers with an HTTP trigger

  • Handler definition
  • Example of handlers with an HTTP trigger
  • Limits on handlers with an HTTP trigger

Common handlers

Handler definition

When creating a C# function, you must specify a handler method, which is executed along with the function. This handler method can be a static method or an instance method. To access the IFcContext object in this method, you can specify IFcContext object as the second parameter in this method. The supported handler methods are defined as follows:

ReturnType HandlerName(InputType input, IFcContext context);  // IFcContext included
ReturnType HandlerName(InputType input); // IFcContext not included
Async Task<ReturnType> HandlerName(InputType input, IFcContext context);
Async Task<ReturnType> HandlerName(InputType input);

Function Compute supports the use of Async in C#-written functions, where the execution of the function waits for the end of the asynchronous method execution.

In the preceding definition:

• ReturnType: the returned object, which can be void, a System.IO.Stream object, or any JSON-serialized or -deserialized object. When void is returned, Async Task degrades to async Task. When a Stream object is returned, the Stream content is included in the response body. Otherwise, the returned object is serialized in JSON and included in the response body.

• InputType: the input parameter, which can be System.IO.Stream or any JSON-serialized or -deserialized object.

• IFcContext: the context object of the function, which includes the following information.

more detail: fc-dotnet-libs

Handler method example

When you write functions in C# using Function Compute, the Aliyun.Serverless.Core package needs to be introduced through NuGet.

Stream Handler

The following method returns the user request input as it is.

using System.IO;
using System.Threading.Tasks;
using Aliyun.Serverless.Core;
using Microsoft.Extensions.Logging;
namespace FC.Examples
{
    public class TestHandler
    {
        public async Task<Stream> Echo(Stream input, IFcContext context)
        {
            ILogger 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;
        }
    }
}

POCO Handler

In addition to Stream objects, plain old CLR objects (POCOs) can also be used as input and output parameters. If a POCO does not specify a JSON serializer object, Function Compute uses Json.Net to serialize and deserialize objects in the JSON format by default.

using Microsoft.Extensions.Logging;
namespace FC.Examples
{
    public class TestHandler
    {
        public class Product
        {
            public string Id { get; set; }
            public string Description { get; set; }
        }
        // optional serializer class, if it’s not specified, the default serializer (based on JSON.Net) will be used.  
        // [FcSerializer(typeof(MySerialization))]  
        public Product Echo(Product product, IFcContext context)
        {
            string Id = product.Id;
            string Description = product.Description;
            context.Logger.LogInformation("Id {0}, Description {1}", Id, Description);
            return product;
        }
    }
}

Handler specification

Handler Signatures

When creating a function, you need to specify a handler method in the string format to tell Function Compute how to locate the method to be called. The string format is as follows:

AssemblyFileName::FullClassName::METHOD

where,

• AssemblyFileName is the file name of Assembly where the function is located (with .dll omitted).

• FullClassName is the full name of the class to which the function belongs, that is, Namespace.ClassName.

• Method is the name of the method to be called.

In the preceding Handler example, if the Assembly file name is test_assembly, then the handler string is as follows:

test_assembly::FC.Examples.TestHandler::Echo

Limits

• The Handler parameter format observes the preceding definition. That is, parameter 1 is required, whereas parameter 2 is optional, with the invariable value IFcContext.

• The Handler function does not support Generic Method.

• The input and output parameters must be Stream objects or can be serialized in the JSON format.

• The Async function returns Task, in which T must be Stream objects or of a class that can be serialized in the JSON format.

Custom Serializer

For POCO handlers, Function Compute provides the default JSON . NET serializer. If the default serializer does not meet requirements, a custom serializer can be implemented based on the interface IFcSerializer in Aliyun.Serverless.Core.

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

Complete operation example of common handlers

SecurityToken is used to verify the identity and permissions of a requester. You must specify SecurityToken when you access other Alibaba Cloud services, such as OSS. In the following C# sample code, SecurityToken is used to retrieve the specified object from an OSS bucket.

1. Create a .NET Core console project.

    [songluo@~/tmp]# mkdir fcdotnetsample
    [songluo@~/tmp]# cd fcdotnetsample
    [songluo@~/tmp/fcdotnetsample]# dotnet new console

2. Add the following packages to fcdotnetsample.csproj:

     <ItemGroup>
        <PackageReference Include="Aliyun.Serverless.Core" Version="1.0.1" />
        <PackageReference Include="Aliyun.OSS.SDK.NetCore" Version="2.9.1" />
     </ItemGroup>

3. Edit ‘Program.cs’.

    using System;
    using System.IO;
    using Aliyun.OSS;
    using Aliyun.Serverless.Core;
    namespace fcdotnetsample
    {
         class Program
        {
            static void Main(string[] args)
            {
                Console.WriteLine("Hello World!");
            }
        }
        public class OssFileHandlerRequest
        {
            public string Bucket;
            public string Key;
            public string Endpoint;
        }
        public class OSSFileHandler
        {
            public Stream GetOssFile(OssFileHandlerRequest req, IFcContext context)
            {
                if (req == null)
                {
                    throw new ArgumentNullException(nameof(req));
                }
                if (context == null || context.Credentials == null)
                {
                    throw new ArgumentNullException(nameof(context));
                }
                OssClient ossClient = new OssClient(req.Endpoint, context.Credentials.AccessKeyId, context.Credentials.AccessKeySecret, context.Credentials.SecurityToken);
                OssObject obj = ossClient.GetObject(req.Bucket, req.Key);
                return obj.Content;
            }
        }
    }

4. Publish the project and compress the target files into a .zip package.

    [songluo@~/tmp/fcdotnetsample]# dotnet publish -c Release
    Microsoft (R) Build Engine version 15.9.20+g88f5fadfbe for .NET Core
    Copyright (C) Microsoft Corporation. All rights reserved.
      Restore completed in 47.9 ms for /Users/songluo/tmp/fcdotnetsample/fcdotnetsample.csproj.
      fcdotnetsample -> /Users/songluo/tmp/fcdotnetsample/bin/Release/netcoreapp2.1/fcdotnetsample.dll
      fcdotnetsample -> /Users/songluo/tmp/fcdotnetsample/bin/Release/netcoreapp2.1/publish/
    [songluo@~/tmp/fcdotnetsample]# cd /Users/songluo/tmp/fcdotnetsample/bin/Release/netcoreapp2.1/publish/
    [songluo@~/tmp/fcdotnetsample/bin/Release/netcoreapp2.1/publish]# zip -r fcdotnetsample.zip *
      adding: Aliyun.OSS.Core.dll (deflated 60%)
      adding: Aliyun.Serverless.Core.dll (deflated 59%)
      adding: Microsoft.Extensions.Logging.Abstractions.dll (deflated 53%)
      adding: fcdotnetsample.deps.json (deflated 73%)
      adding: fcdotnetsample.dll (deflated 57%)
      adding: fcdotnetsample.pdb (deflated 27%)
      adding: fcdotnetsample.runtimeconfig.json (deflated 23%)
    [songluo@~/tmp/fcdotnetsample/bin/Release/netcoreapp2.1/publish]# ls -ll fcdotnetsample.zip
    -rw-r--r--  1 songluo  staff  130276 Mar 14 17:48 fcdotnetsample.zip

Use fcdotnetsample.zip to create a function with the runtime .NET Core 2.1 and the handler fcdotnetsample::fcdotnetsample.OSSFileHandler::GetOssFile.

Initializer handler

Function Compute provides the Init method for initialization. The Init method is automatically called when background containers are started. Each container is called only once.

Init method definition:

public void Init();   // No context objects
public void Init(IFcContext context); // Include context objects
public static void Init();   // No context objects
public static void Init(IFcContext context); // Include context objects

Initializer format

• MyInitializermust map the “initializer” field when the initializer function is added. For example, if fcdotnetsample::fcdotnetsample.TestHandler::MyInitializer is specified as the initializer handler when a function is created, Function Compute first loads the MyInitializer function defined in fcdotnetsample.TestHandler after initializer configuration.

Initializer features

• FunctionInitializer and InitializationTimeout in FunctionParam of IFcContext are designed for the initializer and are set to the user-predefined values when a function is created while the initializer is in use. Otherwise, they are empty and ineffective.
• No value is returned. The Return operation appended to the function is invalid.

Handlers with an HTTP trigger

A handler with an HTTP trigger is different from other trigger-required handlers and is defined as follows:

If you write a function with an HTTP trigger in C#, the Aliyun.Serverless.Core and Aliyun.Serverless.Core.Http packages need to be introduced through NuGet.

using System.Threading.Tasks;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Aliyun.Serverless.Core;
using Aliyun.Serverless.Core.Http;
namespace MySpace.TestHandlers
{
    public class SingleHttpHandler : FcHttpEntrypoint
    {
        protected override void Init(IWebHostBuilder builder)
        { }
        public override async Task<HttpResponse> HandleRequest(HttpRequest request, HttpResponse response, IFcContext fcContext)
        {
            response.StatusCode = 200;
            response.ContentType = "text/plain";
            await response.WriteAsync("hello world");
            return response;
        }
    }
}

Input parameters

• The IFcContext parameters are the same as the IFcContext parameters of common handlers.

• HttpRequest

• HttpResponse

Description

The C#-written functions with HTTP triggers must inherit FcHttpEntrypoint in Aliyun.Serverless.Core.Http. The Init function must be overridden. HandleRequest is a handler and can be overridden as needed.

• Single function: used to override HandleRequest, which is the logical processing of HandleRequest customization.

• Asp.net core application: Only the Init function is overridden.

The example in the following section shows how to use FcHttpEntrypoint.

Example of handlers with an HTTP trigger

Single function example

The following example shows how to use HttpRequest and HttpResponse of a handler with an HTTP trigger.

using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Aliyun.Serverless.Core;
using Aliyun.Serverless.Core.Http;
using Microsoft.Extensions.Logging;
namespace MySpace.TestHandlers
{
    public class SingleHttpHandler : FcHttpEntrypoint
    {
        protected override void Init(IWebHostBuilder builder)
        { 
        }
        public override async Task<HttpResponse> HandleRequest(HttpRequest request, HttpResponse response, IFcContext fcContext)
        {
            string method = request.Method;
            string relativePath = request.Path.Value;
            fcContext.Logger.LogInformation("method = {0}; requestPath = {1}", method, relativePath);
            StreamReader sr = new StreamReader(request.Body);
            string requestBody = sr.ReadToEnd();
            fcContext.Logger.LogInformation("requestBody = {}", requestBody);
            // process request.Headers
            response.StatusCode = 200;
            response.ContentType = "text/plain";
            response.Headers.Add("customheader", "v1");
            await response.WriteAsync("hello world");
            return response;
        }
    }
}

Example of Asp.net core application

using System;
using Aliyun.Serverless.Core.Http;
using Microsoft.AspNetCore.Hosting;
namespace MySpace.TestWebApi
{
    public class FcRemoteEntrypoint : FcHttpEntrypoint
    {
         protected override void Init(IWebHostBuilder builder)
        {
            builder
                .UseStartup<Startup>();
        }
    }
}

Procedure

1. Create a webapi project of asp.net core.

    [songluo@~/tmp]# mkdir fcaspdotnetsample
    [songluo@~/tmp]# cd fcaspdotnetsample
    [songluo@~/tmp/fcaspdotnetsample]# dotnet new webapi

2. Add the following package to fcaspdotnetsample.csproj:

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

3. Create a file named FcRemoteEntrypoint.cs that contains the sample code of Asp.net core application.

4. Publish the project and compress the target files into a .zip package.

    [songluo@~/tmp/fcaspdotnetsample]# dotnet publish -c Release
    Microsoft (R) Build Engine version 15.9.20+g88f5fadfbe for .NET Core
    Copyright (C) Microsoft Corporation. All rights reserved.
      Restore completed in 88.39 ms for /Users/songluo/tmp/fcaspdotnetsample/fcaspdotnetsample.csproj.
      fcaspdotnetsample -> /Users/songluo/tmp/fcaspdotnetsample/bin/Release/netcoreapp2.1/fcaspdotnetsample.dll
      fcaspdotnetsample -> /Users/songluo/tmp/fcaspdotnetsample/bin/Release/netcoreapp2.1/publish/
    [songluo@~/tmp/fcaspdotnetsample]# cd /Users/songluo/tmp/fcaspdotnetsample/bin/Release/netcoreapp2.1/publish/
    [songluo@~/tmp/fcaspdotnetsample/bin/Release/netcoreapp2.1/publish]#  zip -r fcaspdotnetsample.zip *
      adding: appsettings.Development.json (deflated 40%)
      adding: appsettings.json (deflated 30%)
      adding: fcaspdotnetsample.deps.json (deflated 85%)
      adding: fcaspdotnetsample.dll (deflated 61%)
      adding: fcaspdotnetsample.pdb (deflated 40%)
      adding: fcaspdotnetsample.runtimeconfig.json (deflated 31%)
      adding: web.config (deflated 40%)
    [songluo@~/tmp/fcaspdotnetsample/bin/Release/netcoreapp2.1/publish]#  ls -ll fcaspdotnetsample.zip
    -rw-r--r--  1 songluo  staff  39101 Mar 15 09:47 fcaspdotnetsample.zip

Use fcaspdotnetsample.zip to create a function with the runtime .NET Core 2.1 and the handler fcaspdotnetsample::MySpace.TestWebApi.FcRemoteEntrypoint::HandleRequest.

If the Single function is used, create a console project and FcRemoteEntrypoint.cs by following the instructions provided in Complete operation example of common handlers, and replace the code with the sample code of the Single function.

Limits on handlers with an HTTP trigger

Request limits

If the request for a handler with an HTTP trigger exceeds the following limits, the 400 status code and InvalidArgument error code are thrown.

Response limits

If the response for a handler with an HTTP trigger exceeds the following limits, the 502 status code and BadResponse error code are thrown.

For more information about HTTP triggers, see HTTP trigger.

Reference documents

For more information about the C# runtime, see C# runtime.