Skip to content

Commit 28d9741

Browse files
zhiyuanliang-mszhiyuanliang-ms
committed
wip
1 parent 8985b1d commit 28d9741

File tree

2 files changed

+175
-14
lines changed

2 files changed

+175
-14
lines changed

‎articles/azure-app-configuration/reference-dotnet-provider.md

Lines changed: 174 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -17,39 +17,200 @@ ms.date: 04/29/2025
1717

1818
[![Microsoft.Extensions.Configuration.AzureAppConfiguration](https://img.shields.io/nuget/v/Microsoft.Extensions.Configuration.AzureAppConfiguration?label=Microsoft.Extensions.Configuration.AzureAppConfiguration)](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.AzureAppConfiguration)
1919

20-
Azure App Configuration is a managed service that helps developers centralize their application configurations simply and securely. The .NET configuration provider library enables loading configuration from an Azure App Configuration store in a managed way. This client library adds additional functionality above the Azure SDK for .NET.
20+
Azure App Configuration is a managed service that helps developers centralize their application configurations simply and securely. The .NET configuration provider library enables loading configuration from an Azure App Configuration store in a managed way. This client library adds additional [functionality](./configuration-provider-overview.md#feature-development-status) above the Azure SDK for .NET.
2121

2222
## Load configuration
2323

24+
The Azure App Configuration .NET configuration provider integrates with the .NET configuration system, making it easy to load configuration values from your Azure App Configuration store. You can add the provider during application startup and use it alongside other configuration sources.
25+
26+
To use .NET configuration provider, install the package:
27+
28+
```console
29+
dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration
30+
```
31+
32+
Connect to your Azure App Configuration store by calling the `Connect` method on the `AzureAppConfigurationOptions`. The configuration provider follows a builder pattern, accepting an `Action<AzureAppConfigurationOptions>` delegate parameter that allows you to configure the provider.
33+
34+
### [Microsoft Entra ID](#tab/entra-id)
35+
36+
You use the `DefaultAzureCredential` to authenticate to your App Configuration store. Follow the [instructions](./concept-enable-rbac.md#authentication-with-token-credentials) to assign your credential the **App Configuration Data Reader** role.
37+
38+
```csharp
39+
using Microsoft.Extensions.Configuration;
40+
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
41+
using Azure.Identity;
42+
43+
var builder = new ConfigurationBuilder();
44+
builder.AddAzureAppConfiguration(options =>
45+
{
46+
string endpoint = Environment.GetEnvironmentVariable("Endpoint");
47+
options.Connect(new Uri(endpoint), new DefaultAzureCredential());
48+
});
49+
50+
var config = builder.Build();
51+
Console.WriteLine(config["TestApp:Settings:Message"] ?? "Hello world!");
52+
```
53+
54+
> [!NOTE]
55+
> In an ASP.NET Core application or a background service, you might call `AddAzureAppConfiguration` on `builder.Configuration`.
56+
> ```csharp
57+
> var builder = WebApplication.CreateBuilder(args);
58+
> builder.Configuration.AddAzureAppConfiguration(options =>
59+
> {
60+
> string endpoint = Environment.GetEnvironmentVariable("Endpoint");
61+
> options.Connect(new Uri(endpoint), new DefaultAzureCredential());
62+
> });
63+
> ```
64+
65+
### [Connection string](#tab/connection-string)
66+
67+
```csharp
68+
using Microsoft.Extensions.Configuration;
69+
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
70+
using Azure.Identity;
71+
72+
var builder = new ConfigurationBuilder();
73+
builder.AddAzureAppConfiguration(options =>
74+
{
75+
string connectionString = Environment.GetEnvironmentVariable("ConnectionString");
76+
options.Connect(connectionString);
77+
});
78+
79+
var config = builder.Build();
80+
Console.WriteLine(config["TestApp:Settings:Message"] ?? "Hello world!");
81+
```
82+
83+
> [!NOTE]
84+
> In an ASP.NET Core application or a background service, you might call `AddAzureAppConfiguration` on `builder.Configuration`.
85+
> ```csharp
86+
> var builder = WebApplication.CreateBuilder(args);
87+
> builder.Configuration.AddAzureAppConfiguration(options =>
88+
> {
89+
> string connectionString = Environment.GetEnvironmentVariable("ConnectionString");
90+
> options.Connect(connectionString);
91+
> });
92+
> ```
93+
94+
---
95+
2496
### Consume configuration
2597
98+
After adding the Azure App Configuration provider, you can access your configuration values in several ways:
99+
100+
#### 1. Direct access
101+
102+
The simplest approach is to retrieve values directly from the `IConfiguration` instance:
103+
104+
```csharp
105+
// Directly get the configuration
106+
string message = configuration["TestApp:Settings:Message"];
107+
108+
IConfigurationSection settingsSection = configuration.GetSection("TestApp:Settings");
109+
```
110+
111+
#### 2. Dependency injection with IConfiguration
112+
113+
In services or controllers, you can inject and use the `IConfiguration` interface directly:
114+
115+
```csharp
116+
public class WeatherService
117+
{
118+
private readonly IConfiguration _configuration;
119+
120+
public WeatherService(IConfiguration configuration)
121+
{
122+
_configuration = configuration;
123+
}
124+
125+
public Task<WeatherForecast> GetForecastAsync()
126+
{
127+
// Access configuration values directly from the injected instance
128+
string apiEndpoint = _configuration["TestApp:Weather:ApiEndpoint"];
129+
130+
...
131+
132+
return Task.FromResult(new WeatherForecast());
133+
}
134+
}
135+
```
136+
137+
#### 3. Options pattern for strongly-typed configuration
138+
139+
```csharp
140+
// Define a strongly-typed settings class
141+
public class Settings
142+
{
143+
public string BackgroundColor { get; set; }
144+
public long FontSize { get; set; }
145+
public string FontColor { get; set; }
146+
public string Message { get; set; }
147+
}
148+
149+
builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));
150+
```
151+
26152
### JSON Content Type Handling
27153

154+
You can create JSON key-values in App Configuration. For more information, go to [Use content type to store JSON key-values in App Configuration](./howto-leverage-json-content-type.md).
155+
28156
### Load specific key-values using selectors
29157

30-
### Trim prefix from keys
158+
By default, the configuration provider will load all key-values with no label from the App Configuration. You can selectively load key-values from your App Configuration store by calling `Select` method on `AzureAppConfigurationOptions`.
31159

32-
## Configuration refresh
160+
```csharp
161+
builder.AddAzureAppConfiguration(options =>
162+
{
163+
options.Connect(new Uri(endpoint), new DefaultAzureCredential())
164+
// Load configuration values with prefix "TestApp:" and no label
165+
.Select("App:Settings:*")
166+
// Load configuration values with prefix "TestApp:" and "Prod" label
167+
.Select("App:Settings:*", "Prod")
168+
});
169+
```
33170

34-
### Refresh on sentinel key (Legacy)
171+
The `Select` method takes two parameters, the first parameter is a key filter that specifies which keys to load, and the second parameter is a label filter that specifies which key-values with specific labels to load.
35172

36-
## Feature flag
173+
> [!NOTE]
174+
> When multiple `Select` calls include overlapping keys, later calls take precedence over earlier ones.
37175
38-
## Configuration Setting Mapping
176+
#### Key Filter
39177

40-
## Distributed tracing
178+
The key filter parameter determines which configuration keys to include:
41179

42-
## Key Vault reference
180+
- **Exact match**: Using a specific string will match only keys that exactly match the filter.
181+
- **Prefix match**: Adding an asterisk (`*`) at the end creates a prefix filter (e.g., `App:Settings:*` loads all keys starting with "App:Settings:").
182+
- **Multiple key selection**: Using a comma (`,`) allows selection of multiple explicit keys (e.g., `Key1,Key2,Key3`).
183+
- **Reserved characters**: The characters asterisk (`*`), comma (`,`), and backslash (`\`) are reserved and must be escaped with a backslash when used in key names (e.g. the key filter `a\\b\,\*c*` returns all key-values whose key starts with `a\b,*c`.).
184+
185+
> [!NOTE]
186+
> You cannot combine wildcard prefix matching with comma-separated filters in the same `Select` call. For example, `abc*,def` is not supported, but you can make separate `Select` calls with `abc*` and `def`.
187+
188+
#### Label Filter
189+
190+
The label filter parameter selects key-values with a specific label. If not specified, the built-in `LabelFilter.Null` will be used.
191+
192+
> [!NOTE]
193+
> The characters asterisk (`*`) and comma (`,`), are not supported for label filter. Backslash (`\`) character is reserved and must be escaped using another backslash (`\`).
194+
195+
### Trim prefix from keys
43196

44-
## Snapshot
197+
When loading configuration values with specific prefixes, you can use the `TrimKeyPrefix` method to remove those prefixes from the keys in your configuration. This creates cleaner configuration keys in your application while maintaining organization in your App Configuration store.
45198

46-
## Configurable Startup Time-out
199+
```csharp
200+
builder.AddAzureAppConfiguration(options =>
201+
{
202+
options.Connect(new Uri(endpoint), new DefaultAzureCredential())
203+
// Load configuration values with prefix "TestApp:" and trim the prefix
204+
.Select("TestApp:*")
205+
.TrimKeyPrefix("TestApp:");
206+
});
207+
```
47208

48-
## Geo-replication
209+
For example, if your App Configuration store contains a key named `TestApp:Settings:Message`, it will be accessible in your application as `Settings:Message` after trimming the `TestApp:` prefix.
49210

50211
## Next steps
51212

52-
To learn how to use the .NET configuration provider, continue to the following tutorial.
213+
To learn how to use the JavaScript configuration provider, continue to the following tutorial.
53214

54215
> [!div class="nextstepaction"]
55-
> [Use dynamic configuration in JavaScript](./enable-dynamic-configuration-javascript.md)
216+
> [Enable dynamic configuration in an ASP.NET web app](./enable-dynamic-configuration-aspnet-netfx.md)

‎articles/azure-app-configuration/reference-javascript-provider.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ ms.date: 02/02/2025
1717

1818
[![configuration-provider-npm-package](https://img.shields.io/npm/v/@azure/app-configuration-provider?label=@azure/app-configuration-provider)](https://www.npmjs.com/package/@azure/app-configuration-provider)
1919

20-
Azure App Configuration is a managed service that helps developers centralize their application configurations simply and securely. The JavaScript configuration provider library enables loading configuration from an Azure App Configuration store in a managed way. This client library adds additional functionality above the Azure SDK for JavaScript.
20+
Azure App Configuration is a managed service that helps developers centralize their application configurations simply and securely. The JavaScript configuration provider library enables loading configuration from an Azure App Configuration store in a managed way. This client library adds additional [functionality](./configuration-provider-overview.md#feature-development-status) above the Azure SDK for JavaScript.
2121

2222
## Load configuration
2323

0 commit comments

Comments
 (0)