Skip to content

Commit cf8cecb

Browse files
normjnormj
authored
Update README file for ASP.NET Core integration (#1784)
1 parent 1447a8d commit cf8cecb

File tree

3 files changed

+64
-72
lines changed

3 files changed

+64
-72
lines changed

Diff for: ‎Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md

+5
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,11 @@ This package allows ASP .NET Core applications written using the minimal api sty
99
The `AddAWSLambdaHosting` will setup the `Amazon.Lambda.AspNetCoreServer` package to process
1010
the incoming Lambda events as ASP .NET Core requests. It will also initialize `Amazon.Lambda.RuntimeSupport` package to interact with the Lambda service.
1111

12+
## Supported .NET versions
13+
14+
This library supports .NET 6 and above. Lambda provides managed runtimes for long term supported (LTS) versions like .NET 6 and .NET 8. To use standard term supported (STS) versions like .NET 9
15+
the Lambda function must be bundled as a self contained executable or an OCI image.
16+
1217
## Sample ASP .NET Core application
1318

1419
The code sample below is the typical initilization code for an ASP .NET Core application using the minimal api style. The one difference is the extra line of code calling `AddAWSLambdaHosting`.

Diff for: ‎Libraries/src/Amazon.Lambda.AspNetCoreServer/README.md

+58-71
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,17 @@ 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+
## Supported .NET versions
12+
13+
This library supports .NET 6 and above. Lambda provides managed runtimes for long term supported (LTS) versions like .NET 6 and .NET 8. To use standard term supported (STS) versions like .NET 9
14+
the Lambda function must be bundled as a self contained executable or an OCI image.
15+
16+
## Amazon.Lambda.AspNetCoreServer vs Amazon.Lambda.AspNetCoreServer.Hosting
17+
18+
The `Amazon.Lambda.AspNetCoreServer` is typically used with the older ASP.NET Core pattern of having a `Startup` class to setup the ASP.NET Core application. This allows you to share the ASP.NET Core setup logic between the `LambdaEntryPoint` and the normal `Main` entrypoint used for running the ASP.NET Core applications locally. For integrating Lambda into an ASP.NET Core project using the minimal api pattern checkout the [Amazon.Lambda.AspNetCoreServer.Hosting](https://github.com/aws/aws-lambda-dotnet/tree/master/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting). This package integrates Amazon.Lambda.AspNetCoreServer setup into the project's `Main` or top level statements.
19+
20+
Using Amazon.Lambda.AspNetCoreServer directly instead of Amazon.Lambda.AspNetCoreServer.Hosting is recommened when projects need to customize the Lambda behavior through the `LambdaEntryPoint` by overriding the base class methods.
21+
1122
## Lambda Entry Point
1223

1324
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
@@ -23,95 +34,71 @@ is called `LambdaEntryPoint`. The base class is determined based on where the La
2334

2435
**Note:** HTTP API default to payload 2.0 so unless 1.0 is explicitly set the base class should be APIGatewayHttpApiV2ProxyFunction.
2536

26-
Here is an example implementation of the Lamba function in an ASP.NET Core Web API application.
27-
```csharp
28-
using System.IO;
37+
The function handler for the Lambda function will be **TestWebApp::TestWebApp.LambdaEntryPoint::FunctionHandlerAsync**.
2938

30-
using Amazon.Lambda.AspNetCoreServer;
31-
using Microsoft.AspNetCore.Hosting;
39+
## ASP.NET Core setup
3240

33-
namespace TestWebApp
41+
The `LambdaEntryPoint` class in the ASP.NET Core project inherits `Init` methods that can be used to setup ASP.NET Core application. The most common approach is override the `Init` and using the `UseStartup` method on the `IWebHostBuilder` register the startup class. The startup class contains ASP.NET Core setup logic that can be shared between the `LambdaEntryPoint` and the project's `Main` method.
42+
43+
Example `LambdaEntryPoint`:
44+
```csharp
45+
public class LambdaEntryPoint : Amazon.Lambda.AspNetCoreServer.APIGatewayProxyFunction
3446
{
3547
/// <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
48+
/// The builder has configuration, logging and Amazon API Gateway already configured. The startup class
49+
/// needs to be configured in this method using the UseStartup<>() method.
4050
/// </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
51+
/// <param name="builder">The IWebHostBuilder to configure.</param>
52+
protected override void Init(IWebHostBuilder builder)
5553
{
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>
61-
protected override void Init(IWebHostBuilder builder)
62-
{
63-
builder
64-
.UseStartup<Startup>();
65-
}
54+
builder
55+
.UseStartup<Startup>();
6656
}
6757
}
6858
```
6959

70-
The function handler for the Lambda function will be **TestWebApp::TestWebApp.LambdaEntryPoint::FunctionHandlerAsync**.
71-
72-
## Bootstrapping application (IWebHostBuilder vs IHostBuilder)
73-
74-
ASP.NET Core applications are bootstrapped by using a host builder. The host builder is used to configure all of the required services needed to run the ASP.NET Core application. With Amazon.Lambda.AspNetCoreServer there are multiple options for customizing the bootstrapping and they vary between targeted versions of .NET Core.
75-
76-
### ASP.NET Core 3.1
77-
78-
ASP.NET Core 3.1 uses the generic `IHostBuilder` to bootstrap the application. In a typical ASP.NET Core 3.1 application the `Program.cs` file will bootstrap the application using `IHostBuilder` like the following snippet shows. As part of creating the `IHostBuilder` an `IWebHostBuilder` is created by the `ConfigureWebHostDefaults` method.
79-
60+
Example `Startup`:
8061
```csharp
81-
public static IHostBuilder CreateHostBuilder(string[] args) =>
82-
Host.CreateDefaultBuilder(args)
83-
.ConfigureWebHostDefaults(webBuilder =>
84-
{
85-
webBuilder.UseStartup<Startup>();
86-
});
87-
```
88-
89-
Amazon.Lambda.AspNetCoreServer creates this `IHostBuilder` and configures all of the default settings needed to run the ASP.NET Core application in Lambda.
90-
91-
There are two `Init` methods that can be overridden to customize the `IHostBuilder`. The most common customization is to override the `Init(IWebHostBuilder)` method and set the startup class via the `UseStartup` method. To customize the `IHostBuilder` then override the `Init(IHostBuilder)`. **Do not call `ConfigureWebHostDefaults` when overriding `Init(IHostBuilder)` because Amazon.Lambda.AspNetCoreServer will call `ConfigureWebHostDefaults` when creating the `IHostBuilder`. By calling `ConfigureWebHostDefaults` in the `Init(IHostBuilder)` method, the `IWebHostBuilder` will be configured twice.**
92-
93-
If you want complete control over creating the `IHostBuilder` then override the `CreateHostBuilder` method. When overriding the `CreateHostBuilder` method neither of the `Init` methods will be called unless the override calls the base implementation. When overriding `CreateHostBuilder` it is recommended to call `ConfigureWebHostLambdaDefaults` instead of `ConfigureWebHostDefaults` to configure the `IWebHostBuilder` for Lambda.
94-
95-
If the `CreateWebHostBuilder` is overridden in an ASP.NET Core 3.1 application then only the `IWebHostBuilder` is used for bootstrapping using the same pattern that ASP.NET Core 2.1 applications use. `CreateHostBuilder` and `Init(IHostBuilder)` will not be called when `CreateWebHostBuilder` is overridden.
96-
97-
98-
99-
### ASP.NET Core 2.1
62+
public class Startup
63+
{
64+
public Startup(IConfiguration configuration)
65+
{
66+
Configuration = configuration;
67+
}
10068

101-
ASP.NET Core 2.1 applications are bootstrapped with the `IWebHostBuilder` type. Amazon.Lambda.AspNetCoreServer will create an instance of `IWebHostBuilder` and it can be customized by overriding the `Init(IWebHostBuilder)` method. The most common customization is configuring the startup class via the `UseStartup` method.
69+
public IConfiguration Configuration { get; }
10270

103-
If you want complete control over creating the `IWebHostBuilder` then override the `CreateWebHostBuilder` method. When overriding the `CreateWebHostBuilder` method the `Init(IWebHostBuilder)` method will not be called unless the override calls the base implementation or explicitly calls the `Init(IWebHostBuilder)` method.
71+
// This method gets called by the runtime. Use this method to add services to the container
72+
public void ConfigureServices(IServiceCollection services)
73+
{
74+
services.AddControllers();
75+
}
10476

77+
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline
78+
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
79+
{
80+
if (env.IsDevelopment())
81+
{
82+
app.UseDeveloperExceptionPage();
83+
}
10584

106-
## Access to Lambda Objects from HttpContext
85+
app.UseHttpsRedirection();
10786

108-
The original lambda request object and the `ILambdaContext` object can be accessed from the `HttpContext.Items` collection.
87+
app.UseRouting();
10988

110-
| Constant | Object |
111-
|-------|--------|
112-
| AbstractAspNetCoreFunction.LAMBDA_CONTEXT | ILambdaContext |
113-
| AbstractAspNetCoreFunction.LAMBDA_REQUEST_OBJECT | <ul><li>APIGatewayProxyFunction -> APIGatewayProxyRequest</li><li>APIGatewayHttpApiV2ProxyFunction -> APIGatewayHttpApiV2ProxyRequest</li><li>ApplicationLoadBalancerFunction -> ApplicationLoadBalancerRequest</li></ul> |
89+
app.UseAuthorization();
11490

91+
app.UseEndpoints(endpoints =>
92+
{
93+
endpoints.MapControllers();
94+
endpoints.MapGet("/", async context =>
95+
{
96+
await context.Response.WriteAsync("Welcome to running ASP.NET Core on AWS Lambda");
97+
});
98+
});
99+
}
100+
}
101+
```
115102

116103
## JSON Serialization
117104

Diff for: ‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# AWS Lambda for .NET [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/aws/aws-lambda-dotnet?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
1+
# AWS Lambda for .NET
22

33
Repository for the AWS NuGet packages and Blueprints to support writing AWS Lambda functions using .NET Core.
44

0 commit comments

Comments
 (0)