|
| 1 | +--- |
| 2 | +title: Azure App Service integration (Preview) |
| 3 | +description: Learn how to integrate Azure App Service with Aspire for hosting web applications. |
| 4 | +ms.date: 10/02/2025 |
| 5 | +ai-usage: ai-generated |
| 6 | +--- |
| 7 | + |
| 8 | +# Aspire Azure App Service integration (Preview) |
| 9 | + |
| 10 | +[!INCLUDE [includes-hosting](../includes/includes-hosting.md)] |
| 11 | + |
| 12 | +> [!IMPORTANT] |
| 13 | +> The Aspire Azure App Service integration is currently in preview and is subject to change. |
| 14 | +
|
| 15 | +[Azure App Service](/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. |
| 16 | + |
| 17 | +## Hosting integration |
| 18 | + |
| 19 | +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](https://www.nuget.org/packages/Aspire.Hosting.Azure.AppService) NuGet package. |
| 20 | + |
| 21 | +### [.NET CLI](#tab/dotnet-cli) |
| 22 | + |
| 23 | +```dotnetcli |
| 24 | +dotnet add package Aspire.Hosting.Azure.AppService |
| 25 | +``` |
| 26 | + |
| 27 | +### [PackageReference](#tab/package-reference) |
| 28 | + |
| 29 | +```xml |
| 30 | +<PackageReference Include="Aspire.Hosting.Azure.AppService" |
| 31 | + Version="*" /> |
| 32 | +``` |
| 33 | + |
| 34 | +--- |
| 35 | + |
| 36 | +For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package) or [Manage package dependencies in .NET applications](/dotnet/core/tools/dependencies). |
| 37 | + |
| 38 | +## Add Azure App Service environment |
| 39 | + |
| 40 | +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. |
| 41 | + |
| 42 | +```csharp |
| 43 | +var builder = DistributedApplication.CreateBuilder(args); |
| 44 | + |
| 45 | +var appServiceEnv = builder.AddAzureAppServiceEnvironment("app-service-env"); |
| 46 | + |
| 47 | +// Add other resources to the app model |
| 48 | +
|
| 49 | +builder.Build().Run(); |
| 50 | +``` |
| 51 | + |
| 52 | +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: |
| 53 | + |
| 54 | +- An App Service Plan with a Premium P0V3 tier on Linux. |
| 55 | +- An Azure Container Registry (Basic SKU) for container image storage. |
| 56 | +- A user-assigned managed identity for secure access to the container registry. |
| 57 | + |
| 58 | +> [!IMPORTANT] |
| 59 | +> When you call <xref:Aspire.Hosting.AzureAppServiceEnvironmentExtensions.AddAzureAppServiceEnvironment*>, it implicitly calls <xref:Aspire.Hosting.AzureProvisionerExtensions.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](local-provisioning.md#configuration). |
| 60 | +
|
| 61 | +## Connect to an existing Azure App Service plan |
| 62 | + |
| 63 | +You might have an existing Azure App Service plan that you want to use. Chain a call to annotate that your <xref:Aspire.Hosting.Azure.AzureAppServiceEnvironmentResource> is an existing resource: |
| 64 | + |
| 65 | +```csharp |
| 66 | +var builder = DistributedApplication.CreateBuilder(args); |
| 67 | + |
| 68 | +var existingAppServicePlanName = builder.AddParameter("existingAppServicePlanName"); |
| 69 | +var existingResourceGroup = builder.AddParameter("existingResourceGroup"); |
| 70 | + |
| 71 | +var appServiceEnv = builder.AddAzureAppServiceEnvironment("app-service-env") |
| 72 | + .AsExisting(existingAppServicePlanName, existingResourceGroup); |
| 73 | + |
| 74 | +builder.AddProject<Projects.WebApi>("api") |
| 75 | + .PublishAsAzureAppServiceWebsite((infra, website) => |
| 76 | + { |
| 77 | + // Optional: customize the Azure App Service website here |
| 78 | + }); |
| 79 | + |
| 80 | +// After adding all resources, run the app... |
| 81 | +``` |
| 82 | + |
| 83 | +[!INCLUDE [azure-configuration](includes/azure-configuration.md)] |
| 84 | + |
| 85 | +For more information on treating Azure App Service resources as existing resources, see [Use existing Azure resources](integrations-overview.md#use-existing-azure-resources). |
| 86 | + |
| 87 | +> [!NOTE] |
| 88 | +> Alternatively, instead of representing an Azure App Service environment resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](integrations-overview.md#add-existing-azure-resources-with-connection-strings). |
| 89 | +
|
| 90 | +## Publish resources as Azure App Service websites |
| 91 | + |
| 92 | +After adding an App Service environment, you can publish compute resources (`IComputeResource`) as Azure App Service websites using the <xref:Aspire.Hosting.AzureAppServiceComputeResourceExtensions.PublishAsAzureAppServiceWebsite*> method. |
| 93 | + |
| 94 | +```csharp |
| 95 | +var builder = DistributedApplication.CreateBuilder(args); |
| 96 | + |
| 97 | +var appServiceEnv = builder.AddAzureAppServiceEnvironment("app-service-env"); |
| 98 | + |
| 99 | +builder.AddProject<Projects.WebApi>("api") |
| 100 | + .PublishAsAzureAppServiceWebsite((infra, website) => |
| 101 | + { |
| 102 | + // Optional: customize the Azure App Service website here |
| 103 | + }); |
| 104 | + |
| 105 | +builder.Build().Run(); |
| 106 | +``` |
| 107 | + |
| 108 | +The preceding code: |
| 109 | + |
| 110 | +- Creates an Azure App Service environment named `app-service-env`. |
| 111 | +- Adds a project named `api` to the AppHost. |
| 112 | +- Configures the project to be published as an Azure App Service website. |
| 113 | +- Provides an optional callback to customize the website configuration. |
| 114 | + |
| 115 | +During local development (when running with <kbd>F5</kbd>), the project runs locally. When you publish your app, the project is deployed as an Azure App Service website within the provisioned environment. |
| 116 | + |
| 117 | +## Customize the App Service website |
| 118 | + |
| 119 | +The `PublishAsAzureAppServiceWebsite` method accepts a callback that allows you to customize the Azure App Service website configuration using the [Azure.Provisioning](/dotnet/api/azure.provisioning) APIs: |
| 120 | + |
| 121 | +```csharp |
| 122 | +builder.AddProject<Projects.WebApi>("api") |
| 123 | + .PublishAsAzureAppServiceWebsite((infra, website) => |
| 124 | + { |
| 125 | + website.AppSettings.Add("ASPNETCORE_ENVIRONMENT", new AppServiceConfigurationSetting |
| 126 | + { |
| 127 | + Name = "ASPNETCORE_ENVIRONMENT", |
| 128 | + Value = "Production" |
| 129 | + }); |
| 130 | + |
| 131 | + website.Tags.Add("Environment", "Production"); |
| 132 | + website.Tags.Add("Team", "Engineering"); |
| 133 | + }); |
| 134 | +``` |
| 135 | + |
| 136 | +The preceding code: |
| 137 | + |
| 138 | +- Chains a call to <xref:Aspire.Hosting.AzureAppServiceComputeResourceExtensions.PublishAsAzureAppServiceWebsite*> with a customization callback. |
| 139 | +- Adds an application setting for `ASPNETCORE_ENVIRONMENT`. |
| 140 | +- Adds multiple tags for metadata and organization. |
| 141 | + |
| 142 | +> [!NOTE] |
| 143 | +> You can configure many other properties of the App Service website using this approach. For a complete list of available configuration options, see <xref:Azure.Provisioning.AppService.WebSite>. |
| 144 | +
|
| 145 | +## Provisioning-generated Bicep |
| 146 | + |
| 147 | +If you're new to [Bicep](/azure/azure-resource-manager/bicep/overview), 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. |
| 148 | + |
| 149 | +When you add an Azure App Service environment, the following key resources are provisioned: |
| 150 | + |
| 151 | +- **App Service Plan**: A Premium P0V3 Linux-based hosting plan. |
| 152 | +- **Azure Container Registry**: A Basic SKU registry for storing container images. |
| 153 | +- **User-assigned Managed Identity**: For secure access between App Service and Container Registry. |
| 154 | +- **Role Assignments**: ACR Pull role assigned to the managed identity. |
| 155 | + |
| 156 | +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. |
| 157 | + |
| 158 | +### Customize provisioning infrastructure |
| 159 | + |
| 160 | +All Aspire Azure resources are subclasses of the <xref:Aspire.Hosting.Azure.AzureProvisioningResource> type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources—using the <xref:Aspire.Hosting.AzureProvisioningResourceExtensions.ConfigureInfrastructure``1(Aspire.Hosting.ApplicationModel.IResourceBuilder{``0},System.Action{Aspire.Hosting.Azure.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: |
| 161 | + |
| 162 | +```csharp |
| 163 | +var builder = DistributedApplication.CreateBuilder(args); |
| 164 | + |
| 165 | +var appServiceEnv = builder.AddAzureAppServiceEnvironment("app-service-env") |
| 166 | + .ConfigureInfrastructure(infra => |
| 167 | + { |
| 168 | + var resources = infra.GetProvisionableResources(); |
| 169 | + var plan = resources.OfType<AppServicePlan>().Single(); |
| 170 | + |
| 171 | + plan.Sku = new AppServiceSkuDescription |
| 172 | + { |
| 173 | + Name = "P1V3", |
| 174 | + Tier = "Premium" |
| 175 | + }; |
| 176 | + |
| 177 | + plan.Tags.Add("Environment", "Production"); |
| 178 | + plan.Tags.Add("CostCenter", "Engineering"); |
| 179 | + }); |
| 180 | + |
| 181 | +builder.Build().Run(); |
| 182 | +``` |
| 183 | + |
| 184 | +The preceding code: |
| 185 | + |
| 186 | +- Chains a call to the <xref:Aspire.Hosting.AzureProvisioningResourceExtensions.ConfigureInfrastructure*> API: |
| 187 | + - The `infra` parameter is an instance of the <xref:Aspire.Hosting.Azure.AzureResourceInfrastructure> type. |
| 188 | + - The provisionable resources are retrieved by calling the <xref:Azure.Provisioning.Infrastructure.GetProvisionableResources> method. |
| 189 | + - The single <xref:Azure.Provisioning.AppService.AppServicePlan> is retrieved. |
| 190 | + - The <xref:Azure.Provisioning.AppService.AppServicePlan.Sku?displayProperty=nameWithType> is changed to a P1V3 tier. |
| 191 | + - Tags are added to the App Service Plan for metadata and organization. |
| 192 | + |
| 193 | +There are many more configuration options available to customize the App Service environment. For more information, see <xref:Azure.Provisioning.AppService> and [Azure.Provisioning customization](customize-azure-resources.md#azureprovisioning-customization). |
| 194 | + |
| 195 | +## See also |
| 196 | + |
| 197 | +- [Azure App Service documentation](/azure/app-service) |
| 198 | +- [.NET Aspire Azure integrations overview](integrations-overview.md) |
| 199 | +- [Configure Azure Container Apps environments](configure-aca-environments.md) |
0 commit comments