Update EmptyServerless templates to use annotations, and remove preview messaging from annotations template

Author: ashovlin

Blueprints/BlueprintDefinitions/vs2022/AnnotationsFramework/blueprint-manifest.json

@@ -1,7 +1,7 @@
 {
-  "display-name": "Annotations Framework",
+  "display-name": "Annotations Framework Sample",
   "system-name": "Annotations",
-  "description": "(Preview) Use the .NET Lambda Annotations framework to write Lambda Functions.",
+  "description": "Use the .NET Lambda Annotations framework to write Lambda Functions. This is a sample application demonstrating usage of the annotation framework, as opposed to an empty project template.",
   "sort-order": 120,
   "hidden-tags": [
     "C#",

Blueprints/BlueprintDefinitions/vs2022/AnnotationsFramework/template/.template.config/template.json

@@ -5,7 +5,7 @@
     "Lambda",
     "Serverless"
   ],
-  "name": "Lambda Annotations Framework (Preview)",
+  "name": "Lambda Annotations Framework",
   "identity": "AWS.Lambda.Serverless.Annotations.CSharp",
   "groupIdentity": "AWS.Lambda.Serverless.Annotations",
   "shortName": "serverless.Annotations",

Blueprints/BlueprintDefinitions/vs2022/AnnotationsFramework/template/src/BlueprintBaseName.1/CalculatorService/CalculatorService.cs

@@ -0,0 +1,33 @@
+namespace BlueprintBaseName._1
+{
+    /// <summary>
+    /// The implementation of <see cref="ICalculatorService"/> 
+    /// that will be used by our Lambda functions.
+    /// </summary>
+    public class CalculatorService : ICalculatorService
+    {
+        /// <inheritdoc/>
+        public int Add(int x, int y)
+        {
+            return x + y;
+        }
+
+        /// <inheritdoc/>
+        public int Subtract(int x, int y)
+        {
+            return x - y;
+        }
+
+        /// <inheritdoc/>
+        public int Multiply(int x, int y)
+        {
+            return x * y;
+        }
+
+        /// <inheritdoc/>
+        public int Divide(int x, int y)
+        {
+            return x / y;
+        }
+    }
+}

Blueprints/BlueprintDefinitions/vs2022/AnnotationsFramework/template/src/BlueprintBaseName.1/CalculatorService/ICalculatorService.cs

@@ -0,0 +1,40 @@
+namespace BlueprintBaseName._1
+{
+    /// <summary>
+    /// An interface for a service that implements the business logic of our Lambda functions
+    /// </summary>
+    public interface ICalculatorService
+    {
+        /// <summary>
+        /// Adds x and y together
+        /// </summary>
+        /// <param name="x">Addend</param>
+        /// <param name="y">Addend</param>
+        /// <returns>Sum of x and y</returns>
+        int Add(int x, int y);
+
+        /// <summary>
+        /// Subtracts y from x
+        /// </summary>
+        /// <param name="x">Minuend</param>
+        /// <param name="y">Subtrahend</param>
+        /// <returns>x - y</returns>
+        int Subtract(int x, int y);
+
+        /// <summary>
+        /// Multiplies x and y
+        /// </summary>
+        /// <param name="x">Multiplicand</param>
+        /// <param name="y">Multiplier</param>
+        /// <returns>x * y</returns>
+        int Multiply(int x, int y);
+
+        /// <summary>
+        /// Divides x by y
+        /// </summary>
+        /// <param name="x">Dividend</param>
+        /// <param name="y">Divisor</param>
+        /// <returns>x / y</returns>
+        int Divide(int x, int y);
+    }
+}

Blueprints/BlueprintDefinitions/vs2022/AnnotationsFramework/template/src/BlueprintBaseName.1/Functions.cs

@@ -7,23 +7,29 @@
 namespace BlueprintBaseName._1
 {
     /// <summary>
-    /// A collection of sample Lambda functions that provide a REST api for doing simple math calculations. 
+    /// A collection of sample Lambda functions that provide a REST API for doing simple math calculations. 
     /// </summary>
     public class Functions
     {
+        private ICalculatorService _calculatorService;
+
         /// <summary>
         /// Default constructor.
         /// </summary>
-        public Functions()
+        /// <remarks>
+        /// The <see cref="ICalculatorService"/> implementation that we
+        /// instantiated in <see cref="Startup"/> will be injected here.
+        /// 
+        /// As an alternative, a dependency could be injected into each 
+        /// Lambda function handler via the [FromServices] attribute.
+        /// </remarks>
+        public Functions(ICalculatorService calculatorService)
         {
+            _calculatorService = calculatorService;
         }
 
         /// <summary>
         /// Root route that provides information about the other requests that can be made.
-        ///
-        /// PackageType is currently required to be set to LambdaPackageType.Image till the upcoming .NET 6 managed
-        /// runtime is available. Once the .NET 6 managed runtime is available PackageType will be optional and will
-        /// default to Zip.
         /// </summary>
         /// <returns>API descriptions.</returns>
         [LambdaFunction()]
@@ -42,10 +48,6 @@ public string Default()
 
         /// <summary>
         /// Perform x + y
-        ///
-        /// PackageType is currently required to be set to LambdaPackageType.Image till the upcoming .NET 6 managed
-        /// runtime is available. Once the .NET 6 managed runtime is available PackageType will be optional and will
-        /// default to Zip.
         /// </summary>
         /// <param name="x"></param>
         /// <param name="y"></param>
@@ -54,16 +56,14 @@ public string Default()
         [HttpApi(LambdaHttpMethod.Get, "/add/{x}/{y}")]
         public int Add(int x, int y, ILambdaContext context)
         {
-            context.Logger.LogInformation($"{x} plus {y} is {x + y}");
-            return x + y;
+            var sum = _calculatorService.Add(x, y);
+
+            context.Logger.LogInformation($"{x} plus {y} is {sum}");
+            return sum;
         }
 
         /// <summary>
         /// Perform x - y.
-        ///
-        /// PackageType is currently required to be set to LambdaPackageType.Image till the upcoming .NET 6 managed
-        /// runtime is available. Once the .NET 6 managed runtime is available PackageType will be optional and will
-        /// default to Zip.
         /// </summary>
         /// <param name="x"></param>
         /// <param name="y"></param>
@@ -72,16 +72,14 @@ public int Add(int x, int y, ILambdaContext context)
         [HttpApi(LambdaHttpMethod.Get, "/subtract/{x}/{y}")]
         public int Subtract(int x, int y, ILambdaContext context)
         {
-            context.Logger.LogInformation($"{x} subtract {y} is {x - y}");
-            return x - y;
+            var difference = _calculatorService.Subtract(x, y);
+
+            context.Logger.LogInformation($"{x} subtract {y} is {difference}");
+            return difference;
         }
 
         /// <summary>
         /// Perform x * y.
-        ///
-        /// PackageType is currently required to be set to LambdaPackageType.Image till the upcoming .NET 6 managed
-        /// runtime is available. Once the .NET 6 managed runtime is available PackageType will be optional and will
-        /// default to Zip.
         /// </summary>
         /// <param name="x"></param>
         /// <param name="y"></param>
@@ -90,16 +88,14 @@ public int Subtract(int x, int y, ILambdaContext context)
         [HttpApi(LambdaHttpMethod.Get, "/multiply/{x}/{y}")]
         public int Multiply(int x, int y, ILambdaContext context)
         {
-            context.Logger.LogInformation($"{x} multiply {y} is {x * y}");
-            return x * y;
+            var product = _calculatorService.Multiply(x, y);
+
+            context.Logger.LogInformation($"{x} multiplied by {y} is {product}");
+            return product;
         }
 
         /// <summary>
         /// Perform x / y.
-        ///
-        /// PackageType is currently required to be set to LambdaPackageType.Image till the upcoming .NET 6 managed
-        /// runtime is available. Once the .NET 6 managed runtime is available PackageType will be optional and will
-        /// default to Zip.
         /// </summary>
         /// <param name="x"></param>
         /// <param name="y"></param>
@@ -108,8 +104,10 @@ public int Multiply(int x, int y, ILambdaContext context)
         [HttpApi(LambdaHttpMethod.Get, "/divide/{x}/{y}")]
         public int Divide(int x, int y, ILambdaContext context)
         {
-            context.Logger.LogInformation($"{x} divide {y} is {x / y}");
-            return x / y;
+            var quotient = _calculatorService.Divide(x, y);
+
+            context.Logger.LogInformation($"{x} divided by {y} is {quotient}");
+            return quotient;
         }
     }
 }

Blueprints/BlueprintDefinitions/vs2022/AnnotationsFramework/template/src/BlueprintBaseName.1/Readme.md

@@ -1,10 +1,10 @@
-# .NET Lambda Annotations Framework (Preview)
-
-The Lambda Annotations framework is currently in **preview**. Development for this framework is being done on the [aws/aws-lambda-dotnet](https://github.com/aws/aws-lambda-dotnet) repository. We would appreciate any feedback or feature suggestions on this library. 
+# .NET Lambda Annotations Framework
 
 Lambda Annotations is a programming model for writing .NET Lambda function. At a high level the programming model allows
 idiomatic .NET coding patterns and uses [C# Source Generators](https://docs.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/source-generators-overview) to bridge the gap between the Lambda programming model to the more .NET idiomatic programming model.
 
+This template uses Lambda Annotations to deploy an HTTP API backed by multiple Lambda functions. This is intended as a sample application demonstrating usage of the annotation framework, as opposed to an empty project template.
+
 Here is a simplistic example of a .NET Lambda function that acts like a calculator plus method using the normal 
 Lambda programming model. It responds to an API Gateway REST API, pulls the operands from the resource paths, does the 
 addition and returns back an API Gateway response.
@@ -59,7 +59,7 @@ public class Functions
 To bridge the gap from Lambda Annotations programming model to the normal programming model a .NET source generator is included in this package.
 After adding the attributes to your .NET code the source generator will generate the translation code between the 2 programming models. It will also
 keep in sync the generated information including a new function handler string into the CloudFormation template. The usage of source
-generator is transparent to the user.
+generator is transparent to the user. The source generator supports syncing of both JSON and YAML CloudFormation templates.
 
 To see the code that is generated by the source generator turn the verbosity to detailed when executing a build. From the command this 
 is done by using the `--verbosity` switch.
@@ -105,7 +105,7 @@ public class Functions
 
 
     [LambdaFunction]
-    [HttpApi(HttpMethod.Put, HttpApiVersion.V2, "/process/{name}")]
+    [HttpApi(LambdaHttpMethod.Put, "/process/{name}", Version = HttpApiVersion.V2)]
     public async Task Process([FromServices] ITracker tracker, string name, [FromBody] string data)
     {
         tracker.Record();
@@ -151,4 +151,12 @@ parameter to the `LambdaFunction` must be the event object and the event source
 * FromBody
     * Map method parameter to HTTP request body. If parameter is a complex type then request body will be assumed to be JSON and deserialized into the type.
 * FromServices
-    * Map method parameter to registered service in IServiceProvider.
+    * Map method parameter to registered service in IServiceProvider.
+
+## Project References
+
+If you are using API Gateway event attributes, such as `RestAPI` or `HttpAPI`, you need to manually add a package reference to `Amazon.Lambda.APIGatewayEvents` in your project, otherwise the project will not compile. We do not include it by default in order to keep the `Amazon.Lambda.Annotations` library lightweight.
+
+This release only supports API Gateway Events. As we add support for other types of events, such as S3 or DynamoDB, the list of required package references will depend on the Lambda .NET attributes you are using. 
+
+**Note**: If you are using [dependency injection](#dependency-injection) to write functions for other service events , such as S3 or DynamoDB, you will need to reference these packages in your project as well

Blueprints/BlueprintDefinitions/vs2022/AnnotationsFramework/template/src/BlueprintBaseName.1/Startup.cs

@@ -1,5 +1,3 @@
-using Microsoft.Extensions.DependencyInjection;
-
 namespace BlueprintBaseName._1
 {
     [Amazon.Lambda.Annotations.LambdaStartup]
@@ -15,6 +13,9 @@ public class Startup
         /// </summary>
         public void ConfigureServices(IServiceCollection services)
         {
+            // Here we'll add an instance of our calculator service that be used by each function
+            services.AddSingleton<ICalculatorService>(new CalculatorService());
+
             //// Example of creating the IConfiguration object and
             //// adding it to the dependency injection container.
             //var builder = new ConfigurationBuilder()

Blueprints/BlueprintDefinitions/vs2022/AnnotationsFramework/template/test/BlueprintBaseName.1.Tests/BlueprintBaseName.1.Tests.csproj

@@ -9,6 +9,7 @@
     <PackageReference Include="Amazon.Lambda.TestUtilities" Version="2.0.0" />
     <PackageReference Include="Amazon.Lambda.APIGatewayEvents" Version="2.5.0" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.0.0" />
+    <PackageReference Include="Moq" Version="4.18.2" />
     <PackageReference Include="xunit" Version="2.4.1" />
     <PackageReference Include="xunit.runner.visualstudio" Version="2.4.3" />
   </ItemGroup>

Blueprints/BlueprintDefinitions/vs2022/AnnotationsFramework/template/test/BlueprintBaseName.1.Tests/FunctionTest.cs

@@ -1,20 +1,31 @@
 using Xunit;
 using Amazon.Lambda.TestUtilities;
+using Moq;
+
 
 namespace BlueprintBaseName._1.Tests
 {
     public class FunctionTest
     {
+        ICalculatorService _mockCalculatorService;
+
         public FunctionTest()
         {
+            // This isn't an accurate calculator, but rather shows how the business logic
+            // for our Lambda functions can be moved to a class that can be replaced by a
+            // mocked implementation for testing.
+            var mock = new Mock<ICalculatorService>();
+            mock.Setup(m => m.Add(It.IsAny<int>(), It.IsAny<int>())).Returns(12);
+
+            _mockCalculatorService = mock.Object;
         }
 
         [Fact]
         public void TestAdd()
         {
             TestLambdaContext context = new TestLambdaContext();
 
-            var functions = new Functions();
+            var functions = new Functions(_mockCalculatorService);
             Assert.Equal(12, functions.Add(3, 9, context));
         }
     }

Blueprints/BlueprintDefinitions/vs2022/EmptyServerless-Image/template/src/BlueprintBaseName.1/BlueprintBaseName.1.csproj

@@ -11,8 +11,10 @@
     <PublishReadyToRun>true</PublishReadyToRun>
   </PropertyGroup>
   <ItemGroup>
+    <PackageReference Include="Amazon.Lambda.Annotations" Version="0.6.0-preview" />
     <PackageReference Include="Amazon.Lambda.Core" Version="2.1.0" />
     <PackageReference Include="Amazon.Lambda.Serialization.SystemTextJson" Version="2.3.0" />
     <PackageReference Include="Amazon.Lambda.APIGatewayEvents" Version="2.5.0" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="6.0.0" />
   </ItemGroup>
 </Project>

Blueprints/BlueprintDefinitions/vs2022/EmptyServerless-Image/template/src/BlueprintBaseName.1/Function.cs

@@ -1,6 +1,8 @@
 using System.Net;
 using Amazon.Lambda.Core;
 using Amazon.Lambda.APIGatewayEvents;
+using Amazon.Lambda.Annotations;
+using Amazon.Lambda.Annotations.APIGateway;
 
 // Assembly attribute to enable the Lambda function's JSON input to be converted into a .NET class.
 [assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]
@@ -20,11 +22,23 @@ public Functions()
     /// <summary>
     /// A Lambda function to respond to HTTP Get methods from API Gateway
     /// </summary>
-    /// <param name="request"></param>
-    /// <returns>The API Gateway response.</returns>
-    public APIGatewayProxyResponse Get(APIGatewayProxyRequest request, ILambdaContext context)
+    /// <remarks>
+    /// This uses the <see href="https://github.com/aws/aws-lambda-dotnet/blob/master/Libraries/src/Amazon.Lambda.Annotations/README.md">Lambda Annotations</see> 
+    /// programming model to bridge the gap between the Lambda programming model and a more idiomatic .NET model.
+    /// 
+    /// This automatically handles reading parameters from an APIGatewayProxyRequest
+    /// as well as syncing the function definitions to serverless.template each time you build.
+    /// 
+    /// If you do not wish to use this model and need to manipulate the API Gateway 
+    /// objects directly, see the accompanying Readme.md for instructions.
+    /// </remarks>
+    /// <param name="context">Information about the invocation, function, and execution environment</param>
+    /// <returns>The response as an <see cref="APIGatewayProxyResponse"/></returns>
+    [LambdaFunction(PackageType = LambdaPackageType.Image, Policies = "AWSLambdaBasicExecutionRole", MemorySize = 256, Timeout = 30)]
+    [RestApi(LambdaHttpMethod.Get, "/")]
+    public APIGatewayProxyResponse Get(ILambdaContext context)
     {
-        context.Logger.LogInformation("Get Request\n");
+        context.Logger.LogInformation("Handling the 'Get' Request");
 
         var response = new APIGatewayProxyResponse
         {
@@ -35,4 +49,4 @@ public APIGatewayProxyResponse Get(APIGatewayProxyRequest request, ILambdaContex
 
         return response;
     }
-}
+}