From de45d3e311861f429f35019c2011687d2c3ecf8e Mon Sep 17 00:00:00 2001
From: Jonathan Nunn <jonatnun@amazon.com>
Date: Wed, 10 Dec 2025 18:33:06 +0000
Subject: [PATCH 1/2] 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                                 | 36 ++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md b/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md
index bf3455a65..4ed76da23 100644
--- a/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md
+++ b/Libraries/src/Amazon.Lambda.AspNetCoreServer.Hosting/README.md
@@ -48,4 +48,38 @@ app.MapControllers();
 
 app.Run();
 
-```
\ No newline at end of file
+```
+
+## 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
+}
+```

From 40fac52430d5b70c3e632ae595de456fc30bf37e Mon Sep 17 00:00:00 2001
From: Jonathan Nunn <jonatnun@amazon.com>
Date: Fri, 12 Dec 2025 18:29:05 +0000
Subject: [PATCH 2/2] 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