Skip to content

Commit 48f9f61

Browse files
IEvangelistIEvangelist
authored
Adds Azure App Configuration integration (#3500)
* Fixes #3395, adds Azure App Configuration. * Fix include link
1 parent c6d931d commit 48f9f61

File tree

4 files changed

+331
-2
lines changed

4 files changed

+331
-2
lines changed

‎docs/azure/azure-app-configuration-integration.md‎

Lines changed: 305 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,305 @@
1+
---
2+
title: Azure App Configuration integration
3+
description: Learn how to use Azure App Configuration with .NET Aspire.
4+
ms.date: 05/15/2025
5+
---
6+
7+
# .NET Aspire Azure App Configuration integration
8+
9+
[!INCLUDE [includes-hosting-and-client](../includes/includes-hosting-and-client.md)]
10+
11+
[Azure App Configuration](/azure/azure-app-configuration/overview) provides a service to centrally manage application settings and feature flags. Modern programs, especially programs running in a cloud, generally have many components that are distributed in nature. Spreading configuration settings across these components can lead to hard-to-troubleshoot errors during an application deployment. The .NET Aspire Azure App Configuration integration enables you to connect to existing App Configuration instances or create new instances all from your app host.
12+
13+
## Hosting integration
14+
15+
The .NET Aspire Azure App Configuration hosting integration models the App Configuration resource as the <xref:Aspire.Hosting.Azure.AzureAppConfigurationResource> type. To access this type and APIs fro expressing the resource, add the [📦 Aspire.Hosting.Azure.AppConfiguration](https://www.nuget.org/packages/Aspire.Hosting.Azure.AppConfiguration) NuGet package in the [app host](xref:dotnet/aspire/app-host) project.
16+
17+
### [.NET CLI](#tab/dotnet-cli)
18+
19+
```dotnetcli
20+
dotnet add package Aspire.Hosting.Azure.AppConfiguration
21+
```
22+
23+
### [PackageReference](#tab/package-reference)
24+
25+
```xml
26+
<PackageReference Include="Aspire.Hosting.Azure.AppConfiguration"
27+
Version="*" />
28+
```
29+
30+
---
31+
32+
For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package) or [Manage package dependencies in .NET applications](/dotnet/core/tools/dependencies).
33+
34+
### Add Azure App Configuration resource
35+
36+
In your app host project, call <xref:Aspire.Hosting.AzureAppConfigurationExtensions.AddAzureAppConfiguration*> to add and return an Azure App Configuration resource builder.
37+
38+
```csharp
39+
var builder = DistributedApplication.CreateBuilder(args);
40+
41+
var appConfig = builder.AddAzureAppConfiguration("config");
42+
43+
// After adding all resources, run the app...
44+
45+
builder.Build().Run();
46+
```
47+
48+
When you add an <xref:Aspire.Hosting.Azure.AzureAppConfigurationResource> to the app host, it exposes other useful APIs.
49+
50+
> [!IMPORTANT]
51+
> When you call <xref:Aspire.Hosting.AzureAppConfigurationExtensions.AddAzureAppConfiguration*>, it implicitly calls <xref:Aspire.Hosting.AzureProvisionerExtensions.AddAzureProvisioning(Aspire.Hosting.IDistributedApplicationBuilder)>—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).
52+
53+
#### Provisioning-generated Bicep
54+
55+
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. When you add an Azure App Configuration resource, the following Bicep is generated:
56+
57+
:::code language="bicep" source="../snippets/azure/AppHost/config.module.bicep":::
58+
59+
The preceding Bicep is a module that provisions an Azure App Configuration resource. Additionally, role assignments are created for the Azure resource in a separate module:
60+
61+
:::code language="bicep" source="../snippets/azure/AppHost/config-roles.module.bicep":::
62+
63+
The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly will be overwritten, so make changes through the C# provisioning APIs to ensure they're reflected in the generated files.
64+
65+
#### Customize provisioning infrastructure
66+
67+
All .NET 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 `sku`, purge protection, and more. The following example demonstrates how to customize the Azure App Configuration resource:
68+
69+
:::code language="csharp" source="../snippets/azure/AppHost/Program.ConfigureAppConfigInfra.cs" id="configure":::
70+
71+
The preceding code:
72+
73+
- Chains a call to the <xref:Aspire.Hosting.AzureProvisioningResourceExtensions.ConfigureInfrastructure*> API:
74+
- The `infra` parameter is an instance of the <xref:Aspire.Hosting.Azure.AzureResourceInfrastructure> type.
75+
- The provisionable resources are retrieved by calling the <xref:Azure.Provisioning.Infrastructure.GetProvisionableResources> method.
76+
- The single <xref:Azure.Provisioning.AppConfiguration.AppConfigurationStore> is retrieved.
77+
- The <xref:Azure.Provisioning.AppConfiguration.AppConfigurationStore.SkuName?displayProperty=nameWithType> is assigned to `Free`.
78+
- A tag is added to the App Configuration store with a key of `ExampleKey` and a value of `Example value`.
79+
80+
There are many more configuration options available to customize the Azure App Configuration resource. For more information, see <xref:Azure.Provisioning.AppConfiguration>. For more information, see [Azure.Provisioning customization](integrations-overview.md#azureprovisioning-customization).
81+
82+
### Use existing Azure App Configuration resource
83+
84+
You might have an existing Azure App Configuration store that you want to connect to. If you want to use an existing Azure App Configuration store, you can do so by calling the <xref:Aspire.Hosting.ExistingAzureResourceExtensions.AsExisting*> method. This method accepts the config store and resource group names as parameters, and uses it to connect to the existing Azure App Configuration store resource.
85+
86+
```csharp
87+
var builder = DistributedApplication.CreateBuilder(args);
88+
89+
var configName = builder.AddParameter("configName");
90+
var configResourceGroupName = builder.AddParameter("configResourceGroupName");
91+
92+
var appConfig = builder.AddAzureAppConfiguration("config")
93+
.AsExisting(configName, configResourceGroupName);
94+
95+
// After adding all resources, run the app...
96+
97+
builder.Build().Run();
98+
```
99+
100+
For more information, see [Use existing Azure resources](integrations-overview.md#use-existing-azure-resources).
101+
102+
### Connect to an existing Azure App Configuration store
103+
104+
An alternative approach to using the `*AsExisting` APIs enables the addition of a connection string instead, where the app host uses configuration to resolve the connection information. To add a connection to an existing Azure App Configuration store, call the <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString*> method:
105+
106+
```csharp
107+
var builder = DistributedApplication.CreateBuilder(args);
108+
109+
var config = builder.AddConnectionString("config");
110+
111+
builder.AddProject<Projects.WebApplication>("web")
112+
.WithReference(config);
113+
114+
// After adding all resources, run the app...
115+
```
116+
117+
[!INCLUDE [connection-strings-alert](../includes/connection-strings-alert.md)]
118+
119+
The connection string is configured in the app host's configuration, typically under [User Secrets](/aspnet/core/security/app-secrets), under the `ConnectionStrings` section. The app host injects this connection string as an environment variable into all dependent resources, for example:
120+
121+
```json
122+
{
123+
"ConnectionStrings": {
124+
"config": "https://{store_name}.azconfig.io"
125+
}
126+
}
127+
```
128+
129+
The dependent resource can access the injected connection string by calling the <xref:Microsoft.Extensions.Configuration.ConfigurationExtensions.GetConnectionString*> method, and passing the connection name as the parameter, in this case `"config"`. The `GetConnectionString` API is shorthand for `IConfiguration.GetSection("ConnectionStrings")[name]`.
130+
131+
## Client integration
132+
133+
To get started with the .NET Aspire Azure App Configuration client integration, install the [📦 Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration](https://www.nuget.org/packages/Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration) NuGet package in the client-consuming project, that is, the project for the application that uses the App Configuration client. The App Configuration client integration registers a <xref:Microsoft.Azure.Cosmos.CosmosClient> instance that you can use to interact with App Configuration.
134+
135+
### [.NET CLI](#tab/dotnet-cli)
136+
137+
```dotnetcli
138+
dotnet add package Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration
139+
```
140+
141+
### [PackageReference](#tab/package-reference)
142+
143+
```xml
144+
<PackageReference Include="Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration"
145+
Version="*" />
146+
```
147+
148+
---
149+
150+
In the :::no-loc text="Program.cs"::: file of your client-consuming project, call the `AddAzureAppConfiguration` extension method on any <xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder> to register the required services to flow Azure App Configuration values into the <xref:Microsoft.Extensions.Configuration.IConfiguration> instance for use via the dependency injection container. The method takes a connection name parameter.
151+
152+
```csharp
153+
builder.AddAzureAppConfiguration(connectionName: "config");
154+
```
155+
156+
> [!TIP]
157+
> The `connectionName` parameter must match the name used when adding the App Configuration resource in the app host project. In other words, when you call `AddAzureAppConfiguration` in the app host and provide a name of `config` that same name should be used when calling `AddAzureAppConfiguration` in the client-consuming project. For more information, see [Add Azure App Configuration resource](#add-azure-app-configuration-resource).
158+
159+
You can then retrieve the <xref:Microsoft.Extensions.Configuration.IConfiguration> instance using dependency injection. For example, to retrieve the client from an example service:
160+
161+
```csharp
162+
public class ExampleService(IConfiguration configuration)
163+
{
164+
private readonly string _someValue = configuration["SomeKey"];
165+
}
166+
```
167+
168+
### Use feature flags
169+
170+
To use feature flags, install the [📦 Microsoft.FeatureManagement](https://www.nuget.org/packages/Microsoft.FeatureManagement) NuGet package:
171+
172+
### [.NET CLI](#tab/dotnet-cli)
173+
174+
```dotnetcli
175+
dotnet add package Microsoft.FeatureManagement
176+
```
177+
178+
### [PackageReference](#tab/package-reference)
179+
180+
```xml
181+
<PackageReference Include="Microsoft.FeatureManagement"
182+
Version="*" />
183+
```
184+
185+
---
186+
187+
App Configuration doesn't load feature flags by default. To load feature flags, you pass the `Action<AzureAppConfigurationOptions> configureOptions` delegate when calling `builder.AddAzureAppConfiguration`.
188+
189+
```csharp
190+
builder.AddAzureAppConfiguration(
191+
"config",
192+
configureOptions: options => options.UseFeatureFlags());
193+
194+
// Register feature management services
195+
builder.Services.AddFeatureManagement();
196+
```
197+
198+
You can then use <xref:Microsoft.FeatureManagement.IFeatureManager> to evaluate feature flags in your app. Consider the following example ASP.NET Core Minimal API app:
199+
200+
```csharp
201+
using Microsoft.Extensions.Hosting;
202+
using Microsoft.FeatureManagement;
203+
204+
var builder = WebApplication.CreateBuilder(args);
205+
206+
builder.AddAzureAppConfiguration(
207+
"config",
208+
configureOptions: options => options.UseFeatureFlags());
209+
210+
// Register feature management services
211+
builder.Services.AddFeatureManagement();
212+
213+
var app = builder.Build();
214+
215+
app.MapGet("/", async (IFeatureManager featureManager) =>
216+
{
217+
if (await featureManager.IsEnabledAsync("NewFeature"))
218+
{
219+
return Results.Ok("New feature is enabled!");
220+
}
221+
222+
return Results.Ok("Using standard implementation.");
223+
});
224+
225+
app.Run();
226+
```
227+
228+
For more information, see [.NET Feature Management](/azure/azure-app-configuration/feature-management-dotnet-reference).
229+
230+
### Configuration
231+
232+
The .NET Aspire Azure App Configuration library provides multiple options to configure the Azure App Configuration connection based on the requirements and conventions of your project. The App Config endpoint is required to be supplied, either in `AzureAppConfigurationSettings.Endpoint` or using a connection string.
233+
234+
#### Use a connection string
235+
236+
When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `builder.AddAzureAppConfiguration()`:
237+
238+
```csharp
239+
builder.AddAzureAppConfiguration("config");
240+
```
241+
242+
Then the App Configuration endpoint is retrieved from the `ConnectionStrings` configuration section. The App Configuration store URI works with the `AzureAppConfigurationSettings.Credential` property to establish a connection. If no credential is configured, the <xref:Azure.Identity.DefaultAzureCredential> is used.
243+
244+
```json
245+
{
246+
"ConnectionStrings": {
247+
"config": "https://{store_name}.azconfig.io"
248+
}
249+
}
250+
```
251+
252+
#### Use configuration providers
253+
254+
The .NET Aspire Azure App Configuration library supports <xref:Microsoft.Extensions.Configuration>. It loads the `AzureAppConfigurationSettings` from configuration by using the `Aspire:Microsoft:Extensions:Configuration:AzureAppConfiguration` key. Example _appsettings.json_ that configures some of the options:
255+
256+
```json
257+
{
258+
"Aspire": {
259+
"Microsoft": {
260+
"Extensions": {
261+
"Configuration": {
262+
"AzureAppConfiguration": {
263+
"Endpoint": "YOUR_APPCONFIGURATION_ENDPOINT_URI"
264+
}
265+
}
266+
}
267+
}
268+
}
269+
}
270+
```
271+
272+
For the complete App Configuration client integration JSON schema, see [./ConfigurationSchema.json](https://github.com/dotnet/aspire/blob/main/src/Components/Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration/ConfigurationSchema.json).
273+
274+
#### Use inline delegates
275+
276+
You can also pass the `Action<AzureAppConfigurationSettings> configureSettings` delegate to set up some or all the options inline, for example to set App Configuration endpoint from code:
277+
278+
```csharp
279+
builder.AddAzureAppConfiguration(
280+
"config",
281+
configureSettings: settings => settings.Endpoint = "http://YOUR_URI");
282+
```
283+
284+
[!INCLUDE [integration-observability-and-telemetry](../includes/integration-observability-and-telemetry.md)]
285+
286+
#### Logging
287+
288+
The .NET Aspire Azure App Configuration integration uses the following log categories:
289+
290+
- `Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh`
291+
292+
#### Tracing
293+
294+
The .NET Aspire Azure App Configuration integration doesn't make use any activity sources thus no tracing is available.
295+
296+
#### Metrics
297+
298+
The .NET Aspire Azure App Configuration integration currently doesn't support metrics.
299+
300+
## See also
301+
302+
- [Azure App Configuration documentation](/azure/azure-app-configuration/)
303+
- [.NET Aspire integrations overview](../fundamentals/integrations-overview.md)
304+
- [.NET Aspire Azure integrations overview](../azure/integrations-overview.md)
305+
- [.NET Aspire GitHub repo](https://github.com/dotnet/aspire)

‎docs/database/azure-cosmos-db-integration.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: .NET Aspire Azure Cosmos DB integration
33
description: Learn how to install and configure the .NET Aspire Azure Cosmos DB integration to connect to existing Cosmos DB instances or create new instances from .NET with the Azure Cosmos DB emulator.
4-
ms.date: 04/10/2025
4+
ms.date: 05/15/2025
55
uid: dotnet/aspire/azure-cosmos-db-integration
66
---
77

@@ -247,7 +247,7 @@ Then the connection string is retrieved from the `ConnectionStrings` configurati
247247
}
248248
```
249249

250-
For more information on how to format this connection string, see the ConnectionString documentation.
250+
For more information, see the [ConnectionString documentation](/azure/cosmos-db/nosql/how-to-dotnet-get-started#connect-with-a-connection-string).
251251

252252
#### Use configuration providers
253253

‎docs/snippets/azure/AppHost/Program.ConfigureAppConfigInfra.cs‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
using Azure.Provisioning.AppConfiguration;
2+
3+
internal static partial class Program
4+
{
5+
public static void ConfigureAppConfigInfra(IDistributedApplicationBuilder builder)
6+
{
7+
// <configure>
8+
builder.AddAzureAppConfiguration("config")
9+
.ConfigureInfrastructure(infra =>
10+
{
11+
var appConfigStore = infra.GetProvisionableResources()
12+
.OfType<AppConfigurationStore>()
13+
.Single();
14+
15+
appConfigStore.SkuName = "Free";
16+
appConfigStore.EnablePurgeProtection = true;
17+
appConfigStore.Tags.Add("ExampleKey", "Example value");
18+
});
19+
// </configure>
20+
}
21+
}

‎docs/toc.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,9 @@ items:
162162
href: azure/user-assigned-managed-identity.md
163163
- name: Manage role assignments
164164
href: azure/role-assignments.md
165+
- name: Azure App Configuration
166+
displayName: app configuration,configuration
167+
href: azure/azure-app-configuration-integration.md
165168
- name: Azure AI Inference (Preview)
166169
displayName: azure ai,inference
167170
href: azureai/azureai-inference-integration.md

0 commit comments

Comments
 (0)