How to boost developer workflow activities with Azure Developer CLI?

This blog post is an overview to Azure Developer CLI tool and how it helps to boost developer workflow activities. Microsoft has created a lot of great documentation about Azure Developer CLI. This blog post concentrates only main points and especially how to create a Web API project (App Service based + .NET 6) which is compatible with Azure Developer CLI.

What is the Azure Developer CLI?

Microsoft announced the public preview of the Azure Developer CLI in July 2022. Azure Developer CLI (azd) is an open-source tool that accelerates the process of building cloud apps on Azure. The CLI provides best practice, developer-friendly commands that map to key stages in your workflow (ex. build, deployment, monitoring etc.), whether you’re working in the terminal, your editor or integrated development environment (IDE), or DevOps.

You can use the azd with extensible azd templates that include everything you need to get an application up and running in Azure. These templates include application code, and reusable infrastructure as code assets. Community developed templates can be found from here (Awesome azd templates) and here (GitHub).

Currently on October 2022 Azure Developer CLI supports the following Azure compute services: Azure App Service, Function, Azure Container Apps, Azure Static Web Apps and the following programming languages: Node.js, Python, .NET.

Sources:

Supported compute services and programming languages | Microsoft Learn
What is the Azure Developer CLI (preview)? | Microsoft Learn
Introducing the Azure Developer CLI (azd): A faster way to build apps for the cloud - Azure SDK Blog (microsoft.com)

Understand the architecture

Below diagram created by MS describes nicely the architecture of AZD. This blog post follows these main architecture points presented in this diagram.

Let's get started

Prerequisites

Before starting you need to install the following command line tools.

1. Install latest version of Azure CLI

az upgrade

2. Install Azure Developer CLI

powershell -ex AllSigned -c "Invoke-RestMethod 'https://aka.ms/install-azd.ps1' | Invoke-Expression"

3. Install Bicep CLI

az bicep upgrade

Create a project template

These steps create a sample Web Api Visual Studio project which is used to deploy to Azure later.

1. Create a solution

Execute this command in root folder.

dotnet new sln --name "Api.Template"

2. Create a new Dotnet Web API project

Execute this command in root folder.

dotnet new webapi -o src/Api.Template

3. Add Git ignore file

dotnet new gitignore

4. Add project to the solution

dotnet sln add src/Api.Template/Api.Template.csproj

Now you should have this kind of folder structure:

├── Api.Template.sln     [ Solution file ]
├── .gitignore           [ Git ignore file ]
├── src                  [ Source code folder ]
│   ├── Api.Template     [ Folder for Visual Studio WebAPI project ]

Initialize a project

When Visual Studio project is created then project is ready to be initialized with Azure Developer CLI (AZD). Azure Developer CLI creates some configuration files during the initializing.

1. Login to Azure subscription

I recommend login to Azure subscription before starting environment initializing because otherwise you might need to submit subscription details manually. 

az login

2. Initialize a new environment with Azure Developer CLI

Azure Developer CLI uses an environment name to set the AZURE_ENV_NAME environment variable that's used by Azure Developer CLI templates. Environment name is stored to environment configuration file. After environment initializing configurations can be found from .azure folder. It's also important to understand that environment name is also used as a prefix in the Azure Resource Group name. You can find more information about azd environments from here.

This command prompts which template to use. Select "Empty template". I didn't find how to set empty template as a parameter. Execute this command in the root folder where solution file is located.

azd init --location westeurope --subscription 00000000-0000-0000-0000-000000000000 --environment dev

After initializing you have this kind of folder structure:

├── Api.Template.sln      [ Solution file ]
├── .gitignore            [ Git ignore file ]
├── azure.yaml            [ Describes the app and type of Azure resources]
├── src                   [ Source code folder ]
│   ├── Api.Template      [ Folder for Visual Studio WebAPI project ]
├── .azure                [ Creates and configures Azure resources ]
│   ├── dev               [ Environment folder ]
│   │    ├── .env         [ Environment configuration file]
│   └── config.json       [ AZD Azure configuration file  ]

Create the infrastructure files

Azure infrastructure must be described with Bicep and files must be created to a directory called infra.

1. Create folder for infra

Infra folder should be created to the root folder.

2. Create infrastructure (Bicep) files

I prefer this kind of folder structure for infrastructure files:

├── main.bicep                            [ Main bicep file ]
├── main.parameters.json                  [ Parameter file]
├── assets                                [ Assets folder ]
│   ├── abbreviations.json                [ JSON file which contains Azure resource abbreviations ]
├── modules                               [ Bicep modules folder ]
│   ├── applicationinsights.bicep         [ Application Insights bicep module ]
│   ├── appService.bicep                  [ App Service bicep module ]
│   ├── appServicePlan.bicep              [ App Service Plan bicep module ]
│   ├── logAnalyticsWorkspace.bicep       [ Log Analytics Workspace bicep module ]
│   └── resources.bicep                   [ Resource bicep file which orchestrates resource creation  ]

Note! You can create parameter file also with a Bicep CLI:

az bicep generate-params --file main.bicep

Add these parameter values to parameter file.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "name": {
        "value": "${AZURE_ENV_NAME}"
        },
        "location": {
        "value": "${AZURE_LOCATION}"
        },
        "principalId": {
        "value": "${AZURE_PRINCIPAL_ID}"
        }
    }
}

Update Azure.yaml file

Azure Developer CLI (AZD) needs to know details of your application to enable deployment of infrastructure and application to Azure. Basically, azure.yaml describes the app and type of Azure resources. Main configuration points are under services root element.

name: Api.Template
metadata:
  template: webapi-template-azd@0.0.1-beta
services:
  appService:
    project: src/Api.Template
    language: csharp
    host: appservice
    resourceName: app-microservice-westeurope-001

More information about updating azure.yaml can be found from here. Schema of azure.yaml is available in here.

Provision & Deploy

Azure Developer CLI provides different commands whether if you just want to deploy only application or infrastructure or both.

Deploy infrastructure and application to Azure

azd up

Deploy only application to Azure

azd deploy

Deploy only infrastructure to Azure

azd provision

Lastly if you want to remove created resource from Azure you can use the following command:

azd down

Templating

Azure Developer CLI enables to use project templates published to GitHub. You can use community driven templates or use own template.

Initialize project using custom template

Template is available from GitHub.

azd init --template kalleantero/Api.Template

Deploy infrastructure and application to Azure

azd up

Super easy, just two commands and working environment is up and running in Azure.

Summary

Azure Developer CLI widely supports different software development workflow activities like build, deployment and also monitoring & setting up CI/CD which weren't handled in this blog post. Command interface of Azure Developer CLI is very intuitive, and commands wraps different Azure and Bicep CLI commands together behind the scenes. Of course, you can do almost all same things just using different Azure CLI and Bicep CLI commands separately but using Azure Developer CLI makes things more straightforward. 

I see that this tool is very useful especially if you need to quickly set up new developer environment and maybe test something. Using own templates is also very interesting option. Azure Developer CLI is currently still in preview and there are some limitations, but I believe that interesting features are coming in the future to this tool.

Source code of this sample project is available in GitHub.