Edit

Share via

Local Azure provisioning

  • Article

.NET Aspire simplifies local cloud-native app development with its compelling app host model. This model allows you to run your app locally with the same configuration and services as in Azure.

In this article you learn how to provision Azure resources from your local development environment through the .NET Aspire app host. All of this is possible with the help of the Azure.Provisioning.* libraries, which provide a set of APIs to provision Azure resources. These packages are transitive dependencies of the .NET Aspire Azure hosting libraries you use in your app host, so you don't need to install them separately.

Requirements

This article assumes that you have an Azure account and subscription. If you don't have an Azure account, you can create a free one at Azure Free Account. For provisioning functionality to work correctly, you'll need to be authenticated with Azure. Additionally, you'll need to provide some configuration values so that the provisioning logic can create resources on your behalf.

App host provisioning APIs

The app host provides a set of APIs to express Azure resources. These APIs are available as extension methods in .NET Aspire Azure hosting libraries, extending the IDistributedApplicationBuilder interface. When you add Azure resources to your app host, they'll add the appropriate provisioning functionality implicitly. In other words, you don't need to call any provisioning APIs directly.

When the app host starts, the following provisioning logic is executed:

  1. The Azure configuration section is validated.
  2. When invalid the dashboard and app host output provides hints as to what's missing. For more information, see Missing configuration value hints.
  3. When valid Azure resources are conditionally provisioned:
    1. If an Azure deployment for a given resource doesn't exist, it's created and configured as a deployment.
    2. The configuration of said deployment is stamped with a checksum as a means to support only provisioning resources as necessary.

Use existing Azure resources

The app host automatically manages provisioning of Azure resources. The first time the app host runs, it provisions the resources specified in the app host. Subsequent runs don't provision the resources again unless the app host configuration changes.

If you've already provisioned Azure resources outside of the app host and want to use them, you can provide the connection string with the AddConnectionString API as shown in the following Azure Key Vault example:

// Service registration
var secrets = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureKeyVault("secrets")
    : builder.AddConnectionString("secrets");

// Service consumption
builder.AddProject<Projects.ExampleProject>()
       .WithReference(secrets)

The preceding code snippet shows how to add an Azure Key Vault to the app host. The AddAzureKeyVault API is used to add the Azure Key Vault to the app host. The AddConnectionString API is used to provide the connection string to the app host.

Alternatively, for some Azure resources, you can opt-in to running them as an emulator with the RunAsEmulator API. This API is available for Azure Cosmos DB and Azure Storage. For example, to run Azure Cosmos DB as an emulator, you can use the following code snippet:

var cosmos = builder.AddAzureCosmosDB("cosmos")
                    .RunAsEmulator();

The RunAsEmulator API configures an Azure Cosmos DB resource to be emulated using the Azure Cosmos DB emulator with the NoSQL API.

.NET Aspire Azure hosting integrations

If you're using Azure resources in your app host, you're using one or more of the .NET Aspire Azure hosting integrations. These hosting libraries provide extension methods to the IDistributedApplicationBuilder interface to add Azure resources to your app host.

Azure provisioning integrations

The following Azure provisioning libraries are available:

Tip

You shouldn't need to install these packages manually in your projects, as they're transitive dependencies of the corresponding .NET Aspire Azure hosting libraries.

Configuration

When utilizing Azure resources in your local development environment, you need to provide the necessary configuration values. Configuration values are specified under the Azure section:

  • SubscriptionId: The Azure subscription ID.
  • AllowResourceGroupCreation: A boolean value that indicates whether to create a new resource group.
  • ResourceGroup: The name of the resource group to use.
  • Location: The Azure region to use.

Consider the following example appsettings.json configuration:

{
  "Azure": {
    "SubscriptionId": "<Your subscription id>",
    "AllowResourceGroupCreation": true,
    "ResourceGroup": "<Valid resource group name>",
    "Location": "<Valid Azure location>"
  }
}

Important

It's recommended to store these values as app secrets. For more information, see Manage app secrets.

After you've configured the necessary values, you can start provisioning Azure resources in your local development environment.

Azure provisioning credential store

The .NET Aspire app host uses a credential store for Azure resource authentication and authorization. Depending on your subscription, the correct credential store may be needed for multi-tenant provisioning scenarios.

With the Aspire.Hosting.Azure NuGet package installed, and if your app host depends on Azure resources, the default Azure credential store relies on the DefaultAzureCredential. To change this behavior, you can set the credential store value in the appsettings.json file, as shown in the following example:

{
  "Azure": {
    "CredentialSource": "AzureCli"
  }
}

As with all configuration-based settings, you can configure these with alternative providers, such as user secrets or environment variables. The Azure:CredentialSource value can be set to one of the following values:

Tooling support

In Visual Studio, you can use Connected Services to configure the default Azure provisioning settings. Select the app host project, right-click on the Connected Services node, and select Azure Resource Provisioning Settings:

Visual Studio 2022: .NET Aspire App Host project, Connected Services context menu.

This will open a dialog where you can configure the Azure provisioning settings, as shown in the following screenshot:

Visual Studio 2022: Azure Resource Provisioning Settings dialog.

Missing configuration value hints

When the Azure configuration section is missing, has missing values, or is invalid, the .NET Aspire dashboard provides useful hints. For example, consider an app host that's missing the SubscriptionId configuration value that's attempting to use an Azure Key Vault resource. The Resources page indicates the State as Missing subscription configuration:

.NET Aspire dashboard: Missing subscription configuration.

Additionally, the Console logs display this information as well, consider the following screenshot:

.NET Aspire dashboard: Console logs, missing subscription configuration.

Known limitations

After provisioning Azure resources in this way, you must manually clean up the resources in the Azure portal as .NET Aspire doesn't provide a built-in mechanism to delete Azure resources. The easiest way to achieve this is by deleting the configured resource group. This can be done in the Azure portal or by using the Azure CLI:

az group delete --name <ResourceGroupName>

Replace <ResourceGroupName> with the name of the resource group you want to delete. For more information, see az group delete.