Edit

Configure an Aspire app for Azure App Service

This article describes how to configure Aspire apps deployed to Azure App Service. The Aspire Azure App Service integration lets you model and customize the underlying Azure infrastructure in your AppHost.

Important

The Aspire Azure App Service integration is currently in preview.

If you didn't deploy an Aspire app to App Service yet, see the quickstart guide.

Prerequisites

For current installation and AppHost setup guidance, see Azure App Service Hosting integration.

Understand what gets provisioned

When you call AddAzureAppServiceEnvironment, Aspire provisions the following Azure resources by default:

Resource Description
App Service Plan A Premium P0V3 Linux-based hosting plan
Azure Container Registry A Basic SKU registry for storing container images
User-assigned Managed Identity For secure access between App Service and Container Registry
Role Assignments ACR Pull role assigned to the managed identity

These resources provide the infrastructure needed to deploy containerized Aspire apps to Azure App Service.

Connect to an existing App Service plan

If you have an existing Azure App Service plan, you can connect to it instead of provisioning a new one. Use the AsExisting method to reference existing resources:

var builder = DistributedApplication.CreateBuilder(args);

var existingAppServicePlanName = builder.AddParameter("existingAppServicePlanName");
var existingResourceGroup = builder.AddParameter("existingResourceGroup");

builder.AddAzureAppServiceEnvironment("app-service-env")
    .AsExisting(existingAppServicePlanName, existingResourceGroup);

builder.AddProject<Projects.WebApi>("api")
    .WithExternalHttpEndpoints();

builder.Build().Run();

This approach is useful when you want to:

  • Share an App Service plan across multiple applications
  • Use an App Service plan that was provisioned outside of Aspire
  • Connect to resources in a different resource group

For more information, see Use existing Azure resources.

Customize generated App Service websites

When an App Service environment is present, Aspire automatically targets eligible project resources and Dockerfile-backed web containers to App Service. Use PublishAsAzureAppServiceWebsite only when you need to customize the generated website or deployment slot:

var builder = DistributedApplication.CreateBuilder(args);

var appServiceEnv = builder.AddAzureAppServiceEnvironment("app-service-env");

builder.AddProject<Projects.WebApi>("api")
    .WithExternalHttpEndpoints()
    .PublishAsAzureAppServiceWebsite((infra, website) =>
    {
        website.Tags.Add("Environment", "Production");
    });

builder.Build().Run();

During local development with aspire run or IDE launch support, the project runs locally. When you run aspire deploy, the project is deployed as an Azure App Service website within the provisioned environment.

For more information, see Deploy to Azure App Service and aspire run.

Configure App Service plan SKU and tier

You can customize the App Service plan SKU, tier, and capacity by using the ConfigureInfrastructure method. This approach lets you access and modify the underlying Azure resources that Aspire provisions.

In your AppHost.cs file, configure the App Service environment with custom plan settings:

using Azure.Provisioning.AppService;

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureAppServiceEnvironment("app-service-env")
    .ConfigureInfrastructure((infra) =>
    {
        var plan = infra.GetProvisionableResources().OfType<AppServicePlan>().Single();
        plan.Sku = new AppServiceSkuDescription
        {
            Name = "P1V3",
            Tier = "Premium"
        };
    });

builder.Build().Run();

The ConfigureInfrastructure callback gives you direct access to the Azure provisioning resources. In this example:

  • GetProvisionableResources() returns all Azure resources being provisioned.
  • OfType<AppServicePlan>() filters to get the App Service plan.
  • You can then modify properties like Sku.Name, Sku.Tier, and Sku.Capacity (number of instances).

Configure the Aspire Dashboard

The Aspire Dashboard is included by default when deploying to Azure App Service, giving you visibility into your deployed applications:

builder.AddAzureAppServiceEnvironment("app-service-env");
// Dashboard is included by default at https://[prefix]-aspiredashboard-[unique string].azurewebsites.net

The deployed dashboard provides the same experience as local development: view logs, traces, metrics, and application topology for your production environment.

For more information about dashboard capabilities, see Aspire dashboard overview.

To disable the dashboard:

builder.AddAzureAppServiceEnvironment("app-service-env")
    .WithDashboard(enable: false);

Configure Azure Application Insights

Enable Azure Application Insights for comprehensive monitoring and telemetry:

builder.AddAzureAppServiceEnvironment("app-service-env")
    .WithAzureApplicationInsights();

When enabled, Aspire automatically:

  • Creates a Log Analytics workspace.
  • Creates an Application Insights resource.
  • Configures all App Service web apps with the connection string.
  • Injects APPLICATIONINSIGHTS_CONNECTION_STRING into your applications.

You can also reference an existing Application Insights resource:

var insights = builder.AddAzureApplicationInsights("insights");

builder.AddAzureAppServiceEnvironment("app-service-env")
    .WithAzureApplicationInsights(insights);

Configure app settings

You can add custom app settings to your App Service apps by using the PublishAsAzureAppServiceWebsite customization callback.

using Azure.Provisioning.AppService;

builder.AddProject<Projects.aspire_starter_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithReference(apiService)
    .WaitFor(apiService)
    .PublishAsAzureAppServiceWebsite((infra, website) =>
    {
        website.SiteConfig.AppSettings.Add(new AppServiceNameValuePair
        {
            Name = "WEBSITE_LOAD_CERTIFICATES",
            Value = "*"
        });
        website.SiteConfig.AppSettings.Add(new AppServiceNameValuePair
        {
            Name = "MyCustomSetting",
            Value = "MyCustomValue"
        });
    });

You can add App Service application settings through the SiteConfig.AppSettings collection. App Service setting names can contain only letters, numbers, and underscores. For more information, see Azure App Service Hosting integration.

Add tags to resources

Tags help you organize and manage your Azure resources. You can add tags to both websites and the App Service plan.

Add tags to a website:

builder.AddProject<Projects.aspire_starter_Web>("webfrontend")
    .PublishAsAzureAppServiceWebsite((infra, website) =>
    {
        website.Tags.Add("Environment", "Production");
        website.Tags.Add("Team", "Engineering");
    });

Add tags to the App Service plan:

builder.AddAzureAppServiceEnvironment("app-service-env")
    .ConfigureInfrastructure(infra =>
    {
        var plan = infra.GetProvisionableResources().OfType<AppServicePlan>().Single();
        plan.Tags.Add("Environment", "Production");
        plan.Tags.Add("CostCenter", "Engineering");
    });

Configure health probes

Health probes allow Azure App Service to monitor your application's health and make routing decisions. You can configure different probe types using the WithHttpProbe method.

#pragma warning disable ASPIREPROBES001
builder.AddProject<Projects.aspire_starter_Web>("webfrontend")
    .WithHttpProbe(ProbeType.Liveness, "/healthz")
    // ... other configuration
#pragma warning restore ASPIREPROBES001

Note

Using WithHttpProbe may require suppressing the ASPIREPROBES001 diagnostic warning, as this feature is in preview.

Make sure your application exposes the health check endpoints. For ASP.NET Core apps, you can use the built-in health checks middleware:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks();

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

Configure external endpoints

When deploying Aspire apps to App Service, service-to-service communication requires external HTTP endpoints. Unlike Container Apps, App Service currently doesn't manage traffic between apps through internal endpoints.

var apiService = builder.AddProject<Projects.aspire_starter_ApiService>("apiservice")
    .WithExternalHttpEndpoints()
    .WithHttpHealthCheck("/health");

builder.AddProject<Projects.aspire_starter_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithReference(apiService)
    .WaitFor(apiService);

The WithExternalHttpEndpoints() method configures the project to be accessible via public HTTP endpoints. This is required for:

  • Backend services that other services in your Aspire app need to call
  • Frontend applications that users access directly

App Service supports only external HTTP and HTTPS endpoints and one distinct external target port for each deployed app. Aspire upgrades generated external HTTP endpoint URLs and service-discovery connection strings to HTTPS by default. For more information, see Deploy to Azure App Service.

Related content

  • Last updated on