DEV Community: Saeed Ghanavat

Lambda Cold Starts Are Not the Whole Story: How I Took a .NET API from ~2s to <1s with SnapStart

Saeed Ghanavat — Fri, 26 Jun 2026 00:00:00 +0000

With APIs gaining popularity on a daily basis, and with countless ways to host them, the cost of running APIs remains tightly coupled to how you design the architecture of your application.

If cost is a factor you want to get right, then you need to revisit the architecture of your application and understand the trade-offs you are making. One of my favourite cloud architecture approaches is serverless architecture.

There are many serverless or serverless-style services on AWS. Some examples are:

API Gateway
Lambda
DynamoDB
S3
SQS
Fargate

And many more.

Serverless does not mean there are no servers. Come on 😁. It means there are no servers for you to provision, patch, operate, or babysit. There are obviously servers under the hood. They are just managed by AWS.

In this article, I am going to focus on a real problem I encountered while building my AWS Clean Architecture Starter Kit: latency with Lambda APIs after inactivity.

This is not theory. I tested it, broke it down, got misled by some numbers, corrected the measurements, and eventually got the API below 1 second after inactivity.

ECS

One of the best ways to host your application backend is containerisation. I am not going to go deep into how to deploy to ECS in this article. That is not the point here.

The point is to compare the architectural trade-off between running an API continuously in containers versus running it on demand with Lambda.

ECS supports two common ways to run containers:

ECS on EC2
ECS on Fargate

Let’s not argue about EC2. We all know EC2 is not serverless. But what about Fargate?

AWS calls Fargate a serverless compute engine for containers. Fair enough. You do not provision or manage the underlying compute infrastructure. However, from an application architecture point of view, I still do not treat ECS/Fargate as the same kind of serverless experience as Lambda.

Why?

Because with ECS/Fargate, you still manage important parts of the container architecture:

task definitions
ECS services
desired task count
deployment behaviour
scaling policies
container health checks
networking
load balancing

That is not a bad thing. It is just a different trade-off.

Applications running in ECS/Fargate generally continue running while your service maintains running tasks. You pay for those running tasks, even if the API is sitting there doing nothing. That may be perfectly acceptable for latency-sensitive APIs, but it is not the same cost model as Lambda.

And that is as much as I want to say about ECS in this article.

Lambda

On the other side, we have Lambda.

Lambda is much closer to the serverless model most people think about. You do not provision servers, you do not manage the runtime host, and you do not manually scale EC2 instances. Lambda handles the execution environment and scales horizontally as requests come in.

In my AWS Clean Architecture Starter Kit, I chose Lambda for the API hosting model. It is easy to deploy, easy to configure, and easy to connect to API Gateway using CDK.

But in architecture, nothing is free.

You always pay somewhere.

With Lambda, one of the things you need to understand properly is cold start latency.

Lambda Cold Starts

One of the important aspects of serverless architecture is how the service behaves when it has not been used for a while.

With Lambda, AWS may reuse an existing execution environment for later invocations. But after a period of inactivity, or when Lambda needs to scale out, there may be no warm execution environment ready for your request. In that case, Lambda has to prepare one.

That extra preparation time is what we call a cold start.

For a normal non-SnapStart Lambda cold start, the rough shape is:

Cold start path = Init Duration + Duration

For a SnapStart-restored Lambda invocation, the rough shape is:

SnapStart restored path = Restore Duration + Duration

Those fields matter. Client-side tools such as Postman or curl are useful, but they do not tell the full Lambda story on their own.

Response time in Cold Start

Cold starts also happen when a function is invoked for the first time or when Lambda has to create a new execution environment during scale-out.

This is the part you need to understand as an architect:

Can your API tolerate that first-request latency?

There is no universal answer. It depends on the workload.

For internal tools, admin APIs, low-traffic apps, event-driven workloads, and async workloads, Lambda can be an excellent fit.

For APIs that need consistently low p99 latency, especially after idle periods or during scale-out, you need to be more careful.

In my case, the endpoint was simple. It was a /api/people/{id} endpoint reading a record from DynamoDB. Nothing crazy. No heavy computation. No massive payload.

And yet, after inactivity, I was seeing responses around 2 seconds.

That was not acceptable enough for me to ignore.

So I investigated.

Lambda SnapStart

Lambda SnapStart is designed to improve startup performance by taking a snapshot of the initialised execution environment and restoring from that snapshot later.

In simple terms:

Lambda initialises your function.
Lambda takes a snapshot of memory and disk state.
Later, instead of doing a normal initialisation from scratch, Lambda restores from that snapshot.

That sounds like magic. It is not. It is engineering. And it still has trade-offs.

SnapStart applies to published versions. This part is critical.

If you enable SnapStart but keep invoking $LATEST, you are not testing SnapStart properly. You need to publish a version and invoke that version, usually through an alias such as dev, test, or prod.

SnapStart is enabled and will be on when next version published

Once a new version is published and SnapStart optimisation is complete, SnapStart shows as On for the published version.

SnapStart is on

But here is the mistake I nearly made:

Enabling SnapStart is not the same as optimising for SnapStart.

That distinction matters.

Measuring the Right Thing

At first, I tested with Postman. That was useful, but it was also misleading.

Postman response time includes more than the backend execution time. It can include:

socket initialisation
DNS lookup
TCP handshake
TLS handshake
waiting for first byte
download time
client-side processing

So I moved to curl to get cleaner timing breakdowns.

This is the command I used:

curl -s -H "x-api-key: your_api_key" -o /dev/null \
  -w "namelookup: %{time_namelookup}s\nconnect: %{time_connect}s\nappconnect: %{time_appconnect}s\npretransfer: %{time_pretransfer}s\nstarttransfer_ttfb: %{time_starttransfer}s\ntotal: %{time_total}s\n" \
  "https://apigatewayid.execute-api.eu-west-1.amazonaws.com/dev/api/people/person_id"

The key field was:

curl backend wait = starttransfer_ttfb - pretransfer

That gave me a better view of how long the client waited after the connection was ready.

But even curl was not enough on its own.

I also checked:

API Gateway Latency
API Gateway IntegrationLatency
Lambda Init Duration
Lambda Restore Duration
Lambda Duration
DynamoDB SuccessfulRequestLatency

That last one was important.

DynamoDB was not the problem.

Across the tests, DynamoDB SuccessfulRequestLatency stayed low: around 6–14 ms. The slow part was not the DynamoDB table. The slow part was the first SDK/network/runtime path from the restored Lambda environment.

Prepare your application for SnapStart

This is the part most people will miss.

I enabled SnapStart, published the version, wired the alias correctly, waited 5–6 minutes, tested again, and the response was still poor.

In fact, it was worse in one test.

That was annoying, but it was also useful.

It forced me to stop assuming and start measuring properly.

Memory Was a Bottleneck

My Lambda initially had 1024 MB memory.

That was not enough for this .NET Lambda API path.

I increased memory gradually:

1024 MB
1800 MB
2048 MB

The first jump made a meaningful difference, 1390 ms down from 2230 ms. The jump from 1800 MB to 2048 MB was smaller, but still worth testing. This time slight improvement down to 1200 ms.

This matters because Lambda memory is tied to CPU allocation. More memory gives your function more CPU capacity, which can help with .NET runtime work, JSON serialisation, AWS SDK work, TLS/signing, and framework overhead.

Hello World Warm-Up Was Not Enough

I found out that for .Net applications the JIT compilation and assembly loading time can also be a bottleneck. This was when I learned about runtime hooks, in particular RegisterBeforeSnapshot().

I then tried warming a hello-world endpoint before the snapshot.

That helped a bit, but it did not solve the real problem.

Why?

Because hello-world warmed the wrong path.

My real endpoint was:

/api/people/{id}

That endpoint exercised:

ASP.NET Core routing
minimal API path
handler resolution
repository logic
DynamoDB SDK
response mapping

A hello-world endpoint does not warm all of that.

So I changed the warm-up to target the real endpoint path.

builder.Services.AddAWSLambdaBeforeSnapshotRequest(
    new HttpRequestMessage(HttpMethod.Get, "api/people/00000000-0000-0000-0000-000000000001"));

I used a fixed diagnostic ID. Do not use random production data for this. Create a harmless diagnostic record that exists only to warm the path.

Also, do not warm endpoints that write data. That is asking for trouble.

The point is not to run business logic for its own sake. The point is to warm deterministic and reusable startup paths before Lambda creates the snapshot.

Important SnapStart Warning: Uniqueness

SnapStart snapshots initialised state.

That means you must be careful with anything generated during initialisation.

Do not generate these before the snapshot if they must be unique after restore:

request IDs
unique runtime IDs
secrets
random seeds
entropy used for security-sensitive randomness
per-request timestamps

If a value must be unique per request, generate it during the request.

If a value must be unique per restored execution environment, regenerate it after restore.

This is not a theoretical concern. It is part of using SnapStart correctly.

The Tests

I tested the same endpoint:

GET /api/people/{id}

I used three scenarios:

No SnapStart, no warm-up
SnapStart enabled, no warm-up
SnapStart enabled, with real-path warm-up

All timings below are normalised to milliseconds.

Test #1 — No SnapStart, No Warm-Up

This test gave me the baseline for a normal Lambda cold start without SnapStart.

Metric	Value
Endpoint	`/api/people/{id}`
Mode	No SnapStart, no warm-up
API Gateway IntegrationLatency	1300 ms
API Gateway Latency	1300 ms
API Gateway Overhead	0 ms
Lambda Init Duration	478.54 ms
Lambda Restore Duration	N/A
CloudWatch REPORT Duration	646.94 ms
CloudWatch Lambda Duration Metric	632.9 ms
DynamoDB SuccessfulRequestLatency	13.6 ms
curl pretransfer	119.031 ms
curl TTFB	1469.751 ms
curl total	1467 ms

The important number here is the Lambda-side total:

Init Duration + REPORT Duration = 1125.48 ms

So the backend cold path was already above 1 second before adding client-side/network overhead.

No SnapStart enabled and no warmup mechanism configured

Test #2 — SnapStart Enabled, No Warm-Up

This was the annoying one.

SnapStart was enabled. The function was published. The alias was pointing to the published version. CloudWatch showed Restore Duration.

So SnapStart was working.

But the API was not faster.

Metric	Value
Endpoint	`/api/people/{id}`
Mode	SnapStart enabled, no warm-up
API Gateway IntegrationLatency	1700 ms
API Gateway Latency	1700 ms
API Gateway Overhead	0 ms
Lambda Init Duration	N/A
Lambda Restore Duration	579.74 ms
CloudWatch REPORT Duration	993.37 ms
CloudWatch Lambda Duration Metric	993 ms
DynamoDB SuccessfulRequestLatency	11 ms
curl pretransfer	101 ms
curl TTFB	1829 ms
curl total	1830 ms

The key calculation:

Restore Duration + REPORT Duration = 1,573.11 ms

This was worse than the normal non-SnapStart cold start.

That is the part people need to understand.

SnapStart was technically working, but the application was not prepared properly for SnapStart. The first restored request still paid expensive first-use costs.

SnapStart enabled and no warmup mechanism configured

Test #3 — SnapStart Enabled, Real-Path Warm-Up

This is where the result finally became useful.

I kept SnapStart enabled, but added warm-up for the actual /api/people/{id} path before snapshot creation.

Metric	Value
Endpoint	`/api/people/{id}`
Mode	SnapStart enabled, real-path warm-up
API Gateway IntegrationLatency	733 ms
API Gateway Latency	733 ms
API Gateway Overhead	0 ms
Lambda Init Duration	N/A
Lambda Restore Duration	452.75 ms
CloudWatch REPORT Duration	169.07 ms
CloudWatch Lambda Duration Metric	169 ms
DynamoDB SuccessfulRequestLatency	6.6 ms
curl pretransfer	135 ms
curl TTFB	896 ms
curl total	896.8 ms

The key calculation:

Restore Duration + REPORT Duration = 621.82 ms

This was the result I was looking for.

The API response after inactivity dropped below 1 second from curl.

SnapStart enabled and with warmup mechanism configured

All tests aggregated

Here is the full comparison - a bit simplified to help with readability.

Mode	API Gateway Latency	Init / Restore Duration	REPORT Duration	Lambda Duration Metric	curl pretransfer	curl TTFB	curl total
No SnapStart, no warm-up	1300 ms	Init: 478.54 ms	646.94 ms	633 ms	119 ms	1469 ms	1467 ms
SnapStart, no warm-up	1700 ms	Restore: 579.74 ms	993.37 ms	993 ms	101 ms	1829 ms	1830 ms
SnapStart, real-path warm-up	733 ms	Restore: 452.75 ms	169.07 ms	169 ms	135 ms	896 ms	896.8 ms

The numbers are gathered from CloudWatch logs and API calls results via curl (last three).

Lessons learned

The biggest lesson was this:

SnapStart alone was not enough.

In my test, SnapStart without warm-up was worse than the normal non-SnapStart cold start.

That does not mean SnapStart is bad. It means I had not prepared the application properly.

The meaningful improvement came when I warmed the actual request path before the snapshot.

The latency was mainly coming from the Lambda cold/restore path, first-use application code, SDK/network setup, and framework/runtime costs.

Conclusion

Using Lambda to host APIs is exciting, cost-effective, and massively scalable. But it can be a poor choice if you use it blindly and ignore the cold start behaviour.

The lazy take is:

Lambda is bad for latency-sensitive APIs because after idle it can take 2 seconds.

That statement is incomplete.

In my opinion and after all my investigations:

Lambda can be poor for latency-sensitive APIs if you do not understand and optimise the cold/restore path.

In my case, the API did show around 2 seconds after inactivity. But the cause was not simply “Lambda is slow”.

The real causes were:

cold/restore startup cost
low memory allocation
first-use .NET/runtime costs
first-use AWS SDK/network path
warming the wrong endpoint path
measuring with client-side tools without separating backend time properly

After enabling SnapStart correctly, increasing memory, and warming the real /api/people/{id} path before snapshot creation, I got the response to sub-second after inactivity.

That is the real architectural takeaway.

Lambda is not the answer for every API. ECS/Fargate is still a very strong option, especially when you need consistently low latency and always-running services.

But Lambda is also not weak just because cold starts exist.

The truth is more boring and more useful:

You need to understand the trade-off, measure properly, and optimise the actual path your users hit.

No magic. No marketing fluff. Just architecture.

Integrating DynamoDB into Clean Architecture Wasn't as Simple as I Thought

Saeed Ghanavat — Thu, 18 Jun 2026 00:00:00 +0000

I thought integrating DynamoDB into my Clean Architecture solution would take an afternoon.

I already had repository abstractions.

I already had an EF Core implementation.

Surely I could swap the persistence layer and keep the rest of the architecture unchanged.

I was wrong.

Over the next two days I discovered that the hardest part wasn’t learning DynamoDB.

It was realising that my existing abstractions were built around assumptions that no longer held true.

I wanted to build a Clean Architecture solution hosted on AWS Lambda, deployed with CDK, and backed by DynamoDB.

Original architecture

What I had in mind was a focused and opinionated Clean Architecture solution built around serverless AWS services.

The architecture consisted of:

AWS Lambda hosting the API
API Gateway routing requests
DynamoDB providing persistence
AWS CDK managing infrastructure*

The codebase itself was intended to remain relatively simple:

Core containing entities and business rules
Infrastructure handling persistence concerns
IaC isolated in a dedicated CDK project

At this point I assumed the persistence technology could be swapped without affecting the architecture significantly.

It was also planned to use my small Repository Pattern package, Ghanavats.Repository, which I originally created to centralise common persistence functionality and hide implementation details behind simple abstractions.

Repository package

The purpose of the package was simple.

Hide persistence concerns behind common abstractions so the rest of the application remains unaware of the underlying database implementation.

The package currently provides implementations built around EF Core’s DbContext.

In theory, this should have made swapping persistence technologies easier.

In practice, it did not.

Why I thought it would work

My first instinct was to extend the existing Repository package and add DynamoDB support behind the same abstractions.

The idea seemed reasonable.

I already had abstractions such as:

public interface IRepository<T> : IReadRepository<T>
    where T : class

Why not provide another implementation?

The problem was that the abstractions had been designed around EF Core’s way of querying and working with data.

I spent a lot of time trying to force the existing abstractions to work.

The more I pushed in that direction, the more friction I created.

Some repository methods simply did not map cleanly to DynamoDB operations.

What looked like a generic abstraction was actually carrying assumptions from EF Core.

IAmazonDynamoDB vs DynamoDBContext

This was another point of confusion.

AWS provides multiple ways to interact with DynamoDB.

The two options I spent most of my time evaluating were:

IAmazonDynamoDB
DynamoDBContext

The low-level interface is exposed through IAmazonDynamoDB.

This API maps very closely to DynamoDB’s underlying operations and gives complete control over requests and responses.

A simplified example looks like this:

internal sealed class PeopleRepository : IPeopleRepository
{
    private readonly IAmazonDynamoDB _dynamoDb;

    public PeopleRepository(IAmazonDynamoDB dynamoDb)
    {
        _dynamoDb = dynamoDb;
    }

    public async Task<Person> GetPersonById(Guid personId)
    {
        var getItemRequest = new GetItemRequest
        {
            TableName = "Person",
            Key = new Dictionary<string, AttributeValue>
            {
                { "PersonId", new AttributeValue { S = personId.ToString("D") } }
            }
        };

        var result = await _dynamoDb.GetItemAsync(getItemRequest);

        var personIdMapped = result.Item["PersonId"].S;
        var somePropertyMapped = result.Item["SomeProperty"].S;

        var person = Person.Create(personIdMapped, somePropertyMapped);

        return person;
    }
}

While powerful, this approach introduces a lot of manual mapping code.

The alternative is DynamoDBContext.

This high-level interface acts as a wrapper around IAmazonDynamoDB and handles much of the mapping logic automatically.

A simplified example:

internal sealed class PeopleRepository : IPeopleRepository
{
    private readonly DynamoDBContext _dbContext;

    public PeopleRepository()
    {
        var clientConfig = new AmazonDynamoDBConfig
        {
            RegionEndpoint = RegionEndpoint.EUWest1
        };

        var client = new AmazonDynamoDBClient(clientConfig);

        _dbContext = new DynamoDBContextBuilder()
            .WithDynamoDBClient(() => client)
            .Build();
    }

    public async Task<Person> GetPersonById(Guid personId)
    {
        var result = await _dbContext.LoadAsync<DynamoDbPerson>(personId.ToString("D"));
        return result.ToDomain();
    }
}

After experimenting with both approaches, DynamoDBContext felt like the better fit for the starter kit.

Mapping challenge

This is where things became interesting.

With EF Core, I typically keep persistence concerns out of the domain and configure mappings through the Fluent API inside DbContext.

DynamoDBContext takes a different approach.

Entities need to be decorated with attributes so DynamoDB knows how to map them correctly.

Examples include:

DynamoDBTable
DynamoDBHashKey
DynamoDBProperty

Adding these attributes directly to my domain entities would have introduced a dependency from the Core layer to the AWS SDK.

That would violate one of the design principles I wanted the template to enforce.

The challenge was no longer DynamoDB itself.

The challenge was introducing DynamoDB without leaking AWS-specific concerns into the Core layer.

Persistence model solution

Eventually I stopped fighting the SDK.

I decided to:

Use DynamoDBContext
Implement a dedicated repository in Infrastructure
Keep the domain model unchanged
Introduce a dedicated persistence model for DynamoDB mapping

Rather than forcing DynamoDB to fit my existing Repository package, I introduced a DynamoDB-specific persistence model.

Example:

[DynamoDBTable("People")]
internal sealed class DynamoDbPerson
{
    [DynamoDBHashKey]
    public string PersonId { get; init; } = string.Empty;

    [DynamoDBProperty]
    public string Name { get; init; } = string.Empty;

    [DynamoDBProperty]
    public string Email { get; init; } = string.Empty;

    [DynamoDBProperty]
    public string Phone { get; init; } = string.Empty;

    [DynamoDBProperty]
    public string DateOfBirth { get; init; } = string.Empty;
}

This allowed the Infrastructure layer to own all DynamoDB-specific concerns while keeping the Core project free from AWS dependencies.

To recreate domain entities from persistence models, I introduced a hydration factory:

public static Person Rehydrate(
    Guid id,
    string name,
    string email,
    string phone,
    string dateOfBirth)
{
    return new Person(id, name, email, phone, dateOfBirth);
}

And a mapper:

internal static class PersonMapper
{
    extension(DynamoDbPerson? source)
    {
        public Person? ToDomain()
        {
            if (source is null)
            {
                return null;
            }

            return Person.Rehydrate(
                Guid.Parse(source.PersonId),
                source.Name,
                source.Email,
                source.Phone,
                source.DateOfBirth);
        }
    }
}

The final design ended up being much simpler than my original approach.

Instead of introducing AWS-specific dependencies into the Core layer, I created a dedicated persistence model in Infrastructure and mapped it to the domain entity.

This implementation is now part of the AWS Clean Architecture Starter Kit and will likely evolve as I gain more experience with DynamoDB.

Lessons learned

Not every abstraction survives a change in persistence technology.

I expected my repository package to hide DynamoDB in the same way it hid EF Core. In reality, DynamoDB introduces different access patterns and assumptions.

Clean Architecture is more about dependency direction than specific technologies.

The biggest challenge was not DynamoDB itself. It was preventing AWS-specific concerns from leaking into the Core layer.

Sometimes a dedicated implementation is simpler than a generic abstraction.

I spent a considerable amount of time extending an existing repository package before realising a small, focused DynamoDB implementation was easier to understand and maintain.

Persistence models and domain models do not always have to be the same thing.

Introducing a DynamoDB-specific persistence model allowed me to keep the domain clean while still benefiting from DynamoDBContext and its attribute-based mapping.

Conclusion

If I were starting this implementation again today, I would still choose DynamoDBContext and a dedicated persistence model.

The solution ended up being much simpler than the repository abstraction I originally tried to preserve.

Sometimes the best architectural decision is not finding a way to keep an abstraction alive.

Sometimes it is recognising when it no longer fits the problem you are trying to solve.

Stop Recreating .NET Solutions From Scratch

Saeed Ghanavat — Sun, 14 Jun 2026 00:57:00 +0000

I have been there myself, so I am not preaching to you.

I have spent far too much time building new .NET solutions from scratch. Actually, that is not completely true. Most of the time, I was not starting from scratch. I was copying from the first solution I built, or the second one, or the third one, then modifying it again for the fourth or fifth project.

It worked, but it was painful.

The worse part is that when you get used to a painful method, it starts to feel normal. Then normal becomes a habit. Then the habit becomes stubborn. Before you know it, you are defending a bad workflow just because you have repeated it enough times.

That was my mistake.

Every time I wanted to start a new API or SaaS-style project, I would spend time thinking about the same things again:

project structure
configuration
OpenAPI
health checks
authentication and authorisation
logging
testing setup
architecture tests
maybe .NET Aspire
all the other boring but important moving parts

None of these things are useless. They matter. A good solution needs structure.

But doing the same setup manually again and again is not engineering. It is waste.

Copy and paste is not a real template

There is nothing wrong with learning by manually creating a few solutions. In fact, you probably should do that at the beginning. It helps you understand what is actually inside your application.

The problem starts when you already know your preferred setup, but you still keep copying old projects and cleaning them up by hand.

That’s why I wrote this article. Believe me, things will go messy if you don’t change your approach.

You copy an old solution. Then you rename projects. Then you fix namespaces. Then you remove old features. Then you update package versions. Then you change configuration files. Then you realise you forgot something. Then you discover some random leftover name from the previous project.

That is not a clean starting point. That is a recycled accident.

A proper template gives you a repeatable way to generate a clean starting point. The .NET CLI uses the Microsoft Template Engine behind dotnet new to create projects and artifacts based on templates and options.

Microsoft already gave us the tool

Microsoft Template Engine is not some obscure trick. It is the system behind dotnet new.

You can use existing templates, install template packages, create your own templates, and generate projects from them. Microsoft’s documentation explains that .NET templates can generate projects, files, and resources, and template packages can be installed from NuGet, a NuGet package file, or a file system directory.

How cool is that?

That means your standard API setup does not need to live as a half-forgotten GitHub repository that you copy every few months.

It can become a template.

For example, instead of manually rebuilding the same solution structure, you could have something like:

dotnet new install MySolution.Templates
dotnet new mysolution-api -n MyNewApi

Then your solution is generated with the structure and defaults you already decided are useful.

What should go into a good .NET template?

A useful template should not be a dumping ground for every idea you have ever had.

That is another mistake.

The goal is not to create a “perfect enterprise solution” before the project even starts. That usually leads to over-engineering. The goal is to create a sensible baseline that saves time without forcing unnecessary complexity.

For an API template, I would consider including:

a clean solution and project structure
sensible naming
OpenAPI setup
health checks
logging configuration
basic validation setup
test projects
architecture test project
common configuration files
optional authentication setup
optional .NET Aspire support, if it genuinely helps

Microsoft’s template system supports replacing values, including and excluding files, and custom processing during template generation, so you can make templates flexible instead of hard-coding everything.

The real benefit is not speed

When you create projects manually, every solution slowly becomes different. One has health checks. One does not. One has better logging. One has outdated package references. One has tests in a different structure. One has old naming conventions.

That inconsistency becomes expensive later.

A template forces you to make decisions once, improve them over time, and reuse them properly.

That is how you turn experience into a tool.

Honest tip

Don’t do this too early.

If you have only built one solution, you probably do not have a template yet. You have an experiment.

Build manually a few times. Learn what repeats. Learn what is actually useful. Learn what you keep deleting. Then create a template from the parts that survive.

How to create a simple .NET solution template

Here is the part that confused me at first.

Microsoft’s documentation explains custom templates, but the examples are mostly based around item templates, project templates, and packaging templates. That is useful, but it can make the process look more complicated than it needs to be when your actual goal is simple:

I already have a full .NET solution structure I like. I want to reuse it.

You do not need to start with a strange folder structure such as working, content, and separate test folders just because a tutorial uses that approach.

You can start with a real solution.

Build the solution the way you actually want future projects to look.

For example:

TemplateSolution/
│
├── TemplateSolution.sln
│
├── src/
│ ├── TemplateSolution.Api/
│ ├── TemplateSolution.Application/
│ ├── TemplateSolution.Domain/
│ └── TemplateSolution.Infrastructure/
│
├── tests/
│ ├── TemplateSolution.UnitTests/
│ └── TemplateSolution.ArchitectureTests/
│
└── .template.config/
    └── template.json

The important part is this:

.template.config/template.json

That folder should sit at the root of your template, next to the .sln file.

Microsoft’s documentation confirms that the template.json file belongs inside a .template.config folder at the root of the template, and that the template source files can be whatever files and folders you want the template engine to use.

Step 1: Create your normal solution

Create your solution exactly how you like it.

But be careful.

A template should include repeatable foundations, not every random idea you once thought was clever.

Also remove junk before turning it into a template, or use .gitignore. Do not include secrets. Do not include real connection strings. Do not include environment-specific rubbish. That mistake is not “template engineering”; it is negligence.

Step 2: Use a clear placeholder name

Pick a source name that appears everywhere in the solution.

For example TemplateSolution. Then use it in:

TemplateSolution.sln
TemplateSolution.Api
TemplateSolution.Application
TemplateSolution.Domain
TemplateSolution.Infrastructure

This matters because the template engine can replace the configured sourceName with the name provided by the user when they run dotnet new. Microsoft documents sourceName as the value the template engine searches for in file names and file contents, replacing it with the name passed through -n or --name.

So later, when someone runs this:

dotnet new my-api -n Orders

The template engine can replace TemplateSolution with Orders.

That is the bit that saves you from painful renaming.

Step 3: Add `.template.config/template.json`

At the root of the solution, create this folder:

.template.config

Inside it, create this file:

template.json

Put the following in as a starting point. This is more complicated than the one in Microsoft documentation. I needed a few more salt and pepper such as the ability to restore NuGet packages, language name and template type:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "You Name",
  "classifications": [
    "Common",
    "WebApi",
    "ClassLibrary",
    "xUnit"
  ],
  "name": "Ghanavats AWS Clean Architecture Starter Kit Template",
  "description": "A deployable .NET Clean Architecture template featuring AWS Lambda, API Gateway, DynamoDB and Infrastructure as Code using AWS CDK.",
  "identity": "Ghanavats.CleanArchitecture.Template",
  "shortName": "ghanavats_aws_cleanarc_starter",
  "tags": {
    "language": "C#",
    "type": "solution"
  },
  "sourceName": "Ghanavats.CleanArchitecture",
  "preferNameDirectory": true,
  "primaryOutputs": [
    {
      "path": "Ghanavats.CleanArchitecture.sln"
    }
  ],
  "postActions": [
    {
      "actionId": "210D431B-A78B-4D2F-B762-4ED3E3EA9025",
      "description": "Restore NuGet packages required by this project.",
      "condition": "(!skipRestore)",
      "continueOnError": true,
      "manualInstructions": [
        {
          "text": "Run 'dotnet restore'"
        }
      ]
    }
  ]
}

The $schema value is useful because editors that support JSON schemas can provide validation and IntelliSense. This helped me a lot because I was not guessing every property manually. Microsoft also documents this schema field and explains that the full schema is available through JSON Schema Store.

The most important values are:

shortName
sourceName
identity
name

shortName is what you type in the CLI.

dotnet new my-api-template

sourceName is the placeholder name that gets replaced:

TemplateSolution

identity should be unique.

name is the friendly display name.

Step 4: Install the template locally

Open a terminal at the root of your solution, where the .sln file and .template.config folder are.

Then run:

dotnet new install ./

The dotnet new install command installs a template package from a path or NuGet package ID. For local development, installing from the current folder is enough.

Then check that your template is available:

dotnet new list

You should see your template listed with the short name you configured.

Step 5: Generate a new solution from your template

Now test it properly.

Go to a different folder and run:

dotnet new my-api-template -n OrdersService

That should generate a new solution based on your template.

Then build it, please. You don’t want a broken code generated off of your template.

dotnet build

Step 6: Improve the template over time

Your first version will probably not be perfect.

That is fine.

Use it. Find what feels wrong. Remove unnecessary things. Add missing things. Keep improving the baseline. This is exactly what I did.

When you change the template and need to reinstall it, you can uninstall and install it again:

dotnet new uninstall ./
dotnet new install ./

This is where the value starts to show.

Instead of improving one project and forgetting to copy the improvement elsewhere, you improve the template. Then every new project starts from a better place.

That is it.

The hard part is not the tooling. The hard part is deciding what your standard solution should look like.

And that is exactly why templates are useful. They force you to stop rebuilding the same foundation again and again, and they turn your repeated decisions into something reusable.

AWS Clean Architecture Starter Kit

Saeed Ghanavat — Wed, 10 Jun 2026 00:00:00 +0000

A practical .NET Clean Architecture starter kit for building and deploying serverless APIs on AWS.

What Is It?

The AWS Clean Architecture Starter Kit is a deployable .NET solution template that combines Clean Architecture with AWS serverless services.

The project provides a starting point for developers who want to build APIs on AWS without spending days configuring infrastructure and boilerplate code.

The starter kit currently includes:

Clean Architecture template
ASP.NET Core Minimal API
AWS Lambda
Amazon API Gateway
Amazon DynamoDB
Amazon CloudWatch Logging
AWS CDK Infrastructure as Code
OpenAPI Documentation
FluentValidation
Health Checks
Unit Tests
Architecture Tests

Why I Built It

As a software engineer and AWS Solutions Architect, I found that creating a new AWS-backed API often required significantly more work on infrastructure than on the API itself.

Packaging Lambda functions, configuring API Gateway, managing permissions, creating infrastructure with CDK, and integrating AWS services all take time.

I wanted a practical foundation that developers could use as a starting point rather than repeatedly solving the same problems from scratch.

This starter kit is my attempt to simplify that process while documenting the lessons learned along the way.

Who Is It For?

This project is intended for:

.NET developers learning AWS
Developers building serverless applications
Small teams needing a starting point
Engineers looking for practical AWS CDK examples
Developers interested in Clean Architecture

It is not intended to be a framework or a complete enterprise platform.

Architecture

Key Design Decisions

AWS Lambda Instead of ECS

The starter kit uses AWS Lambda as the primary hosting model.

Lambda reduces operational overhead, scales automatically, and is often a cost-effective option for APIs with variable traffic patterns.

Infrastructure as Code Using AWS CDK

All infrastructure is provisioned using AWS CDK.

The goal is to allow developers to create, modify and deploy infrastructure without manual AWS Console configuration.

DynamoDB as the Default Data Store

DynamoDB was selected as the default persistence layer because it integrates naturally with serverless workloads and removes the operational burden of managing database servers.

V1 intentionally keeps the data model simple by using a single partition key.

API Gateway API Keys

API Gateway API Keys provide a lightweight mechanism for controlling access and applying usage plans.

The API itself does not validate API Keys. Validation is performed by API Gateway before requests are forwarded to AWS Lambda.

Getting Started

Install the template
Create a new solution
Configure AWS credentials
Bootstrap CDK
Deploy the infrastructure
Start building

Detailed setup instructions are available in the GitHub repository.

Source Code

The source code is available on GitHub.

AWS Clean Architecture Repository

Related Projects

Ghanavats.ResultPattern

The starter kit includes usage examples based on Ghanavats.ResultPattern.

ResultPattern provides a lightweight approach to modelling success and failure outcomes without relying on exceptions for expected application behaviour.

Although many similar libraries exist, I continue to maintain and use this package because it aligns with how I structure application and domain logic.

ResultPattern Repository

Roadmap

Planned improvements include:

Authentication and authorisation
Additional AWS integrations
CI/CD examples
Advanced DynamoDB modelling
Event-driven architecture examples

Feedback

The project is actively evolving.

Feedback, suggestions and contributions are welcome.

Migrate from AWS WorkMail to Microsoft Exchange and take your emails with you!

Saeed Ghanavat — Wed, 03 Jun 2026 05:22:42 +0000

AWS WorkMail is being retired, with end of support scheduled for 31 March 2027. I have been using it as my personal mail server since I began my AWS journey, so this was not something I wanted to ignore until the last minute.

This article is specific to AWS WorkMail , not Amazon SES. SES is a separate service and, at the time of writing, this retirement announcement is about WorkMail only.

Why I migrated

The main reason is obvious: WorkMail is being retired, so I needed to move away from it.

I also had another reason. In my opinion, AWS WorkMail had a basic UI with basic capabilities. To be fair, that was mostly all I needed. But for my personal setup it was not particularly cheap. I was paying for the WorkMail organisation and each mailbox had its own monthly cost. In total, I was paying around $30 per month.

When AWS announced the retirement, I wanted to act early. I did not want to leave it until the last minute and then rush the migration under pressure. It also gave me a good reason to review whether I could run my personal email setup in a cheaper and cleaner way.

What needed to be planned

The first thing I needed was an alternative.

After some investigation and comparing the pros and cons of a few options, I decided to use Microsoft Exchange Online. Some may say it is overkill for a personal email setup. I would say it is sustainable, affordable for my use case, feature rich, and easy enough to set up.

Below is the list I used to plan the migration:

Domain ownership verification
MX record reconfiguration
Email migration from AWS WorkMail to Exchange Online
How to reduce cost when creating mailboxes
How many licensed mailboxes I actually needed
User downtime risk and how to minimise it
What to test before and after the cutover

DNS and domain considerations

I decided to keep my domain in AWS Route 53. I also avoided removing any existing DNS records too early because I did not want to risk losing emails in flight.

After setting up the new Microsoft Exchange Online subscription, I was able to verify ownership of my domain fairly quickly. This gave me room to manoeuvre. I could create the mailboxes, aliases, and shared mailboxes I needed before touching the MX records.

At the beginning, the DNS and domain side was straightforward. I only had to revisit it properly once I was ready to complete the cutover and point the MX records to Exchange Online.

Mailbox/user considerations

I decided to use only two licensed users: my account and my wife’s account. Only the two of us needed separate personal mailboxes.

For everything else, I used aliases and shared mailboxes.

I created a handful of aliases under my own user mailbox. I like doing this because it gives me a meaningful separation of email addresses without creating unnecessary paid mailboxes.

For emails that both of us need to manage, I created a few shared mailboxes and gave both of us access to read and manage them. When you create shared mailboxes in Exchange Online, Microsoft 365 creates the necessary underlying account objects. In my case, that was not an issue because the shared mailboxes were tied to the main licensed accounts for access and management.

To give a better picture of what I ended up with, this is a simplified version:

My licensed account
- Alias 1
- Alias 2
- Alias 3
- Access to all shared mailboxes
My wife’s licensed account
- Access to all shared mailboxes
Shared mailbox 1
Shared mailbox 2
Shared mailbox 3

This reduced the number of paid accounts and made the setup easier to manage.

Cutover approach

The best approach I could think of was to set up all the mailboxes, shared mailboxes, and aliases I needed first, then leave AWS WorkMail in place until the end of the process. I wanted to continue receiving emails for as long as possible before changing the MX records.

I then investigated how to migrate my existing emails from AWS WorkMail to Exchange Online. After around two hours of reading, testing, and trial and error, I landed on the migration tool inside the Exchange Admin Center. The migration type I needed was IMAP migration.

The Exchange Admin Center has a migration batch tool that lets you migrate mailboxes from different sources. In my case, I only needed IMAP migration.

Setting up access to my AWS WorkMail mailboxes from the Exchange IMAP migration tool took longer than I first expected. The tool requires a CSV file with the mailbox details. Yes, this includes passwords in plain text. It is what it is, but treat that file carefully and delete it when you no longer need it.

To save time and reduce pain, the CSV format must look like this:

EmailAddress,UserName,Password
myuser1@mydomain.co.uk,myuser1@mydomain.co.uk,mysuperstrongpassword
myuser2@mydomain.co.uk,myuser2@mydomain.co.uk,myevenstrongerpassword
myuser3@mydomain.co.uk,myuser3@mydomain.co.uk,someonessuperstrongpassword

Note that the values under EmailAddress and UserName are the same in this example. AWS WorkMail did not like me using only the username. It expected the full email address as the username.

After uploading the CSV file with all the source mailboxes listed, I was able to migrate and sync the emails from AWS WorkMail into the new Exchange Online mailboxes. The migration report showed the number of synced emails from the source. The migration brought across the inbox, sent items, and my custom folders.

Shared mailboxes can be added to the Outlook client app and appear under the main account. For Mac users, I had to add the shared mailbox through the legacy Outlook UI first, then switch back to the new UI. Adding the shared mailbox directly from the new Outlook UI did not work for me.

At this stage I had not reconfigured the MX records with the new Exchange Online details. Everything was still untouched in AWS WorkMail.

Testing before and after

Once the migration was done, I went back to the Exchange Admin Center and continued the email setup. Microsoft gave me the DNS records I needed to add, including the new MX record.

In AWS Route 53, I had to delete the existing MX record because editing it directly did not work cleanly for me. I did this quickly and carefully. In less than 10 minutes, the new records were in place and AWS WorkMail was no longer receiving new inbound email for the domain.

I then logged into my own mailbox and did a sanity check against the migrated data. To my surprise, because I had never done this before, things looked accurate. The migrated emails were there and the folders looked right.

For testing, I would recommend checking at least the following:

Send an email from an external address to the new mailbox
Send an email from Exchange Online to an external address
Test replies, not just new messages
Check aliases
Check shared mailboxes
Check Outlook desktop/mobile client access
Check that old WorkMail mailboxes are no longer receiving new messages after the MX cutover

Mistakes or risks to avoid

I made a funny and expensive mistake when I first set up my email server in AWS WorkMail. I created a separate user account and a completely separate mailbox for almost every purpose.

I had my personal one, then another one for my wife, then another for family stuff, then another for something else, and then repeated that a few more times.

That approach is fine for millionaires who are not bothered about spending an extra $15 or $20 per month for a personal email server. For me, however, it was expensive. I am not financially free yet!

I did not make the same mistake again in my new Exchange Online subscription. I became best friends with aliases, shared mailboxes, and Outlook rules to move emails into the right folders. It is cheaper, easier to maintain, and has less configuration overhead.

Another risk is treating the migration like it is just a technical copy job. It is not. Email is boring until it breaks. If you are doing this for a business, even a small one, you need to think about downtime, DNS propagation, user access, shared mailboxes, and rollback options.

IMAP migration under the hood

An IMAP migration is best understood as a controlled mailbox copy.

Exchange Online does not magically move the mailbox from the source server. Instead, Microsoft 365 connects to the source mail server using IMAP, authenticates against each mailbox, reads the available mail folders, pulls the messages from those folders, and then writes them into the target Exchange Online mailbox.

For this to work, the target users and mailboxes must already exist in Microsoft 365 before the migration starts. The migration endpoint stores the source IMAP server connection details, and the migration batch uses the CSV mapping file to know which source mailbox maps to which target mailbox.

It is a simple and direct server-to-server copy process.

One important limitation: IMAP migration is mainly about email messages and mail folders. It does not migrate everything that exists in a full groupware mailbox. Contacts, calendar items, and tasks are not migrated through IMAP, so those need to be handled separately if they matter to you. This is easy to overlook because users often think of a mailbox as email, calendar, contacts, and settings all together. IMAP does not cover all of that.

Final thoughts

I found the process fairly straightforward, apart from the trial and error around the mailbox CSV file. If I had known the correct CSV format earlier, the whole process would have been much simpler.

For my small personal setup, I did not need a separate archive or backup workflow. I also avoided adding anything unnecessary around SES archiving or journaling because it would have added cost and complexity I did not need.

The key point is this: IMAP migration is not just a button-click task. It is a staged copy-and-cutover process. The mailbox data copy, DNS changes, user communication, Outlook reconfiguration, and final verification all need to be planned together.

The technical migration may be IMAP, but the real success factor is controlling disruption for the users.

If you encounter issues during the sync process, take a look at the Microsoft troubleshooting guide for IMAP mailbox migration.

What I would do differently next time

Next time, I would prepare the CSV file earlier and test it with one mailbox first. That would have saved me time and removed most of the guesswork.

I would also create a simple mailbox inventory before starting. Nothing complicated, just a small table showing each source mailbox, the target mailbox, whether it is licensed or shared, and whether it has aliases. For a personal migration this may feel unnecessary, but even a small checklist helps when DNS, passwords, mailboxes, and clients are all involved.

I would reduce the DNS TTL in advance where possible, then wait before doing the MX cutover. That gives you a better chance of a quicker and cleaner switch when you are ready.

For a larger or business-critical migration, I would also keep the migration batch running a little longer after the MX cutover and perform a final sync/validation before fully shutting down the old system. I got away with a simple process because my setup was small. I would not treat a business migration casually.

The biggest lesson is simple: do the boring preparation properly. The migration tool does the copy, but planning avoids the panic.

DEV Community: Saeed Ghanavat

Lambda Cold Starts Are Not the Whole Story: How I Took a .NET API from ~2s to <1s with SnapStart

ECS

Lambda

Lambda Cold Starts

Lambda SnapStart

Measuring the Right Thing

Prepare your application for SnapStart

Memory Was a Bottleneck

Hello World Warm-Up Was Not Enough

Important SnapStart Warning: Uniqueness

The Tests

Test #1 — No SnapStart, No Warm-Up

Test #2 — SnapStart Enabled, No Warm-Up

Test #3 — SnapStart Enabled, Real-Path Warm-Up

All tests aggregated

Lessons learned

Conclusion

Integrating DynamoDB into Clean Architecture Wasn't as Simple as I Thought

Original architecture

Repository package

Why I thought it would work

IAmazonDynamoDB vs DynamoDBContext

Mapping challenge

Persistence model solution

Lessons learned

Conclusion

Stop Recreating .NET Solutions From Scratch

Copy and paste is not a real template

Microsoft already gave us the tool

What should go into a good .NET template?

The real benefit is not speed

Honest tip

How to create a simple .NET solution template

Step 1: Create your normal solution

Step 2: Use a clear placeholder name

Step 3: Add .template.config/template.json

Step 4: Install the template locally

Step 5: Generate a new solution from your template

Step 6: Improve the template over time

AWS Clean Architecture Starter Kit

What Is It?

Why I Built It

Who Is It For?

Architecture

Key Design Decisions

AWS Lambda Instead of ECS

Infrastructure as Code Using AWS CDK

DynamoDB as the Default Data Store

API Gateway API Keys

Getting Started

Source Code

Related Projects

Ghanavats.ResultPattern

Roadmap

Feedback

Migrate from AWS WorkMail to Microsoft Exchange and take your emails with you!

Why I migrated

What needed to be planned

DNS and domain considerations

Mailbox/user considerations

Cutover approach

Testing before and after

Mistakes or risks to avoid

IMAP migration under the hood

Final thoughts

What I would do differently next time

Step 3: Add `.template.config/template.json`