Azure App Service integration

🧪 Preview

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 Aspire Azure App Service hosting integration models App Service resources as the AzureAppServiceResource type. To access this type and APIs for expressing them within your AppHost project, install the 📦 Aspire.Hosting.Azure.AppService NuGet package:

Aspire CLI

Aspire CLI — 添加 Aspire.Hosting.Azure.AppService 包

aspire add azure-appservice

Aspire CLI 是交互式的；按提示选择合适的搜索结果：

Aspire CLI — 输出示例

Select an integration to add:

> azure-appservice (Aspire.Hosting.Azure.AppService)
> Other results listed as selectable options...

注意

如果只有一个结果，会自动选择。仍需确认版本。

apphost.cs (C# file-based app)

C# — AppHost.cs

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

PackageReference (*.csproj)

XML — 添加 Aspire.Hosting.Azure.AppService 包引用

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

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.

C# — AppHost.cs

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.

Caution

When you call AddAzureAppServiceEnvironment, it implicitly calls AddAzureProvisioning—which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see Local provisioning: Configuration.

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:

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")
    .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.

C# — AppHost.cs

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 F5 F5 F5 F5 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:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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 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 Sku property 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.