What is .NET Aspire?

.NET Aspire is a very powerful tool allowing the developer to write simple C# code to define your distributed application. More simply put, when your application requires a database, a queue, a caching service along with the application code, you no longer have to define all the resources in your cloud provider prior to getting started writing code. There are several known resources we as software architects realize we need for almost any enterprise application. But even when you need to define those later within the application lifecycle, .NET Aspire will allow the growth of the infrastructure change as your application needs to evolve.

Why .NET Aspire?

For several years since the birth of cloud services, we as architects and engineers have had to either work with an infrastructure team or provision infrastructure on our own. And yes, I know there have been many improvements to the process over time, allowing us to write code to define our infrastructure requirements and even provision the infrastructure. It has always required understanding and maintaining a separate language outside .NET to do so. I am sure many of you are like me in the sense that once you build a pipeline or provision the infrastructure, you never have to touch it for several months if not years. It just works! Right? Then when asked to make a modification, you have to relearn it all. With .NET Aspire you can now define the infrastructure for your distributed application by using .NET. This to me is a huge advancement for the .NET community. So I wanted to take you along on my journey of how to first set it up and get started.

Prerequisites

First, you will need to install Azure Developer CLI (AZD) tools by following the instruction for your operating system (Install or update the Azure Developer CLI). Next once you will want to have either .NET 8 or 9 installed on your machine along with a project of your choice. For simplicity’s sake, it is much easier to start a new project with the latest version of Visual Studio (VS), which is also required to ensure that VS supports using .NET Aspire (Build your first Aspire solution). You can also add .NET Aspire to any existing project but again ensure you have the latest version of VS installed (Add aspire to existing project). You should have an AppHost project at minimum, and when starting from a new template, you will also have a Service Defaults project. I will get into those in future posts.

Getting started

Once you have everything setup with the tooling and have a project with .NET aspire setup, I will walk you through explaining the steps on setting up with Azure Cloud and GitHub. The documentation from Microsoft, at the time of first writing this post, seemed a bit lacking in some areas of explaining. So I hope this helps you get started faster.

1. Start up a PowerShell or command window
2. CD to the base directory of your project/solution
3. Run azd auth login which launches a browser to complete signing in to Azure.
4. Run azd init and follow the prompts answering the questions
   1. This initializes the AZD template for your distributed application
   2. Here you will choose things such as the name of the environment you want to run. Just know it will provision a resource group and resources within using that name, so think of something to segregate your various environments
   3. Yes, you can set up more than one environment, but more of that to come later.
5. Run mkdir .github and mkdir ./.github/workflows
6. Download the sample workflow file and place it within the newly created workflows folder (Sample GitHub Actions workflow file)
   1. I had to tweak this file a little bit to ensure it worked for me
      1. I had to add a step for installing .NET 9

           - name: Setup .NET
             uses: actions/setup-dotnet@v4
             with:
               dotnet-version: 9.0.x
         

      2. I commented out the azd init step
      3. Insert a step before azd provision to refresh the environment and be sure to have supporting environment variables at the start of the build

            - name: Refresh azd env (pulls latest infrastructure provision)
              run: azd env new ${{ env.AZURE_ENV_NAME }} --location ${{ env.AZURE_LOCATION }} --subscription ${{ env.AZURE_SUBSCRIPTION_ID }}
         

7. Run azd pipeline config which allows you to configure a deployment pipeline for the environment name you chose in the previous steps.
   1. This will automatically set the configuration variables in GitHub actions to feed into the pipeline environment variables
   2. If you want to support multiple environments, it depends on if you use private repos and if you pay for GitHub. You can copy the yml file and create environment-specific variables in GitHub manually that differ between environments. I trigger one off the develop branch and another off the main (prod) branch. Be sure to update the environment specifically pointing to those GitHub action variables. I use azd env new to set up the environment locally and go through the azd pipeline config process again for that specific environment. Be sure afterward that the correct values are set for each environment. The command does overwrite things for you.
8. At anypoint now you can run azd up to build out the environment without running the pipeline.
9. To tear down the environment, run azd down
10. Once you commit these changes to your repository, the GitHub actions will run. If you did not want to keep the infrastructure around, then run azd down or delete the resource group it created specific to the azd environment name you chose in earlier steps.

Run and Debug locally

This is a straightforward step and runs very similar to how running .NET Core apps from the console have always run. Set the AppHost project as your startup project from within Visual Studio and run the application. It will start up the dashboard and point at all the newly created resources Aspire and AZD tools just created. You will notice that the Aspire Dashboard will show up displaying all the resources that are part of your distributed application. And if you have a web front end project, it will also start. In my case, I have a Blazor project which started up as well.

Summary

.NET Aspire takes away all the headaches of knowing how to configure Azure resources and segregate environments for production or pre-production or even for separate development teams. It makes it simple to tear down any Azure environment as well if you do not want the resources for very long periods. There are plenty of nuget packages targeting almost every azure resource available through the numerous integration features available. Be sure to check out the Aspire Dashboard and discover all that it has to offer. I will cover the Aspire Dashboard as well as Aspire Hosting Integrations in future posts. Reach out if you have any questions. Bye for now and happy coding!