From 95531433c53d36b904b16061a2e0a742ed5930b9 Mon Sep 17 00:00:00 2001 From: Jonathan Nunn Date: Wed, 10 Dec 2025 18:33:06 +0000 Subject: [PATCH 1/6] Fix #2208: Add handler configuration documentation - Add Handler Configuration section to AspNetCoreServer.Hosting README - Document executable vs class library handler modes - Explain Main(string[] args) pitfall causing JsonSerializerException - Provide clear code examples for correct handler setup - Address community confusion about Lambda handler configuration --- .../README.md | 38 +++++++++++++++++-- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md b/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md index 68d287fa5..8cbc58315 100644 --- a/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md +++ b/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md @@ -1,4 +1,3 @@ - # Amazon.Lambda.AspNetCoreServer.Hosting This package allows ASP .NET Core applications written using the minimal api style to be deployed @@ -50,6 +49,40 @@ app.Run(); ``` +## Handler Configuration + +When deploying your Lambda function, the handler configuration depends on your project structure. + +### Executable Mode (Recommended) + +For executable mode, use `AssemblyName` as the handler (e.g., `MyLambdaProject`). This mode works with top-level statements or a `Main()` method without parameters. The Lambda runtime client handles event routing automatically. + +### Class Library Mode + +For class library mode, use `AssemblyName::ClassName::MethodName` as the handler. This mode works with traditional class-based handlers and uses reflection-based method invocation. + +### Common Configuration Issue + +When using `Main(string[] args)` with executable mode handler configuration, the Lambda runtime attempts to deserialize the incoming API Gateway event JSON into the `string[] args` parameter, which causes a `JsonSerializerException`. + +Incorrect usage: +```csharp +static void Main(string[] args) +{ + var builder = WebApplication.CreateBuilder(args); + // ... rest of setup +} +``` + +Correct usage for executable mode: +```csharp +static void Main() +{ + var builder = WebApplication.CreateBuilder(); + // ... rest of setup +} +``` + ## Extension Points `AddAWSLambdaHosting` accepts an optional `HostingOptions` configuration action that exposes the same customization hooks available in the traditional `AbstractAspNetCoreFunction` base class approach. @@ -110,5 +143,4 @@ builder.Services.AddAWSLambdaHosting(LambdaEventSource.HttpApi, options => apiResponse.Headers ??= new Dictionary(); apiResponse.Headers["X-Request-Id"] = context.AwsRequestId; }; -}); -``` \ No newline at end of file +}); \ No newline at end of file From 573277337ce00d16b928d9976f2929e80b31e2d0 Mon Sep 17 00:00:00 2001 From: Jonathan Nunn Date: Fri, 12 Dec 2025 18:29:05 +0000 Subject: [PATCH 2/6] Added change file --- .../issue-2208-handler-configuration-docs.json | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 .autover/changes/issue-2208-handler-configuration-docs.json diff --git a/.autover/changes/issue-2208-handler-configuration-docs.json b/.autover/changes/issue-2208-handler-configuration-docs.json new file mode 100644 index 000000000..2bbb78968 --- /dev/null +++ b/.autover/changes/issue-2208-handler-configuration-docs.json @@ -0,0 +1,11 @@ +{ + "Projects": [ + { + "Name": "Amazon.Lambda.AspNetCoreServer.Hosting", + "Type": "Patch", + "ChangelogMessages": [ + "Added Handler Configuration documentation explaining executable vs class library modes and Main(string[] args) pitfall" + ] + } + ] +} \ No newline at end of file From cef7080f714fff383ef3de8e64bb917ccc029208 Mon Sep 17 00:00:00 2001 From: Jonathan Nunn Date: Thu, 15 Jan 2026 17:26:43 +0000 Subject: [PATCH 3/6] Applied code review feedback --- .../src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md b/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md index 8cbc58315..c06a53ff9 100644 --- a/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md +++ b/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md @@ -60,6 +60,7 @@ For executable mode, use `AssemblyName` as the handler (e.g., `MyLambdaProject`) ### Class Library Mode For class library mode, use `AssemblyName::ClassName::MethodName` as the handler. This mode works with traditional class-based handlers and uses reflection-based method invocation. +<<<<<<< HEAD ### Common Configuration Issue @@ -143,4 +144,6 @@ builder.Services.AddAWSLambdaHosting(LambdaEventSource.HttpApi, options => apiResponse.Headers ??= new Dictionary(); apiResponse.Headers["X-Request-Id"] = context.AwsRequestId; }; -}); \ No newline at end of file +}); +======= +>>>>>>> 76224107 (Applied code review feedback) From f737cc9b02e54fe8d740dfe8641037daba96262a Mon Sep 17 00:00:00 2001 From: Jonathan Nunn Date: Thu, 15 Jan 2026 17:44:40 +0000 Subject: [PATCH 4/6] Applied code review feedback. --- .../README.md | 37 +------------------ 1 file changed, 2 insertions(+), 35 deletions(-) diff --git a/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md b/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md index c06a53ff9..b3c2688f3 100644 --- a/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md +++ b/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md @@ -51,38 +51,7 @@ app.Run(); ## Handler Configuration -When deploying your Lambda function, the handler configuration depends on your project structure. - -### Executable Mode (Recommended) - -For executable mode, use `AssemblyName` as the handler (e.g., `MyLambdaProject`). This mode works with top-level statements or a `Main()` method without parameters. The Lambda runtime client handles event routing automatically. - -### Class Library Mode - -For class library mode, use `AssemblyName::ClassName::MethodName` as the handler. This mode works with traditional class-based handlers and uses reflection-based method invocation. -<<<<<<< HEAD - -### Common Configuration Issue - -When using `Main(string[] args)` with executable mode handler configuration, the Lambda runtime attempts to deserialize the incoming API Gateway event JSON into the `string[] args` parameter, which causes a `JsonSerializerException`. - -Incorrect usage: -```csharp -static void Main(string[] args) -{ - var builder = WebApplication.CreateBuilder(args); - // ... rest of setup -} -``` - -Correct usage for executable mode: -```csharp -static void Main() -{ - var builder = WebApplication.CreateBuilder(); - // ... rest of setup -} -``` +The Lambda function handler must be set to the assembly name (e.g., `MyLambdaProject`). The `AddAWSLambdaHosting` method sets up the Lambda runtime client and registers the callback for processing Lambda events, so the handler should not use the class library format (`::::`). ## Extension Points @@ -144,6 +113,4 @@ builder.Services.AddAWSLambdaHosting(LambdaEventSource.HttpApi, options => apiResponse.Headers ??= new Dictionary(); apiResponse.Headers["X-Request-Id"] = context.AwsRequestId; }; -}); -======= ->>>>>>> 76224107 (Applied code review feedback) +}); \ No newline at end of file From 4ecd0343b07f5602366b2bf6c5fe5edadc23a6d3 Mon Sep 17 00:00:00 2001 From: Garrett Beatty Date: Sun, 1 Feb 2026 14:23:25 -0500 Subject: [PATCH 5/6] Delete .autover/changes/issue-2208-handler-configuration-docs.json --- .../issue-2208-handler-configuration-docs.json | 11 ----------- 1 file changed, 11 deletions(-) delete mode 100644 .autover/changes/issue-2208-handler-configuration-docs.json diff --git a/.autover/changes/issue-2208-handler-configuration-docs.json b/.autover/changes/issue-2208-handler-configuration-docs.json deleted file mode 100644 index 2bbb78968..000000000 --- a/.autover/changes/issue-2208-handler-configuration-docs.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "Projects": [ - { - "Name": "Amazon.Lambda.AspNetCoreServer.Hosting", - "Type": "Patch", - "ChangelogMessages": [ - "Added Handler Configuration documentation explaining executable vs class library modes and Main(string[] args) pitfall" - ] - } - ] -} \ No newline at end of file From d4f2266ed7a4bc8df1330ded940ccf6cab4efe7b Mon Sep 17 00:00:00 2001 From: Jonathan Nunn Date: Wed, 4 Mar 2026 23:49:21 +0000 Subject: [PATCH 6/6] Fix: Add missing closing backticks to code block --- .../src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md b/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md index b3c2688f3..0098747bf 100644 --- a/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md +++ b/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md @@ -1,3 +1,4 @@ + # Amazon.Lambda.AspNetCoreServer.Hosting This package allows ASP .NET Core applications written using the minimal api style to be deployed @@ -113,4 +114,5 @@ builder.Services.AddAWSLambdaHosting(LambdaEventSource.HttpApi, options => apiResponse.Headers ??= new Dictionary(); apiResponse.Headers["X-Request-Id"] = context.AwsRequestId; }; -}); \ No newline at end of file +}); +``` \ No newline at end of file