Getting the AWS CLI Tool<\/h2>\n
First, you will need the following tools:<\/p>\n
- \n
- AWS CLI tool<\/li>\n
- .NET 6 SDK<\/li>\n
- Rider, Visual Studio 2022, Vim, or an editor of choice<\/li>\n<\/ul>\n
The AWS CLI tool can be obtained from the AWS documentation<\/a>. You will need to create an account then set up the CLI tool with your credentials. The goal is to configure the credentials<\/em> file under the AWS folder and set an access key. You will also need to set the region depending on your physical location. Because this is not an exhaustive guide on getting started, I will leave the rest up to you the reader.<\/p>\n
Create a New Project<\/h2>\n
I will pick the .NET 6 CLI tool because it is the most accessible to everyone. You can open a console via Windows Terminal or the CMD tool. Before you begin, verify that you have the correct version installed on your machine.<\/p>\n
> dotnet --version<\/pre>\n
This outputs version 6.0.42 on my machine. Next, you will need the AWS dotnet templates:<\/p>\n
> dotnet new -i Amazon.Lambda.Templates\r\n> dotnet tool install -g Amazon.Lambda.Tools<\/pre>\n
If you have already installed these templates, simply check that you have the latest available:<\/p>\n
> dotnet tool update -g Amazon.Lambda.Tools<\/pre>\n
Then, create a new project and a test project with a region.<\/p>\n
> dotnet new serverless.AspNetCoreMinimalAPI -n Pizza.Api \\\r\n --profile default --region us-east-1\r\n\r\n> dotnet new xunit -n Pizza.Api.Tests<\/pre>\n
Be sure to set the correct region, one that matches your profile in the AWS CLI tool.<\/p>\n
The dotnet CLI generates a bunch of files and puts them all over the place. I recommend doing a bit of manual clean up and follow the folder structure below in Figure 1.<\/p>\n
![\"Graphical](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2023\/01\/graphical-user-interface-text-application-descr-1.png\")
<\/p>\nFigure 1. Folder structure<\/strong><\/p>\n
You may also create the solution file Pizza.Api.sln via:<\/p>\n
> dotnet new sln -n Pizza.Api\r\n> dotnet sln add src\\Pizza.Api\\Pizza.Api.csproj\r\n> dotnet sln add test\\Pizza.Api.Tests\\Pizza.Api.Tests.csproj<\/pre>\n
This allows you to open the entire solution in Rider<\/a>, for example, to make the coding experience much richer.<\/p>\n
The template generated nonsense like a Controllers folder and HTTPS redirect. Simply delete the Controllers folder in the
Pizza.Api<\/code> folder and delete theUnitTest1.cs<\/code> file that is in thePizza.Api.Tests<\/code> folder.<\/p>\nIn the Program.cs file delete the following lines of code.<\/p>\n
builder.Services.AddControllers();\r\n\r\napp.UseHttpsRedirection();\r\napp.UseAuthorization();\r\napp.MapControllers();<\/pre>\n
The HTTPS redirect is a pesky feature that only applies to local to make life harder for developers. On the AWS cloud, the AWS Gateway handles traffic before it calls into your lambda function. Gutting dependencies also helps with cold starts. Trimming middleware like Controllers and Authorization keeps the request pipeline efficient because you get billed while the code is running. One technique to keep costs low, for example, is to use Cognito<\/a> instead of doing auth inside the lambda function.<\/p>\n
Run Your Lambda on Local<\/h2>\n
Luckily, .NET 6 makes this process somewhat familiar to .NET developers who are used to working with on-prem solutions. Be sure to have (or create) the following
launchSettings.json<\/code> under a Properties<\/strong> folder in the project:<\/p>\n{\r\n \"$schema\": \"https:\/\/json.schemastore.org\/launchsettings.json\",\r\n \"profiles\": {\r\n \"Pizza.Api\": {\r\n \"commandName\": \"Project\",\r\n \"dotnetRunMessages\": true,\r\n \"launchBrowser\": false,\r\n \"applicationUrl\": \"http:\/\/localhost:5095\",\r\n \"environmentVariables\": {\r\n \"ASPNETCORE_ENVIRONMENT\": \"Development\"\r\n }\r\n }\r\n }\r\n}<\/pre>\nNow, go back to the console and run the app under the
..\\Pizza.Api\\src\\Pizza.Api<\/code> folder:<\/p>\n> dotnet watch<\/pre>\n
There should be an output telling you it is now running under the port number 5095.<\/p>\n
![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2023\/01\/word-image-95401-2.png\")
<\/p>\nThis watcher tool automatically hot reloads, which is a nice feature from Microsoft, this is to keep up with code changes on the fly without restarting the app. This is mostly there for convenience, so I recommend keeping an eye out to make sure the latest code is actually running.<\/p>\n
Then, use CURL to test your lambda function on local, make sure the -i flag remains lowercase or try –include:<\/p>\n
> curl -X GET -i -H \"Accept: application\/json\" http:\/\/localhost:5095<\/pre>\n
With the AWS tools, developers who are familiar with .NET should start to feel more at home. This is one of the niceties of the ecosystem, because the tools remain identical on the surface.<\/p>\n
The one radical departure so far is using the minimal API to host an endpoint and I will explore this topic next.<\/p>\n
Make a Pizza<\/h2>\n
To make a pizza, first, you will need to install the DynamoDB NuGet package in the project. (If you are not acquainted with Amazon DynamoDB, you can get more information here<\/a>)<\/p>\n
In the same
Pizza.Api<\/code> folder, install the dependency:<\/p>\n> dotnet add package AWSSDK.DynamoDBv2<\/pre>\n
Also, this project requires a Slugify<\/a> dependency. This will convert a string, like a pizza name, into a unique identifier we can put in the URL to find the pizza resource in the API.<\/p>\n
To install the
slugify<\/code> dependency:<\/p>\n> dotnet add package Slugify.Core<\/pre>\n
With lambda functions, one goal is to keep dependencies down to a minimum. You may find it necessary to copy-paste code instead of adding yet another dependency to keep the bundle size small. In this case, I opted to add more dependencies to make writing this article easier for me.<\/p>\n
Create a
Usings.cs<\/code> file in thePizza.Api<\/code> directory insrc<\/code> and put these global usings in:<\/p>\nglobal using Amazon;\r\nglobal using Amazon.DynamoDBv2;\r\nglobal using Amazon.DynamoDBv2.DataModel;\r\nglobal using Pizza.Api;\r\nglobal using Slugify;<\/pre>\n
Now, in the
Program.cs<\/code> file wire up dependencies through the IoC container:<\/p>\nbuilder.Services.AddSingleton<IAmazonDynamoDB>( _ =>\r\n new AmazonDynamoDBClient(RegionEndpoint.USEast1));\r\nbuilder.Services.AddSingleton<IDynamoDBContext>(p =>\r\n new DynamoDBContext(p.GetService<IAmazonDynamoDB>()));\r\nbuilder.Services.AddScoped<ISlugHelper, SlugHelper>();\r\nbuilder.Services.AddScoped<PizzaHandler>();<\/pre>\n
Note your region can differ from mine. I opted to use the DynamoDB object persistence model via the Amazon.DynamoDBv2.DataModel namespace to keep the code minimal. This decision dings cold starts a bit, but only a little. Here though, I am paying the cost of latency to gain developer convenience.<\/p>\n
The DynamoDB object persistence model requires a pizza model with annotations so it can do the mapping between your C# code and the database table.<\/p>\n
Create a
PizzaModel.cs<\/code> file, and put this code in:<\/p>\nnamespace Pizza.Api;\r\n\r\n[DynamoDBTable(\"pizzas\")]\r\npublic class PizzaModel\r\n{\r\n [DynamoDBHashKey]\r\n [DynamoDBProperty(\"url\")]\r\n public string Url { get; set; } = string.Empty;\r\n\r\n [DynamoDBProperty(\"name\")]\r\n public string Name { get; set; } = string.Empty;\r\n\r\n [DynamoDBProperty(\"ingredients\")]\r\n public List<string> Ingredients { get; set; } = new();\r\n\r\n public override string ToString() =>\r\n $\"{Name}: {string.Join(',', Ingredients)}\";\r\n}<\/pre>\nGiven the table definition above, create the DynamoDB table via the AWS CLI tool:<\/p>\n
> aws dynamodb create-table --table-name pizzas \\\r\n --attribute-definitions AttributeName=url,AttributeType=S \\\r\n --key-schema AttributeName=url,KeyType=HASH \\\r\n --provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1 \\\r\n --region us-east-1 --query TableDescription.TableArn --output text<\/pre>\n
The url field is the hash which uniquely identifies the pizza entry. This is also the key used to find pizzas in the database table.<\/p>\n
Next, create the
PizzaHandler.cs<\/code> file, and put in a basic scaffold:<\/p>\nnamespace Pizza.Api;\r\n\r\npublic class PizzaHandler\r\n{\r\n private readonly ISlugHelper _slugHelper;\r\n private readonly IDynamoDBContext _context;\r\n private readonly ILogger<PizzaHandler> _logger;\r\n\r\n public PizzaHandler(\r\n IDynamoDBContext context,\r\n ISlugHelper slugHelper,\r\n ILogger<PizzaHandler> logger)\r\n {\r\n _context = context;\r\n _slugHelper = slugHelper;\r\n _logger = logger;\r\n }\r\n\r\n public async Task<IResult> MakePizza(PizzaModel pizza)\r\n {\r\n throw new NotImplementedException();\r\n }\r\n\r\n public async Task<IResult> TastePizza(string url)\r\n {\r\n throw new NotImplementedException();\r\n }\r\n}<\/pre>\nThis is the main file that will serve pizzas. The focus right now is the
MakePizza<\/code> method.<\/p>\nBefore continuing, create the
PizzaHandlerTests.cs<\/code> file under the test project:<\/p>\nnamespace Pizza.Api.Tests;\r\n\r\npublic class PizzaHandlerTests\r\n{\r\n private readonly Mock<IDynamoDBContext> _context;\r\n private readonly PizzaHandler _handler;\r\n\r\n public PizzaHandlerTests()\r\n {\r\n var slugHelper = new Mock<ISlugHelper>();\r\n _context = new Mock<IDynamoDBContext>();\r\n var logger = new Mock<ILogger<PizzaHandler>>();\r\n\r\n _handler = new PizzaHandler(\r\n _context.Object,\r\n slugHelper.Object,\r\n logger.Object);\r\n }\r\n}<\/pre>\nThe test project should have its own Usings.cs file, add these global entries:<\/p>\n
global using Moq;\r\nglobal using Amazon.DynamoDBv2.DataModel;\r\nglobal using Microsoft.Extensions.Logging;\r\nglobal using Slugify;<\/pre>\n
Also, install the Moq<\/a> dependency under the
Pizza.Api.Tests<\/code> project:<\/p>\n> dotnet add package Moq<\/pre>\n
You will also need the Slugify and Amazon.DynamoDBv2 packages seen in the
Pizza.Api<\/code> project as well. First, I like to unit test my code to check that my reasoning behind the code is sound. This is a technique that I picked up from my eight-grade teacher: \u201ctest early and test often\u201d. The faster the feedback loop is between code you just wrote and a reasonable test, the more effective you can be in getting the job done.<\/p>\nInside the
PizzaHandlerTests<\/code> class, create a unit test method:<\/p>\n[Fact]\r\npublic async Task MakePizzaCreated()\r\n{\r\n \/\/ arrange\r\n var pizza = new PizzaModel\r\n {\r\n Name = \"Name\",\r\n Ingredients = new List<string> {\"toppings\"}\r\n };\r\n\r\n \/\/ act\r\n var result = await _handler.MakePizza(pizza);\r\n\r\n \/\/ assert\r\n Assert.Equal(\"CreatedResult\", result.GetType().Name);\r\n}<\/pre>\nThere is a little quirkiness here because the
Results<\/code> class in minimal API is actually hidden behind private classes. The only way to get to the result type is via reflection, which is unfortunate because the unit test is not able to validate the strongly typed class. Hopefully in future LTS (Long Term Support) releases the team will fix this odd behaviour.<\/p>\nNow, write the MakePizza method in the PizzaHandler to pass the unit test:<\/p>\n
public async Task<IResult> MakePizza(PizzaModel pizza)\r\n{\r\n if (string.IsNullOrWhiteSpace(pizza.Name)\r\n || pizza.Ingredients.Count == 0)\r\n {\r\n return Results.ValidationProblem(new Dictionary<string, string[]>\r\n {\r\n {nameof(pizza), new [] \r\n {\"To make a pizza include name and ingredients\"}}\r\n });\r\n }\r\n\r\n pizza.Url = _slugHelper.GenerateSlug(pizza.Name);\r\n\r\n await _context.SaveAsync(pizza);\r\n _logger.LogInformation($\"Pizza made! {pizza}\");\r\n\r\n return Results.Created($\"\/pizzas\/{pizza.Url}\", pizza);\r\n}<\/pre>\nWith minimal API, you simply return an
IResult<\/code>. TheResults<\/code> class supports all the same behaviour you are already familiar with from theBaseController<\/code> class. The one key difference is there is a lot less bloat here which is ideal for a lambda function that runs on the AWS cloud.<\/p>\nFinally, go back to the
Program.cs<\/code> file and add new endpoints right before theapp.Run<\/code>.<\/p>\nusing (var serviceScope = app.Services.CreateScope())\r\n{\r\n var services = serviceScope.ServiceProvider;\r\n var pizzaApi = services.GetRequiredService<PizzaHandler>();\r\n\r\n app.MapPost(\"\/pizzas\", pizzaApi.MakePizza);\r\n app.MapGet(\"\/pizzas\/{url}\", pizzaApi.TastePizza);\r\n}<\/pre>\nOne nicety from minimal API is how well this integrates with the existing IoC container. You can map requests to a method, and the model binder does the rest. Those of you familiar with Controllers should see code that reads identical in the
PizzaHandler<\/code>.<\/p>\nThen, make sure the dotnet watcher CLI tool is running the latest code and test your endpoint via CURL:<\/p>\n
> curl -X POST -i -H \"Accept: application\/json\" ^\r\n -H \"Content-Type: application\/json\" ^\r\n -d \"{\\\"name\\\":\\\"Pepperoni Pizza\\\",\\\"ingredients\\\":[\\\"tomato sauce\\\",\\\"cheese\\\",\\\"pepperoni\\\"]}\" http:\/\/localhost:5095\/pizzas<\/pre>\nFeel free to play with this endpoint on local. Notice how the endpoint is strongly typed, if you pass in a list of ingredients as raw numbers then validation fails the request. If there is data missing, validation once again kicks the unmade pizza back with a failed request.<\/p>\n
You may be wondering how the app running on local is able to talk to DynamoDB. This is because the SDK picks up the same credentials used by the AWS CLI tool. If you can access resources on AWS, then you are also able to point to DynamoDB using your own personal account with C#.<\/p>\n
Taste a Pizza<\/h2>\n
With a fresh pizza made, time to taste the fruits of your labor.<\/p>\n
In the
PizzaHandlerTests<\/code> class, add this unit test:<\/p>\n[Fact]\r\npublic async Task TastePizzaOk()\r\n{\r\n \/\/ arrange\r\n _context\r\n .Setup(m => m.LoadAsync<PizzaModel?>(\"url\", default))\r\n .ReturnsAsync(new PizzaModel());\r\n\r\n \/\/ act\r\n var result = await _handler.TastePizza(\"url\");\r\n\r\n \/\/ assert\r\n Assert.Equal(\"OkObjectResult\", result.GetType().Name);\r\n}<\/pre>\nThis only checks the happy path; you can add more tests to check for failure scenarios and increase code coverage. I\u2019ll leave this as an exercise to you the reader, if you need help, please check out the GitHub repo.<\/p>\n
To pass the test, put in place the
TastePizza<\/code> method inside thePizzaHandler<\/code>:<\/p>\npublic async Task<IResult> TastePizza(string url)\r\n{\r\n var pizza = await _context.LoadAsync<PizzaModel?>(url);\r\n\r\n return pizza == null\r\n ? Results.NotFound()\r\n : Results.Ok(pizza);\r\n}<\/pre>\nThen, test this endpoint via CURL:<\/p>\n
> curl -X GET -i -H \"Accept: application\/json\" http:\/\/localhost:5095\/pizzas\/pepperoni-pizza<\/pre>\n
Onto the Cloud!<\/h2>\n
With a belly full of pizza, I hope nobody feels hungry, deploying this to the AWS cloud feels seamless. The good news is that the template already does a lot of the hard work for you so you can focus on a few key items.<\/p>\n
First, tweak the
serverless.template<\/code> file and set the memory and CPU allocation. Do this in the JSON file:<\/p>\n{\r\n \"Properties\": {\r\n \"MemorySize\": 2600,\r\n \"Architectures\": [\"x86_64\"]\r\n }\r\n}<\/pre>\nThis sets a memory allocation of 2.5GB, with a x86 processor. These allocations are not final because you really should do monitoring and tweaking to figure out an optimal allocation for your lambda function. Increasing the memory blindly does not guarantee best results, luckily there is a nice guide from AWS<\/a> that is very helpful.<\/p>\n
Before you can deploy, you\u2019ll need to create an S3 bucket which is where the deploy bundle will go. Note that you may need to provide your own name for the S3 bucket:<\/p>\n
> aws s3api create-bucket --acl private --bucket pizza-api-upload \\\r\n --region us-east-1 --object-ownership BucketOwnerEnforced\r\n> aws s3api put-public-access-block --bucket pizza-api-upload \\\r\n --public-access-block-configuration \"BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true\"<\/pre>\n
Then, deploy your app to the AWS cloud via the dotnet AWS tool:<\/p>\n
> dotnet lambda deploy-serverless --stack-name pizza-api --s3-bucket pizza-api-upload<\/pre>\n
Unfortunately, the
dotnet lambda<\/code> deploy tool does not handle role policies for DynamoDB automatically. Login into AWS, go to IAM, click on roles, then click on the role the tool created for your lambda function. It should be under a logical name likepizza-api-AspNetCoreFunctionRole-818HE2VECU1J.<\/code><\/p>\nThen, copy this role name, and create a file
dynamodb.json<\/code> with the access rules:<\/p>\n{\r\n \"Version\": \"2012-10-17\",\r\n \"Statement\": [\r\n {\r\n \"Action\": [\r\n \"dynamodb:DescribeTable\",\r\n \"dynamodb:GetItem\",\r\n \"dynamodb:PutItem\",\r\n \"dynamodb:UpdateItem\"\r\n ],\r\n \"Effect\": \"Allow\",\r\n \"Resource\": \"*\"\r\n }\r\n ]\r\n}<\/pre>\nNow, from the Pizza.Api project folder, grant role access to DynamoDB via this command:<\/p>\n
> aws iam put-role-policy --role-name pizza-api-AspNetCoreFunctionRole-818HE2VECU1J \\\r\n --policy-name PizzaApiDynamoDB --policy-document file:\/\/.\/dynamodb.json<\/pre>\n
Be sure to specify the correct role name for your lambda function.<\/p>\n
Finally, taste a pre-made pizza via CURL. Note that the dotnet lambda deploy tool should have responded with a URL for your lambda function. Make sure the correct
GATEWAY_ID<\/code> andREGION<\/code> go in theURL<\/code>.:<\/p>\n> curl -X GET -i ^\r\n -H \"Accept: application\/json\" https:\/\/GATEWAY_ID.execute-api.REGION.amazonaws.com\/Prod\/pizzas\/pepperoni-pizza<\/pre>\n
I recommend poking around in AWS to get more familiar with lambda functions.<\/p>\n
The API Gateway runs the lambda function via a reverse proxy. This routes all HTTPS traffic directly to the kestrel host, which is the same code that runs on local. This is a bit more costly because the lambda function routes all traffic, but the developer experience is greatly enhanced by this. Go to S3 and find your pizza-api-upload bucket, notice the bundle size remains small, around 2MB. The dotnet AWS tool might be doing some trimming to keep cold starts low. Also, look at CloudWatch<\/a> and check the logs for your lambda function. You will find cold starts in general are below .5 sec, this is great news! In .NET 6, the AWS team has been able to make vast improvements which I believe will continue in future LTS releases. Lastly, note the VM that executes the lambda runs on Linux, this is another area of improvement that is also possible in .NET 6.<\/p>\n
Conclusion<\/h2>\n
AWS lambda functions with C# are now production ready. The teams from both Microsoft and AWS have made significant progress in .NET 6 to make this dream a reality.<\/p>\n
<\/p>\n","protected":false},"excerpt":{"rendered":"
Serverless computing is pushing C# to evolve to the next level. This is exciting because you pay-per-use and only incur charges when the code is running. This means that .NET 6 must spin up fast, do its job, then die quickly. This mantra of birth and rebirth pushes developers and the underlying tech to think……<\/p>\n","protected":false},"author":274017,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[137092,53],"tags":[],"coauthors":[41241],"class_list":["post-95401","post","type-post","status-publish","format-standard","hentry","category-aws","category-featured"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/95401","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/users\/274017"}],"replies":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/comments?post=95401"}],"version-history":[{"count":4,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/95401\/revisions"}],"predecessor-version":[{"id":95407,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/95401\/revisions\/95407"}],"wp:attachment":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media?parent=95401"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/categories?post=95401"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/tags?post=95401"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/coauthors?post=95401"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}