Set up Azure App Service in the AppHost

🧪 Preview

This article is the reference for the Aspire Azure App Service Hosting integration. It enumerates the AppHost APIs — with examples for both AppHost.cs and apphost.mts — that you use to model an Azure App Service environment in your AppHost project.

If you’re new to the Azure App Service integration, start with the Get started with the Azure App Service integration guide. For how deployed apps consume the runtime configuration this integration injects, see Azure App Service runtime configuration.

Installation

To start building an Aspire app that targets Azure App Service, install the 📦 Aspire.Hosting.Azure.AppService NuGet package:

TypeScript

Terminal

aspire add Aspire.Hosting.Azure.AppService

Learn more about aspire add in the command reference.

This updates your aspire.config.json with the hosting integration package:

aspire.config.json

{
  "packages": {
    "Aspire.Hosting.Azure.AppService": "13.6.0"
  }
}

C#

Terminal

aspire add Aspire.Hosting.Azure.AppService

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

AppHost.cs

#:package Aspire.Hosting.Azure.AppService@*

AppHost.csproj

<PackageReference Include="Aspire.Hosting.Azure.AppService" Version="*" />

Add Azure App Service environment

To deploy compute resources to Azure App Service, first add an App Service environment to your AppHost. The environment represents the hosting infrastructure (App Service Plan) into which Aspire deploys your project and container resources.

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const appServiceEnv =
  await builder.addAzureAppServiceEnvironment('app-service-env');

await builder.addProject('api', '../WebApi/WebApi.csproj');

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

// After adding all resources, run the app...
builder.Build().Run();

1. When you call addAzureAppServiceEnvironment (or AddAzureAppServiceEnvironment in C#), Aspire implicitly enables Azure provisioning for the application.

2. All project resources and Dockerfile-backed containers in the AppHost are automatically targeted to the App Service environment when it’s present — no explicit wiring is required.

3. During local development the projects run locally as usual. When you publish, each eligible resource is deployed as an Azure App Service website within the provisioned environment.

Cuidado

Calling AddAzureAppServiceEnvironment (or addAzureAppServiceEnvironment in TypeScript) implicitly calls AddAzureProvisioning, which adds support for generating Azure resources dynamically during app startup. The app must configure an Azure subscription and location. For more information, see Local provisioning: Configuration.

Nota

Backing services such as databases, caches, and message brokers should use their own managed Azure services rather than App Service websites. Only web-facing compute resources — project resources and Dockerfile-backed containers — are deployed as App Service websites.

When the App Service environment is provisioned in Azure, the following resources are created:

• 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 the Container Registry.
• Role Assignments — ACR Pull role assigned to the managed identity.

Connect to an existing App Service plan

If you already have an App Service plan in Azure, annotate your environment resource as existing to use it instead of provisioning a new one:

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const existingAppServicePlanName = await builder.addParameter(
  'existingAppServicePlanName'
);
const existingResourceGroup = await builder.addParameter(
  'existingResourceGroup'
);

const appServiceEnv =
  await builder.addAzureAppServiceEnvironment('app-service-env');
await appServiceEnv.asExisting(
  existingAppServicePlanName,
  existingResourceGroup
);

await builder.addProject('api', '../WebApi/WebApi.csproj');

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

// After adding all resources, run the app...
builder.Build().Run();

For more information on treating Azure resources as existing resources, see Use existing Azure resources.

Customize App Service websites

By default, Aspire generates an App Service website for each eligible resource without additional configuration. Use PublishAsAzureAppServiceWebsite (C#) or publishAsAzureAppServiceWebsite (TypeScript) when you need to customize the generated website — for example to add application settings or tags:

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

await builder.addAzureAppServiceEnvironment('app-service-env');

const api = await builder.addProject('api', '../WebApi/WebApi.csproj');
await api.publishAsAzureAppServiceWebsite({
  configure: async (infra, website) => {
    // Customize infrastructure here using Azure Provisioning APIs
  },
});

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.WebApi>("api")
    .PublishAsAzureAppServiceWebsite((infra, website) =>
    {
        website.AppSettings.Add("ASPNETCORE_ENVIRONMENT", new AppServiceConfigurationSetting
        {
            Name = "ASPNETCORE_ENVIRONMENT",
            Value = "Production"
        });

        website.Tags.Add("Environment", "Production");
        website.Tags.Add("Team", "Engineering");
    });

builder.Build().Run();

The preceding code:

• Adds an App Service environment.
• Chains a call to PublishAsAzureAppServiceWebsite (or publishAsAzureAppServiceWebsite) with a customization callback.
• In C#, adds an application setting for ASPNETCORE_ENVIRONMENT and metadata tags.

Nota

When App Service deployment configures a managed identity for a resource, Aspire automatically sets the AZURE_TOKEN_CREDENTIALS environment variable to ManagedIdentityCredential. This ensures that DefaultAzureCredential uses only ManagedIdentityCredential for authentication, following Azure SDK best practices. If you need a different credential type, remove this app setting by customizing the generated website with PublishAsAzureAppServiceWebsite.

Deployment slots

Deployment slots let you deploy your app to a staging environment for testing before swapping it into production. The WithDeploymentSlot extension method (or withDeploymentSlot in TypeScript) configures a deployment slot for the App Service environment:

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

await (
  await builder.addAzureAppServiceEnvironment('appservice')
).withDeploymentSlot('staging');

const apiService = await builder.addProject(
  'apiservice',
  '../ApiService/ApiService.csproj'
);

await builder
  .addProject('webfrontend', '../Web/Web.csproj')
  .withReference(apiService)
  .waitFor(apiService);

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureAppServiceEnvironment("appservice")
    .WithDeploymentSlot("staging");

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

builder.AddProject<Projects.Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithHttpHealthCheck("/health")
    .WithReference(apiService)
    .WaitFor(apiService);

builder.Build().Run();

The preceding code configures all App Service websites to be deployed to a staging slot.

Deployment slot behavior

When you deploy to a slot, the deployment behavior depends on whether the production App Service already exists:

• New App Service: If the production App Service doesn’t exist at the time of deployment, Aspire deploys to both the production App Service and the specified deployment slot.
• Existing App Service: If the production App Service already exists, Aspire deploys only to the specified deployment slot.

Using parameters for deployment slots

Specify the deployment slot name as a parameter so that it can be provided at deployment time:

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const slotName = await builder.addParameter('deploymentSlot');

await (
  await builder.addAzureAppServiceEnvironment('appservice')
).withDeploymentSlot(slotName);

// Add your projects and other resources...

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var slotName = builder.AddParameter("deploymentSlot");

builder.AddAzureAppServiceEnvironment("appservice")
    .WithDeploymentSlot(slotName);

// Add your projects and other resources...

builder.Build().Run();

With this configuration, provide a value for the deploymentSlot parameter when running aspire deploy.

Applying customizations to slots

Cuidado

Customizations applied to the production App Service are not automatically applied to deployment slots. You must explicitly apply customizations to the slot when needed.

When you customize App Service resources using PublishAsAzureAppServiceWebsite (or publishAsAzureAppServiceWebsite) or ConfigureInfrastructure, those customizations apply to the production slot by default. Apply them separately to each slot when needed using the configureSlot option:

TypeScript

apphost.mts

const api = await builder.addProject('api', '../WebApi/WebApi.csproj');
await api.publishAsAzureAppServiceWebsite({
  configure: async (infra, website) => {
    // Production website customizations
  },
  configureSlot: async (infra, slot) => {
    // Deployment slot customizations
  },
});

C#

AppHost.cs

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

Regional virtual network integration

To configure regional virtual network integration for the websites in an App Service environment, add the 📦 Aspire.Hosting.Azure.Network integration and delegate a subnet to the environment with WithDelegatedSubnet (or withDelegatedSubnet in TypeScript):

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const vnet = await builder.addAzureVirtualNetwork('vnet');
const subnet = await vnet.addSubnet('app-service-subnet', '10.0.0.0/24');

const appServiceEnv = await builder
  .addAzureAppServiceEnvironment('app-service-env')
  .withDelegatedSubnet(subnet);

await builder.addProject('api', '../WebApi/WebApi.csproj');

await builder.build().run();

C#

AppHost.cs

#pragma warning disable ASPIREAZURE003 // Azure Virtual Network APIs are experimental.

var builder = DistributedApplication.CreateBuilder(args);

var vnet = builder.AddAzureVirtualNetwork("vnet");
var subnet = vnet.AddSubnet("app-service-subnet", "10.0.0.0/24");

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

#pragma warning restore ASPIREAZURE003

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

builder.Build().Run();

WithDelegatedSubnet delegates the subnet to Microsoft.Web/serverFarms and configures every generated website, deployment slot, and the default Aspire Dashboard to use it for regional virtual network integration. The subnet must meet the Azure App Service regional virtual network integration requirements.

Nota

Regional virtual network integration affects outbound traffic only. It doesn’t make website or dashboard ingress private, and it doesn’t enable Route All. Configure private endpoints or access restrictions, and Route All, separately when those behaviors are required.

For more information on configuring virtual networks and subnets, see Azure Virtual Network.

Customize provisioning infrastructure

All Aspire Azure resources expose a ConfigureInfrastructure API (or configureInfrastructure in TypeScript) that lets you customize the generated Bicep through the Azure.Provisioning APIs. For example, you can change the App Service Plan SKU:

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

await (
  await builder.addAzureAppServiceEnvironment('app-service-env')
).configureInfrastructure(async (infra) => {
  // Customize Azure Provisioning resources here
});

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var appServiceEnv = builder.AddAzureAppServiceEnvironment("app-service-env")
    .ConfigureInfrastructure(infra =>
    {
        var resources = infra.GetProvisionableResources();
        var plan = resources.OfType<AppServicePlan>().Single();

        plan.Sku = new AppServiceSkuDescription
        {
            Name = "P1V3",
            Tier = "Premium"
        };

        plan.Tags.Add("Environment", "Production");
        plan.Tags.Add("CostCenter", "Engineering");
    });

builder.Build().Run();

The preceding code:

• Chains a call to the ConfigureInfrastructure API.
• Retrieves the provisionable resources and locates the single AppServicePlan.
• Changes the SKU to a P1V3 Premium tier.
• Adds tags for metadata and cost management.

For more information, see Azure.Provisioning.AppService and Azure.Provisioning customization.

Provisioning-generated Bicep

If you’re new to Bicep, it’s a domain-specific language for defining Azure resources. With Aspire, you don’t need to write Bicep by hand — the provisioning APIs generate it for you. When you publish your app, the generated Bicep is output alongside the manifest file.

When you add an Azure App Service environment, the following key resources are provisioned:

• 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.

The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in your AppHost. Customize the Bicep through the C# or TypeScript provisioning APIs — direct edits to generated Bicep files are overwritten on the next publish.

See also

• Azure App Service runtime configuration
• Azure Virtual Network
• Local Azure provisioning
• Use existing Azure resources
• Azure.Provisioning customization