Ghanavats

Stop Recreating .NET Solutions From Scratch

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": "Saeed Ghanavat",
  "classifications": [
    "Common",
    "WebApi",
    "ClassLibrary",
    "Clean Architecture"
  ],
  "name": "YourCompany API Solution",
  "description": "Whatever description you want.",
  "identity": "YourCompany.ApiSolution.Templates",
  "shortName": "my-api-template",
  "tags": {
    "language": "C#",
    "type": "solution"
  },
  "sourceName": "TemplateSolution",
  "preferNameDirectory": true,
  "primaryOutputs": [
    {
      "path": "YouSolution.Templates.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.

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

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.

flowchart LR
    A[AWS WorkMail
Source IMAP Server] -->|IMAPS connection
Port 993 / SSL| B[Microsoft 365
Migration Endpoint]
    B --> C[Exchange Online
Migration Batch]
    D[CSV Mapping File
source mailbox → target mailbox] --> C
    C -->|Authenticate to each source mailbox| A
    C -->|Copy email folders and messages| E[Exchange Online
Target Mailboxes]
    F[DNS MX Record Cutover] -->|New inbound mail routes to Microsoft 365| E
    G[Post-migration Validation] --> H[Check mail flow
Check mailbox content
Check user access]
    E --> G

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.

AWS Clean Architecture Starter Kit

Wed, 10 Jun 2026 00:00:00 +0000

AWS Clean Architecture Starter Kit

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

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.

Ghanavats

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

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

AWS Clean Architecture Starter Kit

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

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