Aspire Azure App Service integration (Preview)

Includes: Hosting integration only — Client integration not included

Azure App Service is a fully managed platform for building, deploying, and scaling web apps. Aspire apps often run locally during development but require scalable, production-ready hosting environments for staging and production. The Aspire integration allows you to provision or reference an existing Azure App Service environment (App Service Plan) and seamlessly publish your container, executable, and project resources as Azure App Service websites. When you add an App Service environment, the integration automatically provisions an Azure Container Registry for container-based deployments and grants fine-grained role assignments to enable secure access between Azure resources.

Hosting integration

The Azure App Service integration is part of the Aspire hosting model. It allows you to define and manage your app's resources in a declarative manner. The integration is available in the 📦 Aspire.Hosting.Azure.AppService NuGet package.

dotnet add package Aspire.Hosting.Azure.AppService

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

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Add Azure App Service environment

To use Azure App Service with Aspire, you first add an App Service environment to your AppHost project. The environment represents the hosting infrastructure (App Service Plan) where your apps will run.

var builder = DistributedApplication.CreateBuilder(args);

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

// Add other resources to the app model

builder.Build().Run();

The preceding code creates a new Azure App Service environment named app-service-env. When you run your app locally, this environment is provisioned in your Azure subscription with the following resources:

• An App Service Plan with a Premium P0V3 tier on Linux.
• An Azure Container Registry (Basic SKU) for container image storage.
• A user-assigned managed identity for secure access to the container registry.

Connect to an existing Azure App Service plan

You might have an existing Azure App Service plan that you want to use. Chain a call to annotate that your AzureAppServiceEnvironmentResource is an existing resource:

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")
       .PublishAsAzureAppServiceWebsite((infra, website) =>
       {
           // Optional: customize the Azure App Service website here
       });

// After adding all resources, run the app...

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

Publish resources as Azure App Service websites

After adding an App Service environment, you can publish compute resources (IComputeResource) as Azure App Service websites using the PublishAsAzureAppServiceWebsite method.

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.WebApi>("api")
       .PublishAsAzureAppServiceWebsite((infra, website) =>
       {
           // Optional: customize the Azure App Service website here
       });

builder.Build().Run();

The preceding code:

• Creates an Azure App Service environment named app-service-env.
• Adds a project named api to the AppHost.
• Configures the project to be published as an Azure App Service website.
• Provides an optional callback to customize the website configuration.

During local development (when running with F5), the project runs locally. When you publish your app, the project is deployed as an Azure App Service website within the provisioned environment.

Customize the App Service website

The PublishAsAzureAppServiceWebsite method accepts a callback that allows you to customize the Azure App Service website configuration using the Azure.Provisioning APIs:

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");
       });

The preceding code:

• Chains a call to PublishAsAzureAppServiceWebsite with a customization callback.
• Adds an application setting for ASPNETCORE_ENVIRONMENT.
• Adds multiple tags for metadata and organization.

Provisioning-generated Bicep

If you're new to Bicep, it's a domain-specific language for defining Azure resources. With .NET Aspire, you don't need to write Bicep by-hand, instead the provisioning APIs generate Bicep 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 C#. Customizations to the Bicep file directly are overwritten, so make changes through the C# provisioning APIs to ensure they're reflected in the generated files.

Customize provisioning infrastructure

All Aspire Azure resources are subclasses of the AzureProvisioningResource type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources—using the ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API. For example, you can configure the App Service Plan SKU, location, and more. The following example demonstrates how to customize the Azure App Service environment:

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:
  • The infra parameter is an instance of the AzureResourceInfrastructure type.
  • The provisionable resources are retrieved by calling the GetProvisionableResources() method.
  • The single AppServicePlan is retrieved.
  • The AppServicePlan.Sku is changed to a P1V3 tier.
  • Tags are added to the App Service Plan for metadata and organization.

There are many more configuration options available to customize the App Service environment. For more information, see Azure.Provisioning.AppService and Azure.Provisioning customization.

See also

• Azure App Service documentation
• .NET Aspire Azure integrations overview
• Configure Azure Container Apps environments