Skip to content

Commit 4c38fb6

Browse files
normjnormj
committed
Update README.md
1 parent 2b672f3 commit 4c38fb6

File tree

3 files changed

+79
-51
lines changed
  • Libraries/src

3 files changed

+79
-51
lines changed

‎Libraries/src/Amazon.Lambda.APIGatewayEvents/README.md‎

Lines changed: 6 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,13 @@ API Gateway events consist of a request that was routed to a Lambda function by
66

77
# Classes
88

9-
## APIGatewayProxyRequest
9+
|Class|Description|
10+
|-----|-----------|
11+
| [APIGatewayProxyRequest](./APIGatewayProxyRequest.cs) | Represents proxy request coming from REST API, HTTP API payload format 1.0 or WebSocket API. |
12+
| [APIGatewayProxyResponse](./APIGatewayProxyResponse.cs) | The return object for functions handling requests for REST API, HTTP API payload format 1.0 or WebSocket API. |
13+
| [APIGatewayHttpApiV2ProxyRequest](./APIGatewayHttpApiV2ProxyRequest.cs) | Represents proxy request coming from HTTP API payload format 2.0. |
14+
| [APIGatewayHttpApiV2ProxyResponse](./APIGatewayHttpApiV2ProxyResponse.cs) | The return object for functions handling requests for HTTP API payload format 2.0. |
1015

11-
The [APIGatewayProxyRequest](./APIGatewayProxyRequest.cs) class contains information relating to the proxy request coming from the [Amazon API Gateway](https://aws.amazon.com/api-gateway/).
1216

1317
# Sample Functions
1418

@@ -35,28 +39,3 @@ public class Function
3539
}
3640
```
3741

38-
### Microsoft.AspNetCore.Mvc controller
39-
40-
In a AspNetCore controller, An instance of this interface is attached to any `ControllerBase.Request.HttpContext` instances via the `Items` property using the key "[APIGATEWAY_REQUEST / APIGatewayRequest](../Amazon.Lambda.AspNetCoreServer/APIGatewayProxyFunction.cs)".
41-
42-
The following is an example of accessing an instance of this class in a controller method.
43-
44-
```csharp
45-
[ApiController]
46-
public class TestController : ControllerBase
47-
{
48-
[HttpGet("/[controller]")]
49-
public IActionResult Get()
50-
{
51-
Response.Headers.Add("Access-Control-Allow-Origin", "*"); // NOTE: Should be configured via app.UseCors in Startup.cs
52-
53-
var proxyRequest = (APIGatewayProxyRequest)Request.HttpContext.Items[APIGatewayProxyFunction.APIGATEWAY_REQUEST];
54-
var tmp = new
55-
{
56-
proxyRequest.RequestContext.RequestId,
57-
proxyRequest.RequestContext.Identity?.CognitoIdentityId
58-
};
59-
return new OkObjectResult(tmp);
60-
}
61-
}
62-
```

‎Libraries/src/Amazon.Lambda.AspNetCoreServer/README.md‎

Lines changed: 49 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,20 @@ or from an [Application Load Balancer](https://docs.aws.amazon.com/elasticloadba
88
and converts that request into the classes the ASP.NET Core framework expects and then converts the response from the ASP.NET Core
99
framework into the response body that API Gateway Proxy or Application Load Balancer understands.
1010

11-
## Example Lambda Function
11+
## Lambda Entry Point
1212

13-
In the ASP.NET Core application add a class that extends from [APIGatewayProxyFunction](../Amazon.Lambda.AspNetCoreServer/APIGatewayProxyFunction.cs)
14-
and implement the Init method.
13+
In the ASP.NET Core application add a class that will be the entry point for Lambda to call into the application. Commonly this class
14+
is called `LambdaEntryPoint`. The base class is determined based on where the Lambda functions will be invoked from.
15+
16+
|Lambda Involve| Base Class |
17+
|----------|---------------|
18+
| API Gateway REST API | APIGatewayProxyFunction |
19+
| API Gateway WebSocket API | APIGatewayProxyFunction |
20+
| API Gateway HTTP API Payload 1.0 | APIGatewayProxyFunction |
21+
| API Gateway HTTP API Payload 2.0 | APIGatewayHttpApiV2ProxyFunction |
22+
| Application Load Balancer | ApplicationLoadBalancerFunction |
23+
24+
**Note:** HTTP API default to payload 2.0 so unless 1.0 is explicitly set the base class should be APIGatewayHttpApiV2ProxyFunction.
1525

1626
Here is an example implementation of the Lamba function in an ASP.NET Core Web API application.
1727
```csharp
@@ -22,8 +32,32 @@ using Microsoft.AspNetCore.Hosting;
2232

2333
namespace TestWebApp
2434
{
25-
public class LambdaFunction : APIGatewayProxyFunction
35+
/// <summary>
36+
/// This class extends from APIGatewayProxyFunction which contains the method FunctionHandlerAsync which is the
37+
/// actual Lambda function entry point. The Lambda handler field should be set to
38+
///
39+
/// AWSServerless19::AWSServerless19.LambdaEntryPoint::FunctionHandlerAsync
40+
/// </summary>
41+
public class LambdaEntryPoint :
42+
43+
// The base class must be set to match the AWS service invoking the Lambda function. If not Amazon.Lambda.AspNetCoreServer
44+
// will fail to convert the incoming request correctly into a valid ASP.NET Core request.
45+
//
46+
// API Gateway REST API -> Amazon.Lambda.AspNetCoreServer.APIGatewayProxyFunction
47+
// API Gateway HTTP API payload version 1.0 -> Amazon.Lambda.AspNetCoreServer.APIGatewayProxyFunction
48+
// API Gateway HTTP API payload version 2.0 -> Amazon.Lambda.AspNetCoreServer.APIGatewayHttpApiV2ProxyFunction
49+
// Application Load Balancer -> Amazon.Lambda.AspNetCoreServer.ApplicationLoadBalancerFunction
50+
//
51+
// Note: When using the AWS::Serverless::Function resource with an event type of "HttpApi" then payload version 2.0
52+
// will be the default and you must make Amazon.Lambda.AspNetCoreServer.APIGatewayHttpApiV2ProxyFunction the base class.
53+
54+
Amazon.Lambda.AspNetCoreServer.APIGatewayProxyFunction
2655
{
56+
/// <summary>
57+
/// The builder has configuration, logging and Amazon API Gateway already configured. The startup class
58+
/// needs to be configured in this method using the UseStartup<>() method.
59+
/// </summary>
60+
/// <param name="builder"></param>
2761
protected override void Init(IWebHostBuilder builder)
2862
{
2963
builder
@@ -35,31 +69,22 @@ namespace TestWebApp
3569

3670
The function handler for the Lambda function will be **TestWebApp::TestWebApp.LambdaFunction::FunctionHandlerAsync**.
3771

38-
Once the function is deployed configure API Gateway with a HTTP Proxy to call the Lambda Function. Refer to the API Gateway
39-
[developer guide](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-create-api-as-simple-proxy.html) for more information.
4072

41-
### Application Load Balancer Example
73+
## Access to Lambda Objects from HttpContext
4274

43-
To be used with an Application Load Balancer from ELB the base class needs to be changed from APIGatewayProxyFunction to **ApplicationLoadBalancerFunction**.
75+
The original lambda request object and the `ILambdaContext` object can be accessed from the `HttpContext.Items` collection.
4476

45-
```csharp
46-
using System.IO;
77+
| Constant | Object |
78+
|-------|--------|
79+
| AbstractAspNetCoreFunction.LAMBDA_CONTEXT | ILambdaContext |
80+
| AbstractAspNetCoreFunction.LAMBDA_REQUEST_OBJECT | <ul><li>APIGatewayProxyFunction -> APIGatewayProxyRequest</li><li>APIGatewayHttpApiV2ProxyFunction -> APIGatewayHttpApiV2ProxyRequest</li><li>ApplicationLoadBalancerFunction -> ApplicationLoadBalancerRequest</li></ul> |
4781

48-
using Amazon.Lambda.AspNetCoreServer;
49-
using Microsoft.AspNetCore.Hosting;
5082

51-
namespace TestWebApp
52-
{
53-
public class LambdaFunction : ApplicationLoadBalancerFunction
54-
{
55-
protected override void Init(IWebHostBuilder builder)
56-
{
57-
builder
58-
.UseStartup<Startup>();
59-
}
60-
}
61-
}
62-
```
83+
## JSON Serialization
84+
85+
Starting with version 5.0.0 when targeting .NET Core 3.1 `Amazon.Lambda.Serialization.SystemTextJson`. When targeting previous
86+
versions of .NET Core or using a version of Amazon.Lambda.AspNetCoreServer before 5.0.0 will use `Amazon.Lambda.Serialization.Json`.
87+
6388

6489
## Web App Path Base
6590

‎Libraries/src/Amazon.Lambda.Serialization.SystemTextJson/README.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Amazon.Lambda.Serialization.SystemTextJson
2+
3+
This package contains a custom `Amazon.Lambda.Core.ILambdaSerializer` implementation which uses System.Text.Json to
4+
serialize/deserialize .NET types in Lambda functions. This serializer targets .NET Core 3.1 so can be used the .NET Core 2.1
5+
Lambda runtime.
6+
7+
If targeting .NET Core 3.1 this serializer is highly recommend over Amazon.Lambda.Serialization.Json and can significantly reduce
8+
cold start performance in Lambda.
9+
10+
This serializer can be present on the assembly or on the handler method. If you specify both, the method attribute takes priority.
11+
12+
Here is an example of setting this attribute on the assembly.
13+
```
14+
[assembly: Amazon.Lambda.Core.LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.LambdaJsonSerializer))]
15+
```
16+
17+
And this is how the method can be applied to the handler method.
18+
```csharp
19+
[Amazon.Lambda.Core.LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.LambdaJsonSerializer))]
20+
public Response CustomSerializerMethod(Request input)
21+
{
22+
...
23+
}
24+
```

0 commit comments

Comments
 (0)