Package version:
Azure App Configuration is a managed service that helps developers centralize their application and feature settings simply and securely.
For applications that only need to read configuration values, we suggest using the @azure/app-configuration-provider library instead.
Use @azure/app-configuration (this library) to:
Key links:
npm install @azure/app-configuration
See our support policy for more details.
You can use the Azure Portal or the Azure CLI to create an Azure App Configuration resource.
Example (Azure CLI):
az appconfig create --name <app-configuration-resource-name> --resource-group <resource-group-name> --location eastus
AppConfigurationClient can authenticate using a service principal or using a connection string.
Authentication via service principal is done by:
@azure/identity package.Using DefaultAzureCredential
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";
// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);
More information about @azure/identity can be found here
To authenticate with a resource in a Sovereign Cloud, you will need to set the audience in the AppConfigurationClient constructor options.
import { AppConfigurationClient } from "@azure/app-configuration";
import { DefaultAzureCredential } from "@azure/identity";
// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.azure.cn";
// Create an AppConfigurationClient that will authenticate through AAD in the China cloud
const client = new AppConfigurationClient(
endpoint,
new DefaultAzureCredential(),
{
audience: KnownAppConfigurationAudience.AzureChina
}
);
Note: When audience property is not defined, the SDK will default to Azure Public Cloud.
To get the Primary connection string for an App Configuration resource you can use this Azure CLI command:
az appconfig credential list -g <resource-group-name> -n <app-configuration-resource-name> --query "([?name=='Primary'].connectionString)[0]"
And in code you can now create your App Configuration client with the connection string you got from the Azure CLI:
import { AppConfigurationClient } from "@azure/app-configuration";
const connectionString = "Endpoint=https://example.azconfig.io;XXX=YYYY;YYY=ZZZZ";
const client = new AppConfigurationClient(connectionString);
The AppConfigurationClient has some terminology changes from App Configuration in the portal.
ConfigurationSetting objectsisReadOnly field, which you can toggle using setReadOnly.ConfigurationSnapshot objects.The client follows a simple design methodology - ConfigurationSetting can be passed into any method that takes a ConfigurationSettingParam or ConfigurationSettingId.
This means this pattern works:
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";
// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);
const setting = await client.getConfigurationSetting({
key: "hello",
});
setting.value = "new value!";
await client.setConfigurationSetting(setting);
// fields unrelated to just identifying the setting are simply
// ignored (for instance, the `value` field)
await client.setReadOnly(setting, true);
// delete just needs to identify the setting so other fields are
// just ignored
await client.deleteConfigurationSetting(setting);
or, for example, re-getting a setting:
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";
// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);
let setting = await client.getConfigurationSetting({
key: "hello",
});
// re-get the setting
setting = await client.getConfigurationSetting(setting);
The 2022-11-01-preview API version supports configuration snapshots: immutable, point-in-time copies of a configuration store. Snapshots can be created with filters that determine which key-value pairs are contained within the snapshot, creating an immutable, composed view of the configuration store. 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. For example, this feature can be used to create "release configuration snapshots" within an App Configuration. See the create and get a snapshot section in the example below.
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";
// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);
await client.setConfigurationSetting({
key: "testkey",
value: "testvalue",
// Labels allow you to create variants of a key tailored
// for specific use-cases like supporting multiple environments.
// https://learn.microsoft.com/azure/azure-app-configuration/concept-key-value#label-keys
label: "optional-label",
});
const retrievedSetting = await client.getConfigurationSetting({
key: "testkey",
label: "optional-label",
});
console.log("Retrieved value:", retrievedSetting.value);
beginCreateSnapshot gives you the poller to poll for the snapshot creation.
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";
// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);
const key = "testkey";
const value = "testvalue";
const label = "optional-label";
await client.addConfigurationSetting({
key,
value,
label,
});
const poller = await client.beginCreateSnapshot({
name: "testsnapshot",
retentionPeriod: 2592000,
filters: [{ keyFilter: key, labelFilter: label }],
});
const snapshot = await poller.pollUntilDone();
You can also use beginCreateSnapshotAndWait to have the result of the creation directly after the polling is done.
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";
// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);
const key = "testkey";
const value = "testvalue";
const label = "optional-label";
const snapshot = await client.beginCreateSnapshotAndWait({
name: "testsnapshot",
retentionPeriod: 2592000,
filters: [{ keyFilter: key, labelFilter: label }],
});
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";
// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);
const retrievedSnapshot = await client.getSnapshot("testsnapshot");
console.log("Retrieved snapshot:", retrievedSnapshot);
ConfigurationSetting in the snapshotimport { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";
// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);
const retrievedSnapshotSettings = await client.listConfigurationSettingsForSnapshot("testsnapshot");
for await (const setting of retrievedSnapshotSettings) {
console.log(`Found key: ${setting.key}, label: ${setting.label}`);
}
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";
// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);
const snapshots = await client.listSnapshots();
for await (const snapshot of snapshots) {
console.log(`Found snapshot: ${snapshot.name}`);
}
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";
// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);
// Snapshot is in ready status
const archivedSnapshot = await client.archiveSnapshot("testsnapshot");
console.log("Snapshot updated status is:", archivedSnapshot.status);
// Snapshot is in archive status
const recoverSnapshot = await client.recoverSnapshot("testsnapshot");
console.log("Snapshot updated status is:", recoverSnapshot.status);
Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the AZURE_LOG_LEVEL environment variable to info. Alternatively, logging can be enabled at runtime by calling setLogLevel in the @azure/logger:
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
For more detailed instructions on how to enable logs, you can look at the @azure/logger package docs.
React Native does not support some JavaScript API used by this SDK library so you need to provide polyfills for them. Please see our React Native sample with Expo for more details.
The following samples show you the various ways you can interact with App Configuration:
helloworld.ts - Get, set, and delete configuration values.helloworldWithLabels.ts - Use labels to add additional dimensions to your settings for scenarios like beta vs production.optimisticConcurrencyViaEtag.ts - Set values using etags to prevent accidental overwrites.setReadOnlySample.ts - Marking settings as read-only to prevent modification.getSettingOnlyIfChanged.ts - Get a setting only if it changed from the last time you got it.listRevisions.ts - List the revisions of a key, allowing you to see previous values and when they were set.secretReference.ts - SecretReference represents a configuration setting that references as KeyVault secret.snapshot.ts - Create, list configuration settings, and archive snapshots.featureFlag.ts - Feature flags are settings that follow specific JSON schema for the value.More in-depth examples can be found in the samples folder on GitHub.
If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.
This module's tests are a mixture of live and unit tests, which require you to have an Azure App Configuration instance. To execute the tests you'll need to run:
rush updaterush build -t @azure/app-configurationsdk\appconfiguration\app-configuration folder:
APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instancecd sdk\appconfiguration\app-configurationnpm run test.View our tests folder for more details.