Merge pull request #299001 from zhiyuanliang-ms/zhiyuanliang/update-js-doc

Azure App Configuration - Update JS provider reference doc

Author: JillGrant615

articles/azure-app-configuration/configuration-provider-overview.md

@@ -50,7 +50,7 @@ Entra ID Authentication | GA | GA | GA | GA | [GA](./reference-javascript-provid
 Dynamic Refresh (Poll Mode) | GA | GA | GA | GA | GA
 Dynamic Refresh (Push Mode) | GA | GA | N/A | N/A | N/A
 Dynamic Refresh (Collection Monitoring) | WIP | WIP | GA | WIP | [GA](./reference-javascript-provider.md#configuration-refresh)
-JSON Content Type Handling | GA | GA | GA | GA | GA
+JSON Content Type Handling | GA | GA | GA | GA | [GA](./reference-javascript-provider.md#json-content-type-handling)
 Configuration Setting Mapping | GA | N/A | N/A | N/A | N/A
 Key Vault References | GA | GA | GA | GA | [GA](./reference-javascript-provider.md#key-vault-reference)
 Key Vault Secret Refresh | GA | WIP | GA | WIP | WIP

articles/azure-app-configuration/howto-feature-filters-javascript.md

@@ -83,4 +83,4 @@ To learn more about the built-in feature filters, continue to the following docu
 For the full feature rundown of the JavaScript feature management library, continue to the following document.
 
 > [!div class="nextstepaction"]
-> [.NET Feature Management](./feature-management-javascript-reference.md)
+> [JavaScript Feature Management](./feature-management-javascript-reference.md)

articles/azure-app-configuration/howto-timewindow-filter-javascript.md

@@ -79,4 +79,4 @@ To learn more about the feature filters, continue to the following documents.
 For the full feature rundown of the JavaScript feature management library, continue to the following document.
 
 > [!div class="nextstepaction"]
-> [.NET Feature Management](./feature-management-javascript-reference.md)
+> [JavaScript Feature Management](./feature-management-javascript-reference.md)

articles/azure-app-configuration/quickstart-feature-flag-javascript.md

@@ -198,7 +198,7 @@ Add a feature flag called *Beta* to the App Configuration store and leave **Labe
 
 ## Next steps
 
-For the full feature rundown of the JavaScript.NET feature management library, continue to the following document.
+For the full feature rundown of the JavaScript feature management library, continue to the following document.
 
 > [!div class="nextstepaction"]
 > [JavaScript Feature Management](./feature-management-javascript-reference.md)

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

@@ -35,8 +35,8 @@ const credential = new DefaultAzureCredential(); // For more information, see ht
 
 async function run() {
     // Connect to Azure App Configuration using a token credential and load all key-values with no label.
-    const settings = await load(endpoint, credential);
-    console.log('settings.get("message"):', settings.get("message"));
+    const appConfig = await load(endpoint, credential);
+    console.log('appConfig.get("message"):', appConfig.get("message"));
 }
 
 run();
@@ -50,8 +50,8 @@ const connectionString = process.env.AZURE_APPCONFIG_CONNECTION_STRING;
 
 async function run() {
     // Connect to Azure App Configuration using a connection string and load all key-values with no label.
-    const settings = await load(connectionString);
-    console.log('settings.get("message"):', settings.get("message"));
+    const appConfig = await load(connectionString);
+    console.log('appConfig.get("message"):', appConfig.get("message"));
 }
 
 run();
@@ -85,8 +85,8 @@ The `AzureAppConfiguration` type extends the following interfaces:
     The `IGettable` interface provides `get` method to retrieve the value of a key-value from the Map-styled data structure.
 
     ```typescript
-    const settings = await load(endpoint, credential);
-    const fontSize = settings.get("app:font:size"); // value of the key "app:font:size" from the App Configuration store
+    const appConfig = await load(endpoint, credential);
+    const fontSize = appConfig.get("app:font:size"); // value of the key "app:font:size" from the App Configuration store
     ```
 
 - `ReadonlyMap`
@@ -112,20 +112,40 @@ The `AzureAppConfiguration` type extends the following interfaces:
    In JavaScript, objects or maps are commonly used as the primary data structures to represent configurations. The JavaScript configuration provider library supports both of the configuration approaches, providing developers with the flexibility to choose the option that best fits their needs.
 
     ```typescript
-    const settings = await load(endpoint, credential);
-    const settingsObj = settings.constructConfigurationObject({separator: ":"});
-    const fontSize1 = settings.get("app:font:size"); // map-style configuration representation
+    const appConfig = await load(endpoint, credential);
+    const settingsObj = appConfig.constructConfigurationObject({separator: ":"});
+    const fontSize1 = appConfig.get("app:font:size"); // map-style configuration representation
     const fontSize2 = settingsObj.app.font.size; // object-style configuration representation
     ```
 
+### JSON Content Type Handling
+
+You can [create JSON key-values](./howto-leverage-json-content-type.md#create-json-key-values-in-app-configuration) in App Configuration. When loading key-values from Azure App Configuration, the configuration provider will automatically convert the key-values of valid JSON content type (e.g. application/json) into object.
+
+```json
+{
+    "key": "font",
+    "label": null,
+    "value": "{\r\n\t\"size\": 12,\r\n\t\"color\": \"red\"\r\n}",
+    "content_type": "application/json"
+}
+```
+
+The above key-value will be loaded as `{ size: 12, color: "red" }`.
+
+```typescript
+const appConfig = await load(endpoint, credential);
+const { size, color } = appConfig.get("font");
+```
+
 ### Load specific key-values using selectors
 
 By default, the `load` method will load all configurations with no label from the configuration store. You can configure the behavior of the `load` method through the optional parameter of [`AzureAppConfigurationOptions`](https://github.com/Azure/AppConfiguration-JavaScriptProvider/blob/main/src/AzureAppConfigurationOptions.ts) type.
 
 To refine or expand the configurations loaded from the App Configuration store, you can specify the key or label selectors under the `AzureAppConfigurationOptions.selectors` property.
 
 ```typescript
-const settings = await load(endpoint, credential, {
+const appConfig = await load(endpoint, credential, {
     selectors: [
         { // load the subset of keys starting with "app1." prefix and "test" label
             keyFilter: "app1.*",
@@ -146,62 +166,20 @@ const settings = await load(endpoint, credential, {
 You can trim the prefix off of keys by providing a list of trimmed key prefixes to the `AzureAppConfigurationOptions.trimKeyPrefixes` property.
 
 ```typescript
-const settings = await load(endpoint, credential, {
+const appConfig = await load(endpoint, credential, {
     selectors: [{
         keyFilter: "app.*"
     }],
     trimKeyPrefixes: ["app."]
 });
 ```
 
-## Key Vault reference
-
-Azure App Configuration supports referencing secrets stored in Azure Key Vault. In App Configuration, you can create keys that map to secrets stored in Key Vault. The secrets are securely stored in Key Vault, but can be accessed like any other configuration once loaded.
-
-The configuration provider library retrieves Key Vault references, just as it does for any other keys stored in App Configuration. Because the client recognizes the keys as Key Vault references, they have a unique content-type, and the client will connect to Key Vault to retrieve their values for your application. You need to configure `AzureAppConfigurationOptions.KeyVaultOptions` property with the proper credential to allow the configuration provider to connect to Azure Key Vault.
-
-```typescript
-const credential = new DefaultAzureCredential();
-const settings = await load(endpoint, credential, {
-    keyVaultOptions: {
-        credential: credential
-    }
-});
-```
-
-You can also provide `SecretClient` instance directly to `KeyVaultOptions`. In this way, you can customize the options while creating `SecretClient`.
-
-```typescript
-const { SecretClient } = require("@azure/keyvault-secrets");
-
-const credential = new DefaultAzureCredential();
-const secretClient = new SecretClient(keyVaultUrl, credential, {
-    serviceVersion: "7.0",
-});
-const settings = await load(endpoint, credential, {
-    keyVaultOptions: {
-        secretClients: [ secretClient ]
-    }
-});
-```
-
-You can also set `secretResolver` property to locally resolve secrets that don’t have a Key Vault associated with them.
-
-```typescript
-const resolveSecret = (url) => "From Secret Resolver";
-const settings = await load(endpoint, credential, {
-    keyVaultOptions: {
-        secretResolver: resolveSecret
-    }
-});
-```
-
 ## Configuration refresh
 
 Dynamic refresh for the configurations lets you pull their latest values from the App Configuration store without having to restart the application. You can set `AzureAppConfigurationOptions.refreshOptions` to enable the refresh and configure refresh options. The loaded configuration will be updated when any change of selected key-values is detected on the server. By default, a refresh interval of 30 seconds is used, but you can override it with the `refreshIntervalInMs` property.
 
 ```typescript
-const settings = await load(endpoint, credential, {
+const appConfig = await load(endpoint, credential, {
     refreshOptions: {
         enabled: true,
         refreshIntervalInMs: 15_000
@@ -213,7 +191,7 @@ Setting up `refreshOptions` alone won't automatically refresh the configuration.
 
 ```typescript
 // this call is not blocking, the configuration will be updated asynchronously
-settings.refresh();
+appConfig.refresh();
 ```
 
 This design prevents unnecessary requests to App Configuration when your application is idle. You should include the `refresh` call where your application activity occurs. This is known as **activity-driven configuration refresh**. For example, you can call `refresh` when processing an incoming request or inside an iteration where you perform a complex task.
@@ -222,7 +200,7 @@ This design prevents unnecessary requests to App Configuration when your applica
 const server = express();
 // Use an express middleware to refresh configuration whenever a request comes in
 server.use((req, res, next) => {
-    settings.refresh();
+    appConfig.refresh();
     next();
 })
 ```
@@ -234,16 +212,16 @@ Even if the refresh call fails for any reason, your application will continue to
 The `onRefresh` method lets you custom callback functions that will be invoked each time the local configuration is successfully updated with changes from the Azure App Configuration store. It returns a Disposable object, which you can use to remove the registered callback
 
 ```typescript
-const settings = await load(endpoint, credential, {
+const appConfig = await load(endpoint, credential, {
     refreshOptions: {
         enabled: true
     }
 });
-const disposer = settings.onRefresh(() => {
+const disposer = appConfig.onRefresh(() => {
     console.log("Config refreshed.");
 });
 
-settings.refresh();
+appConfig.refresh();
 // Once the refresh is successful, the callback function you registered will be executed.
 // In this example, the message "Config refreshed" will be printed.
 
@@ -255,7 +233,7 @@ disposer.dispose();
 A sentinel key is a key that you update after you complete the change of all other keys. The configuration provider will monitor the sentinel key instead of all selected key-values. When a change is detected, your app refreshes all configuration values.
 
 ```typescript
-const settings = await load(endpoint, credential, {
+const appConfig = await load(endpoint, credential, {
     refreshOptions: {
         enabled: true,
         watchedSettings: [
@@ -272,12 +250,12 @@ For more information about refresh configuration, go to [Use dynamic configurati
 You can [create feature flags](./manage-feature-flags.md#create-a-feature-flag) in Azure App Configuration. By default, the feature flags will not be loaded by configuration provider. You can enable loading and refreshing feature flags through `AzureAppConfigurationOptions.featureFlagOptions` property when calling the `load` method.
 
 ```typescript
-const settings = await load(endpoint, credential, {
+const appConfig = await load(endpoint, credential, {
     featureFlagOptions: {
-        enabled: true,
+        enabled: true, // enable loading feature flags
         selectors: [ { keyFilter: "*", labelFilter: "Prod" } ],
         refresh: {
-            enabled: true, // the refresh for feature flags need to be enbaled in addition to key-values
+            enabled: true, // enable refreshing feature flags
             refreshIntervalInMs: 10_000
         }
     }
@@ -287,12 +265,96 @@ const settings = await load(endpoint, credential, {
 > [!NOTE]
 > If `featureFlagOptions` is enabled and no selector is specified, the configuration provider will load all feature flags with no label from the App Configuration store.
 
+> [!IMPORTANT]
+> To effectively consume and manage feature flags loaded from Azure App Configuration, install and use the [`@microsoft/feature-management`](https://www.npmjs.com/package/@microsoft/feature-management) package. This library provides a structured way to control feature behavior in your application.
+
 ### Feature management
 
-Feature management library provides a way to develop and expose application functionality based on feature flags. The feature management library is designed to work in conjunction with the configuration provider library. The configuration provider will load all selected feature flags into the configuration under the `feature_flags` list of the `feature_management` section. The feature management library will consume and manage the loaded feature flags for your application. 
+Feature management library provides a way to develop and expose application functionality based on feature flags. The feature management library is designed to work in conjunction with the configuration provider library. The configuration provider will load all selected feature flags into the configuration under the `feature_flags` list of the `feature_management` section. The feature management library will consume and manage the loaded feature flags for your application.
+
+The following example demonstrates how to integrate the `@microsoft/feature-management` library with the configuration provider to dynamically control API accessibility in an Express application based on the status of the `Beta` feature flag.
+
+```typescript
+// Load feature flags from Azure App Configuration
+import { load } from "@azure/app-configuration-provider";
+const appConfig = await load(endpoint, credential, {
+    featureFlagOptions: {
+        enabled: true, // enable loading feature flags
+        refresh: {
+            enabled: true // enable refreshing feature flags
+        }
+    }
+});
+
+import { ConfigurationMapFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
+// Create a feature flag provider which uses the configuration provider as feature flag source
+const ffProvider = new ConfigurationMapFeatureFlagProvider(appConfig);
+// Create a feature manager which will evaluate the feature flag
+const fm = new FeatureManager(ffProvider);
+
+import express from "express";
+const server = express();
+
+// Use a middleware to achieve request-driven configuration refresh
+server.use((req, res, next) => {
+    // this call is not blocking, the configuration will be updated asynchronously
+    appConfig.refresh();
+    next();
+});
+
+server.get("/Beta", async (req, res) => {
+    if (await featureManager.isEnabled("Beta")) {
+        res.send("Welcome to the Beta page!");
+    } else {
+        res.status(404).send("Page not found");
+    }
+});
+```
 
 For more information about how to use the JavaScript feature management library, go to the [feature flag quickstart](./quickstart-feature-flag-javascript.md).
 
+## Key Vault reference
+
+Azure App Configuration supports referencing secrets stored in Azure Key Vault. In App Configuration, you can create keys that map to secrets stored in Key Vault. The secrets are securely stored in Key Vault, but can be accessed like any other configuration once loaded.
+
+The configuration provider library retrieves Key Vault references, just as it does for any other keys stored in App Configuration. Because the client recognizes the keys as Key Vault references, they have a unique content-type, and the client will connect to Key Vault to retrieve their values for your application. You need to configure `AzureAppConfigurationOptions.KeyVaultOptions` property with the proper credential to allow the configuration provider to connect to Azure Key Vault.
+
+```typescript
+const credential = new DefaultAzureCredential();
+const appConfig = await load(endpoint, credential, {
+    keyVaultOptions: {
+        credential: credential
+    }
+});
+```
+
+You can also provide `SecretClient` instance directly to `KeyVaultOptions`. In this way, you can customize the options while creating `SecretClient`.
+
+```typescript
+import { SecretClient } from "@azure/keyvault-secrets";
+
+const credential = new DefaultAzureCredential();
+const secretClient = new SecretClient(keyVaultUrl, credential, {
+    serviceVersion: "7.0",
+});
+const appConfig = await load(endpoint, credential, {
+    keyVaultOptions: {
+        secretClients: [ secretClient ]
+    }
+});
+```
+
+You can also set `secretResolver` property to locally resolve secrets that don’t have a Key Vault associated with them.
+
+```typescript
+const resolveSecret = (url) => "From Secret Resolver";
+const appConfig = await load(endpoint, credential, {
+    keyVaultOptions: {
+        secretResolver: resolveSecret
+    }
+});
+```
+
 ## Geo-replication
 
 For information about using geo-replication, go to [Enable geo-replication](./howto-geo-replication.md).
@@ -303,3 +365,8 @@ To learn how to use the JavaScript configuration provider, continue to the follo
 
 > [!div class="nextstepaction"]
 > [Use dynamic configuration in JavaScript](./enable-dynamic-configuration-javascript.md)
+
+To learn how to use the JavaScript feature management library, continue to the following documentation.
+
+> [!div class="nextstepaction"]
+> [JavaScript Feature Management](./feature-management-javascript-reference.md)