Read time: 6 minutes

A few months ago, I was trying to find a way to come up with some sort of template for future .NET API projects based on .NET Aspire.

The standard Aspire templates give you a great start, but I had already finished another Aspire application with tons of essential building blocks that I did not want to manually bring to the new project.

There had to be a better way than cloning and tweaking everything by hand.

Well, this is exactly what .NET project templates are designed for, and when taking full advantage of their features, they can really streamline the way you start new Aspire-based projects.

Today, I’ll show you how I created my new .NET Aspire API Starter template, step-by-step.

Let’s start.

​

The starting point

The Aspire-enabled .NET API I had just finished already had most of the things I could reuse in future projects, including:

  • Vertical slice architecture
  • Classic (and not-so-classic) CRUD endpoints
  • EF Core integration with PostgreSQL
  • Global error handling
  • Authorization policies
  • JWT authentication with support for Entra ID
  • Azure Storage integration

  • An Aspire AppHost project with:

    • A complete application model
    • Support for Azure services, ready to deploy

  • An Aspire Service Defaults project with:

    • Custom health checks
    • OpenTelemetry integration
  • An integration tests project, with several working tests
  • An Azure DevOps CI/CD pipeline
  • A lot of other reusable stuff.

At a high level, it looked like this:

​

To turn this into a template, I started by generalizing things a bit.

​

Step 1: Generalize project items

You don’t have to do this, but it didn’t feel right to have GameStore spread all over the soon-to-be template.

Plus, that term will be used as a placeholder to be replaced with the actual name given to the project by the user.

So I replaced all instances of GameStore with TemplateApp, a more generic term:

​

Notice this applies not only to folders and project files, but also to every namespace and class influenced by the name of the project:

​

Even to the CI/CD pipeline yml contents:

​

It’s not the most fun part of this process, but with the help of the Copilot Agent, it didn’t take long.

Next: time to add the template configuration.

​

Step 2: Add the template configuration

To turn the templatized application into an actual template, all you need to do is add a template.json file in a new .template.config folder at the root of the repo.

Here’s my template.json file:

​

Let’s go over the not-so-obvious key elements:

  • classifications: These will show in the Tags column when your template appears in the dotnet new list command results.
  • shortName: The name you will use with dotnet new to create a project using your template.
  • sourceName: The name to be replaced across all template dirs and files with the value specified by the user via the –name argument.
  • preferNameDirectory: Makes it so a directory is created for your project if –name was specified.

There are tons more things you could configure in that file, but I found these to be a great start.

Now, let’s install the template.

​

Step 3: Install the template

To use the template, you first have to install it. But, before doing that, make sure you delete any extra folders you don’t want to get included with it, like your bin or obj dirs.

Then, open a terminal at the root of your template, and use the dotnet new install command:

​

You should now be able to list your template with the familiar dotnet new list command:

​

Great, now let’s put it to the test.

​

Using the template

Let’s say I want to create a new Aspire-enabled API for my new inventory management application.

Easy to get started with the new template:

​

Let’s open the new project in VS Code and confirm all projects and files look good:

​

What about classes?

​

But can I build and run this? Will it work?

​

Yep. Let’s also open the Aspire Dashboard:

​

Great!

Finally, what about the integration tests?

​

Mission Accomplished!

​

Wrapping Up

.NET project templates aren’t just about saving time—they’re about building consistency across your projects.

Instead of manually recreating the same Aspire setup, authentication flows, and project structure every time, you get a battle-tested foundation that just works.

One template. Infinite projects. Zero repetitive setup.

And that’s all for today.

See you next Saturday.

P.S. If you need it, the complete .NET Aspire API Starter template is now available here.


Whenever you’re ready, there are 4 ways I can help you:

  1. ​Stripe for .NET Developers (Waitlist)​: Add real payments to your .NET apps with Stripe—fast, secure, production-ready.

  2. .NET Cloud Developer Bootcamp: A complete blueprint for C# developers who need to build production-ready .NET applications for the Azure cloud.

  3. ​​Get the full source code: Download the working project from this newsletter, grab exclusive course discounts, and join a private .NET community.

  4. Promote your business to 25,000+ developers by sponsoring this newsletter.