Azure App Configuration is a managed service that helps developers centralize their application configurations simply and securely.
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. Use App Configuration to store all the settings for your application and secure their accesses in one place.
Use the client library for App Configuration to create and manage application configuration settings.
Source code | Package (Maven) | API reference documentation | Product documentation | Samples
- Java Development Kit (JDK) with version 8 or above
- Azure Subscription
- App Configuration Store
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-data-appconfiguration</artifactId>
<version>1.0.0-preview.6</version>
</dependency>All client libraries, by default, use Netty HTTP client. Adding the above dependency will automatically configure AppConfiguration to use Netty HTTP client.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-core-http-netty</artifactId>
<version>1.0.0</version>
</dependency>If, instead of Netty it is preferable to use OkHTTP, there is a HTTP client available for that too. Exclude the default Netty and include OkHTTP client in your pom.xml.
<!-- Add AppConfiguration dependency without Netty HTTP client -->
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-data-appconfiguration</artifactId>
<version>1.0.0-preview.6</version>
<exclusions>
<exclusion>
<groupId>com.azure</groupId>
<artifactId>azure-core-http-netty</artifactId>
</exclusion>
</exclusions>
</dependency><!-- Add OkHTTP client to use with AppConfiguration -->
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-core-http-okhttp</artifactId>
<version>1.0.0</version>
</dependency>When an HTTP client is included on the classpath, as shown above, it is not necessary to specify it in the client library builders, unless you want to customize the HTTP client in some fashion. If this is desired, the httpClient builder method is often available to achieve just this, by allowing users to provide a custom (or customized) com.azure.core.http.HttpClient instances.
For starters, by having the Netty or OkHTTP dependencies on your classpath, as shown above, you can create new instances of these HttpClient types using their builder APIs. For example, here is how you would create a Netty HttpClient instance:
HttpClient client = new NettyAsyncHttpClientBuilder()
.port(8080)
.wiretap(true)
.build();To create a Configuration Store you can use the Azure Portal or Azure CLI.
You need to install the Azure App Configuration CLI extension first by executing the following command:
az extension add -n appconfigAfter that, create the Configuration Store:
az appconfig create --name <config-store-name> --resource-group <resource-group-name> --location eastusIn 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.
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.
Once you have the value of the connection string you can create the configuration client:
ConfigurationClient client = new ConfigurationClientBuilder()
.connectionString(connectionString)
.buildClient();or
ConfigurationAsyncClient client = new ConfigurationClientBuilder()
.connectionString(connectionString)
.buildAsyncClient();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, in the "WestEurope" label, a solution can be achieved that allows the application to seamlessly retrieve Configuration Settings as it runs in these two dimensions.
The client performs the interactions with the App Configuration service, getting, setting, deleting, and selecting configuration settings. An asynchronous, ConfigurationAsyncClient, and synchronous, ConfigurationClient, client exists in the SDK allowing for selection of a client based on an application's use case.
An application that needs to retrieve startup configurations is better suited using the synchronous client, for example setting up a SQL connection.
ConfigurationClient client = new ConfigurationClientBuilder()
.connectionString(connectionString)
.buildClient();
// urlLabel is optional
String url = client.getConfigurationSetting(urlKey, urlLabel).getValue();
Connection conn;
try {
conn = DriverManager.getConnection(url);
} catch (SQLException ex) {
System.out.printf("Failed to get connection using url %s", url);
}An application that has a large set of configurations that it needs to periodically update is be better suited using the asynchronous client, for example all settings with a specific label are periodically updated.
ConfigurationAsyncClient client = new ConfigurationClientBuilder()
.connectionString(appConfigConnectionString)
.buildAsyncClient();
client.listConfigurationSettings(new SettingSelector().setLabels(periodicUpdateLabel))
.subscribe(setting -> updateConfiguration(setting));The following sections provide several code snippets covering some of the most common configuration service tasks, including:
Create a configuration client by using ConfigurationClientBuilder by passing connection string.
ConfigurationClient client = new ConfigurationClientBuilder()
.connectionString(connectionString)
.buildClient();Create a configuration setting to be stored in the configuration store. There are two ways to store a configuration setting:
addConfigurationSettingcreates a setting only if the setting does not already exist in the store.
ConfigurationSetting setting = configurationClient.addConfigurationSetting("new_key", "new_label", "new_value");Or
setConfigurationSettingcreates a setting if it doesn't exist or overrides an existing setting.
ConfigurationSetting setting = client.setConfigurationSetting("some_key", "some_label", "some_value");Retrieve a previously stored configuration setting by calling getConfigurationSetting.
ConfigurationSetting setting = client.setConfigurationSetting("some_key", "some_label", "some_value");
ConfigurationSetting retrievedSetting = client.getConfigurationSetting("some_key", "some_label");For conditional request, if you want to conditionally fetch a configuration setting, set ifChanged to true.
When ifChanged is true, the configuration setting is only retrieved if it is different than the given setting.
This is determined by comparing the ETag of the setting to the one in the service to see if they are the same or not.
If the ETags are not the same, it means the configuration setting is different, and its value is retrieved.
Response<ConfigurationSetting> settingResponse = client.getConfigurationSettingWithResponse(setting, null, true, Context.NONE);Update an existing configuration setting by calling setConfigurationSetting.
ConfigurationSetting setting = client.setConfigurationSetting("some_key", "some_label", "some_value");
ConfigurationSetting updatedSetting = client.setConfigurationSetting("some_key", "some_label", "new_value");For conditional request, if you want to conditionally update a configuration setting, set the ifUnchanged parameter to
true. When ifUnchanged is true, the configuration setting is only updated if it is same as the given setting.
This is determined by comparing the ETag of the setting to the one in the service to see if they are the same or not.
If the ETag are the same, it means the configuration setting is same, and its value is updated.
Response<ConfigurationSetting> settingResponse = client.setConfigurationSettingWithResponse(setting, true, Context.NONE);Delete an existing configuration setting by calling deleteConfigurationSetting.
ConfigurationSetting setting = client.setConfigurationSetting("some_key", "some_label", "some_value");
ConfigurationSetting deletedSetting = client.deleteConfigurationSetting("some_key", "some_label");For conditional request, if you want to conditionally delete a configuration setting, set the ifUnchanged parameter
to true. When ifUnchanged parameter to true. When ifUnchanged is true, the configuration setting is only deleted if
it is same as the given setting. This is determined by comparing the ETag of the setting to the one in the service
to see if they are the same or not. If the ETag are same, it means the configuration setting is same, and its value is deleted.
Response<ConfigurationSetting> settingResponse = client.deleteConfigurationSettingWithResponse(setting, true, Context.NONE);List multiple configuration settings by calling listConfigurationSettings.
Pass a null SettingSelector into the method if you want to fetch all the configuration settings and their fields.
String key = "some_key";
String key2 = "new_key";
client.setConfigurationSetting(key, "some_label", "some_value");
client.setConfigurationSetting(key2, "new_label", "new_value");
SettingSelector selector = new SettingSelector().setKeys(key, key2);
PagedIterable<ConfigurationSetting> settings = client.listConfigurationSettings(selector);List all revisions of a configuration setting by calling listRevisions.
String key = "revisionKey";
client.setConfigurationSetting(key, "some_label", "some_value");
client.setConfigurationSetting(key, "new_label", "new_value");
SettingSelector selector = new SettingSelector().setKeys(key);
PagedIterable<ConfigurationSetting> settings = client.listRevisions(selector);Set a configuration setting to read-only status.
client.setConfigurationSetting("some_key", "some_label", "some_value");
ConfigurationSetting setting = client.setReadOnly("some_key", "some_label");Clear read-only from a configuration setting.
ConfigurationSetting setting = client.clearReadOnly("some_key", "some_label");When you interact with App Configuration using this Java client library, errors returned by the service correspond to the same HTTP status codes returned for REST API requests. For example, if you try to retrieve a configuration setting that doesn't exist in your configuration store, a 404 error is returned, indicating Not Found.
- Samples are explained in detail here.
- Quickstart: Create a Java Spring app with App Configuration
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.
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 [email protected] with any additional questions or comments.
