Skip to content

Conversation

@jnunn-aws
Copy link

Issue #, if available:
Fixes #2208

Description of changes:
This PR addresses the documentation gap identified in issue #2208 by adding a comprehensive "Handler Configuration" section to the AspNetCoreServer.Hosting README.

Changes Made:

  • Added new "Handler Configuration" section explaining the difference between executable and class library handler modes
  • Documented the common pitfall where using Main(string[] args) with incorrect handler configuration causes JsonSerializerException
  • Provided clear code examples showing both incorrect and correct handler setup patterns
  • Explained the technical reason why the error occurs (Lambda runtime attempting to bind API Gateway JSON to string array)

Community Impact:

  • Resolves confusion reported by community members about Lambda handler configuration
  • Provides clear guidance that was previously only available through project templates
  • Helps developers avoid the JsonSerializerException configuration error
  • Improves developer experience for AspNetCoreServer.Hosting users

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

- 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
@hvanbakel
Copy link
Contributor

That works for me. The AWS docs themselves could use some love there too but I don't think those are on GitHub. So here
https://docs.aws.amazon.com/lambda/latest/dg/csharp-handler.html#csharp-handler-signatures

@normj normj self-requested a review December 11, 2025 17:23

When deploying your Lambda function, the handler configuration depends on your project structure.

### Executable Mode (Recommended)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the README for Amazon.Lambda.AspNetCoreServer.Hosting which always has the Lambda function deployed as an executable. The doc update should be explaining how for this library the executable programming model is always used and the function handler must be set to the assembly name.

You can remove the Common Configuration Issue section because once they know to deploy as an executable that is a non-issue.

@normj normj added the Release Not Needed Add this label if a PR does not need to be released. label Dec 11, 2025
@GarrettBeatty GarrettBeatty self-requested a review December 12, 2025 18:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Release Not Needed Add this label if a PR does not need to be released.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Difference between top level statements and Main method with AspNetCoreServer.Hosting

3 participants