Add [S3Event] annotation attribute and source generator support

[GarrettBeatty]

Summary

Adds [S3Event] annotation attribute support to the Lambda Annotations framework, enabling developers to declaratively configure S3 event-triggered Lambda functions directly in C# code. The source generator automatically produces the corresponding SAM/CloudFormation template configuration at build time.

User Experience

With this change, developers can write S3-triggered Lambda functions like this:

[LambdaFunction]
[S3Event("@MyBucket", FilterSuffix = ".jpg")]
public async Task ProcessImage(S3Event evnt)
{
    // Handle uploaded images
}

The source generator will automatically generate the SAM template entry:

ProcessImage:
  Type: AWS::Serverless::Function
  Properties:
    Events:
      MyBucket:
        Type: S3
        Properties:
          Bucket: !Ref MyBucket
          Events:
            - s3:ObjectCreated:*
          Filter:
            S3Key:
              Rules:
                - Name: suffix
                  Value: .jpg

Attribute Properties

Property	Required	Description	Default
Bucket	Yes	S3 bucket reference (must start with @ to reference a CloudFormation resource)	-
ResourceName	No	CloudFormation event resource name	Derived from bucket name
Events	No	Semicolon-separated S3 event types	s3:ObjectCreated:*
FilterPrefix	No	S3 key prefix filter (e.g., uploads/)	Not set
FilterSuffix	No	S3 key suffix filter (e.g., .jpg)	Not set
Enabled	No	Whether the event source is enabled	true

Compile-Time Validation

The source generator validates at build time:

• Bucket reference: Must start with @ (referencing a CloudFormation resource)
• Method signature: First parameter must be S3Event, optional second parameter must be ILambdaContext
• Return type: Must be void or Task (S3 notifications are fire-and-forget)
• Dependencies: Project must reference Amazon.Lambda.S3Events NuGet package
• Resource name: Must be alphanumeric if explicitly set

Example with all properties

[LambdaFunction]
[S3Event("@MyBucket",
    ResourceName = "ImageUploadEvent",
    Events = "s3:ObjectCreated:Put;s3:ObjectRemoved:*",
    FilterPrefix = "uploads/",
    FilterSuffix = ".csv",
    Enabled = true)]
public async Task ProcessUpload(S3Event evnt, ILambdaContext context)
{
    context.Logger.LogLine($"Processing {evnt.Records.Count} records");
}

What Changed

Annotation Attribute (Amazon.Lambda.Annotations)

• New S3EventAttribute class in Amazon.Lambda.Annotations.S3 namespace with configurable properties and built-in validation

Source Generator (Amazon.Lambda.Annotations.SourceGenerator)

• S3EventAttributeBuilder — extracts attribute data from Roslyn syntax tree
• AttributeModelBuilder — recognizes and routes S3Event attributes
• EventTypeBuilder — maps to EventType.S3
• SyntaxReceiver — registers S3Event as a recognized attribute
• TypeFullNames — adds S3 type constants
• LambdaFunctionValidator — validates method signatures, return types, dependencies, and attribute properties
• CloudFormationWriter.ProcessS3Attribute() — generates SAM template with Bucket (Ref), Events (list), Filter (S3Key rules), and Enabled
• New diagnostic AWSLambda0133 for invalid S3EventAttribute errors

Tests

• Unit tests covering 7 attribute configurations × 2 template formats (JSON/YAML) = 14 test cases
• Synced property tests verifying template updates when attributes change
• Integration test deploying a real S3-triggered Lambda and verifying bucket notification configuration

Related: DOTNET-8572

[Copilot]

Pull request overview

Adds first-class S3 event source support to Lambda Annotations by introducing an [S3Event] attribute and extending the source generator to emit the corresponding SAM S3 event configuration (plus validation and tests), mirroring the existing SQS event workflow.

Changes:

• Introduce S3EventAttribute (Amazon.Lambda.Annotations) and wire it into the source generator (model building, validation, CloudFormation writing).
• Add unit tests + sample inputs to validate S3 event template output and property syncing behavior.
• Extend the TestServerlessApp integration test stack/template to include an S3-triggered function and validate bucket notification configuration.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
Libraries/test/TestServerlessApp/TestServerlessApp.csproj	Adds S3Events project reference for S3 event handler examples.
Libraries/test/TestServerlessApp/serverless.template	Adds generated S3 event function + S3 bucket resource to integration template.
Libraries/test/TestServerlessApp/S3EventExamples/ValidS3Events.cs.txt	Adds valid S3Event attribute usages for generator tests (non-deployed input).
Libraries/test/TestServerlessApp/S3EventExamples/S3EventProcessing.cs	Adds an S3-triggered Lambda function example for integration deployment.
Libraries/test/TestServerlessApp/aws-lambda-tools-defaults.json	Updates defaults for unique test bucket/stack naming used by deployment script.
Libraries/test/TestServerlessApp.IntegrationTests/S3EventNotification.cs	Adds integration test verifying S3 bucket notification configuration.
Libraries/test/TestServerlessApp.IntegrationTests/IntegrationTestContextFixture.cs	Adds S3 helper exposure + resolves deployed TestS3Bucket physical name; updates expected function count.
Libraries/test/TestServerlessApp.IntegrationTests/DeploymentScript.ps1	Ensures TestS3Bucket resource exists in deployed template for S3 event testing.
Libraries/test/IntegrationTests.Helpers/S3Helper.cs	Adds helper to fetch S3 bucket notification configuration.
Libraries/test/Amazon.Lambda.Annotations.SourceGenerators.Tests/WriterTests/S3EventsTests.cs	Adds CloudFormation writer tests for S3 event rendering and syncing.
Libraries/test/Amazon.Lambda.Annotations.SourceGenerators.Tests/Amazon.Lambda.Annotations.SourceGenerators.Tests.csproj	Adds S3Events project reference for source generator tests.
Libraries/src/Amazon.Lambda.Annotations/S3/S3EventAttribute.cs	Introduces public [S3Event] attribute with validation and configurable properties.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/Writers/CloudFormationWriter.cs	Adds S3 event serialization into SAM template + synced metadata tracking.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/Validation/LambdaFunctionValidator.cs	Adds dependency + signature validation for S3 event handlers and attribute validation diagnostics.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/TypeFullNames.cs	Registers S3 event types/attribute names for generator lookups.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/SyntaxReceiver.cs	Adds S3EventAttribute to attribute discovery map.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/Models/EventTypeBuilder.cs	Adds S3 event type detection from attributes.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/Models/Attributes/S3EventAttributeBuilder.cs	Adds builder that materializes S3EventAttribute data from Roslyn AttributeData.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/Models/Attributes/AttributeModelBuilder.cs	Wires S3EventAttributeBuilder into attribute model construction.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/Diagnostics/DiagnosticDescriptors.cs	Adds a dedicated diagnostic descriptor for invalid S3EventAttribute usage.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.