Azure.Data.AppConfiguration
1.5.0
Prefix Reserved
dotnet add package Azure.Data.AppConfiguration --version 1.5.0
NuGet\Install-Package Azure.Data.AppConfiguration -Version 1.5.0
<PackageReference Include="Azure.Data.AppConfiguration" Version="1.5.0" />
paket add Azure.Data.AppConfiguration --version 1.5.0
#r "nuget: Azure.Data.AppConfiguration, 1.5.0"
// Install Azure.Data.AppConfiguration as a Cake Addin #addin nuget:?package=Azure.Data.AppConfiguration&version=1.5.0 // Install Azure.Data.AppConfiguration as a Cake Tool #tool nuget:?package=Azure.Data.AppConfiguration&version=1.5.0
Azure App Configuration client library for .NET
Azure App Configuration is a managed service that helps developers centralize their application and feature settings simply and securely.
Use the client library for App Configuration to:
- Create and manage centrally stored application configuration settings
- Retrieve configuration settings from a specific point in time
Source code | Package (NuGet) | API reference documentation | Product documentation | Samples
Getting started
Install the package
Install the Azure App Configuration client library for .NET with NuGet:
dotnet add package Azure.Data.AppConfiguration
Prerequisites
- An Azure subscription.
- An existing Configuration Store.
If you need to create a Configuration Store, you can use the Azure Portal or Azure CLI.
You can use the Azure CLI to create the Configuration Store with the following command:
az appconfig create --name <config-store-name> --resource-group <resource-group-name> --location eastus
Authenticate the client
In order to interact with the App Configuration service, you'll need to create an instance of the Configuration Client class. To make this possible, you'll need the connection string of the Configuration Store.
Get credentials
Use the Azure CLI snippet below to get the connection string from the Configuration Store.
az appconfig credential list --name <config-store-name>
Alternatively, get the connection string from the Azure Portal.
Create ConfigurationClient
Once you have the value of the connection string, you can create the ConfigurationClient:
string connectionString = "<connection_string>";
var client = new ConfigurationClient(connectionString);
Create ConfigurationClient with Azure Active Directory Credential
Client subscription key authentication is used in most of the examples in this getting started guide, but you can also authenticate with Azure Active Directory using the Azure Identity library. To use the DefaultAzureCredential provider shown below, or other credential providers provided with the Azure SDK, please install the Azure.Identity package:
dotnet add package Azure.Identity
You will also need to register a new AAD application and grant access to Configuration Store by assigning the "App Configuration Data Reader"
or "App Configuration Data Owner"
role to your service principal.
Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.
string endpoint = "<endpoint>";
var client = new ConfigurationClient(new Uri(endpoint), new DefaultAzureCredential());
Key concepts
Configuration Setting
A Configuration Setting is the fundamental resource within a Configuration Store. In its simplest form, it is a key and a value. However, there are additional properties such as the modifiable content type and tags fields that allow the value to be interpreted or associated in different ways.
The Label property of a Configuration Setting provides a way to separate Configuration Settings into different dimensions. These dimensions are user defined and can take any form. Some common examples of dimensions to use for a label include regions, semantic versions, or environments. Many applications have a required set of configuration keys that have varying values as the application exists across different dimensions.
For example, MaxRequests may be 100 in "NorthAmerica" and 200 in "WestEurope". By creating a Configuration Setting named MaxRequests with a label of "NorthAmerica" and another, only with a different value, with a "WestEurope" label, an application can seamlessly retrieve Configuration Settings as it runs in these two dimensions.
Azure App Configuration allows users to create a point-in-time snapshot of their configuration store, providing them with the ability to treat settings as one consistent version. This feature enables applications to hold a consistent view of configuration, ensuring that there are no version mismatches to individual settings due to reading as updates were made. Snapshots are immutable, ensuring that configuration can confidently be rolled back to a last-known-good configuration in the event of a problem.
Thread safety
We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.
Additional concepts
Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime
Examples
The following sections provide several code snippets covering some of the most common Configuration Service tasks. Note that there are sync and async methods available for both.
- Create a Configuration Setting
- Retrieve a Configuration Setting
- Update an existing Configuration Setting
- Delete a Configuration Setting
- Create a Snapshot
- Retrieve a Snapshot
- Archive a Snapshot
- Recover a snapshot
- Retrieve all Snapshots
Create a Configuration Setting
Create a Configuration Setting to be stored in the Configuration Store. There are two ways to store a Configuration Setting:
- AddConfigurationSetting creates a setting only if the setting does not already exist in the store.
- SetConfigurationSetting creates a setting if it doesn't exist or overrides an existing setting.
string connectionString = "<connection_string>";
var client = new ConfigurationClient(connectionString);
var settingToCreate = new ConfigurationSetting("some_key", "some_value");
ConfigurationSetting setting = client.SetConfigurationSetting(settingToCreate);
Retrieve a Configuration Setting
Retrieve a previously stored Configuration Setting by calling GetConfigurationSetting. This snippet assumes the setting "some_key" exists in the configuration store.
string connectionString = "<connection_string>";
var client = new ConfigurationClient(connectionString);
ConfigurationSetting setting = client.GetConfigurationSetting("some_key");
Update an existing Configuration Setting
Update an existing Configuration Setting by calling SetConfigurationSetting. This snippet assumes the setting "some_key" exists in the configuration store.
string connectionString = "<connection_string>";
var client = new ConfigurationClient(connectionString);
ConfigurationSetting setting = client.SetConfigurationSetting("some_key", "new_value");
Delete a Configuration Setting
Delete an existing Configuration Setting by calling DeleteConfigurationSetting. This snippet assumes the setting "some_key" exists in the configuration store.
string connectionString = "<connection_string>";
var client = new ConfigurationClient(connectionString);
client.DeleteConfigurationSetting("some_key");
Create a Snapshot
To create a snapshot, you need to instantiate the ConfigurationSnapshot
class and specify filters to determine which configuration settings should be included. The creation process is a Long-Running Operation (LRO) and can be achieved by calling the CreateSnapshot
method.
var settingsFilter = new List<ConfigurationSettingsFilter> { new ConfigurationSettingsFilter("some_key") };
var settingsSnapshot = new ConfigurationSnapshot(settingsFilter);
var snapshotName = "some_snapshot";
var operation = client.CreateSnapshot(WaitUntil.Completed, snapshotName, settingsSnapshot);
var createdSnapshot = operation.Value;
Console.WriteLine($"Created configuration snapshot: {createdSnapshot.Name}, Status: {createdSnapshot.Status}");
Retrieve a Snapshot
Once a configuration snapshot is created, you can retrieve it using the GetSnapshot
method.
var snapshotName = "some_snapshot";
ConfigurationSnapshot retrievedSnapshot = client.GetSnapshot(snapshotName);
Console.WriteLine($"Retrieved configuration snapshot: {retrievedSnapshot.Name}, status: {retrievedSnapshot.Status}");
Archive a Snapshot
To archive a snapshot, you can utilize the ArchiveSnapshot
method. This operation updates the status of the snapshot to archived
.
var snapshotName = "some_snapshot";
ConfigurationSnapshot archivedSnapshot = client.ArchiveSnapshot(snapshotName);
Console.WriteLine($"Archived configuration snapshot: {archivedSnapshot.Name}, status: {archivedSnapshot.Status}");
Recover a snapshot
You can recover an archived snapshot by using the RecoverSnapshot
method. This operation updates the status of the snapshot to ready
.
var snapshotName = "some_snapshot";
ConfigurationSnapshot recoveredSnapshot = client.RecoverSnapshot(snapshotName);
Console.WriteLine($"Recovered configuration snapshot: {recoveredSnapshot.Name}, status: {recoveredSnapshot.Status}");
Retrieve all Snapshots
To retrieve all snapshots, you can use the GetSnapshots
method.
var count = 0;
foreach (var item in client.GetSnapshots(new SnapshotSelector()))
{
count++;
Console.WriteLine($"Retrieved configuration snapshot: {item.Name}, status {item.Status}");
}
Console.WriteLine($"Total number of snapshots retrieved: {count}");
Troubleshooting
See our troubleshooting guide for details on how to diagnose various failure scenarios.
Next steps
More sample code
Several App Configuration client library samples are available to you in this GitHub repository. These include:
- Hello world: Create and delete a configuration setting.
- Hello world async with labels: Asynchronously create, update and delete configuration settings with labels.
- Make a configuration setting readonly: Make a configuration setting read-only, and then return it to a read-write state.
- Read revision history: Read the revision history of a configuration setting that has been changed.
- Get a setting if changed: Save bandwidth by using a conditional request to retrieve a setting only if it is different from your local copy.
- Update a setting if it hasn't changed: Prevent lost updates by using optimistic concurrency to update a setting only if your local updates were applied to the same version as the resource in the configuration store.
- Configuration settings snapshot: Create, retrieve and update status of a configuration settings snapshot.
- Create a mock client: Mock a client for testing.
For more details see the samples README.
Contributing
See the App Configuration CONTRIBUTING.md for details on building, testing, and contributing to this library.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Azure.Core (>= 1.42.0)
- Microsoft.Bcl.AsyncInterfaces (>= 6.0.0)
- System.Text.Json (>= 4.7.2)
NuGet packages (5)
Showing the top 5 NuGet packages that depend on Azure.Data.AppConfiguration:
Package | Downloads |
---|---|
Microsoft.Extensions.Configuration.AzureAppConfiguration
Microsoft.Extensions.Configuration.AzureAppConfiguration is a configuration provider for the .NET Core framework that allows developers to use Microsoft Azure App Configuration service as a configuration source in their applications. |
|
Microsoft.Configuration.ConfigurationBuilders.AzureAppConfiguration
A set of Configuration Builders for the .Net Framework that draw from Azure AppConfiguration stores. |
|
Olive.Azure
Olive Framework |
|
XPike.Configuration.Azure
xPike Configuration provider for Azure Application Configuration Service. |
|
SimpleToggle.Sources.Azure
Adds Azure toggle sources for Simple Toggle. Includes App Configuration sources. |
GitHub repositories (4)
Showing the top 4 popular GitHub repositories that depend on Azure.Data.AppConfiguration:
Repository | Stars |
---|---|
phongnguyend/Practical.CleanArchitecture
Full-stack .Net 8 Clean Architecture (Microservices, Modular Monolith, Monolith), Blazor, Angular 18, React 18, Vue 3, BFF with YARP, Domain-Driven Design, CQRS, SOLID, Asp.Net Core Identity Custom Storage, OpenID Connect, Entity Framework Core, OpenTelemetry, SignalR, Hosted Services, Health Checks, Rate Limiting, Cloud Services (Azure, AWS, GCP).
|
|
aspnet/MicrosoftConfigurationBuilders
Microsoft.Configuration.Builders
|
|
Azure/azure-sdk-tools
Tools repository leveraged by the Azure SDK team.
|
|
jongio/memealyzer
Memealyzer is an app built to demonstrate some the latest and greatest Azure tech to dev, debug, and deploy microservice applications.
|
Version | Downloads | Last updated |
---|---|---|
1.5.0 | 24,345 | 8/6/2024 |
1.4.1 | 2,735,867 | 4/18/2024 |
1.4.0 | 35,647 | 4/10/2024 |
1.4.0-beta.1 | 920 | 3/7/2024 |
1.3.0 | 6,063,982 | 11/8/2023 |
1.3.0-beta.3 | 482 | 10/9/2023 |
1.3.0-beta.2 | 57,880 | 7/11/2023 |
1.3.0-beta.1 | 14,023 | 10/10/2022 |
1.2.1 | 198,064 | 9/12/2023 |
1.2.0 | 31,234,339 | 10/4/2021 |
1.2.0-beta.1 | 477 | 8/10/2021 |
1.1.0 | 446,507 | 7/7/2021 |
1.1.0-beta.3 | 6,135 | 6/8/2021 |
1.1.0-beta.2 | 653 | 4/6/2021 |
1.1.0-beta.1 | 3,440 | 3/9/2021 |
1.0.3 | 119,603 | 5/14/2021 |
1.0.2 | 587,072 | 9/11/2020 |
1.0.1 | 105,122 | 7/7/2020 |
1.0.0 | 20,385,284 | 1/7/2020 |
1.0.0-preview.6 | 4,107 | 12/6/2019 |
1.0.0-preview.5 | 188,540 | 11/21/2019 |
1.0.0-preview.4 | 154,414 | 10/31/2019 |
1.0.0-preview.3 | 880 | 10/17/2019 |
1.0.0-preview.2 | 375 | 10/7/2019 |
1.0.0-preview.1 | 426 | 9/10/2019 |