Add examples and getting started instructions

README.md

@@ -2,6 +2,36 @@
 
 The [Azure App Configuration](https://docs.microsoft.com/en-us/azure/azure-app-configuration/overview) provider for JavaScript enables developers to configure their applications using centralized configuration located in Azure App Configuration. 
 
+## Getting started
+
+### Prerequisites
+
+- An [Azure Subscription](https://azure.microsoft.com)
+- An [App Configuration](https://docs.microsoft.com/azure/azure-app-configuration/) resource
+
+### Install the package
+
+```bash
+npm install @azure/app-configuration-provider
+```
+
+### Use the API
+
+```js
+import { load } from "@azure/app-configuration-provider";
+
+// Load settings from App Configuration as a readonly Map.
+const settings = await load("<app-configuration-connection-string>");
+
+// Consume the settings by calling `get(key)`, e.g.
+const value = settings.get("<key-of-a-config>");
+```
+
+
+## Examples
+
+See code snippets under [examples/](./examples/) folder.
+
 ## Contributing
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a

SUPPORT.md

@@ -1,13 +1,3 @@
-# TODO: The maintainer of this repo has not yet edited this file
-
-**REPO OWNER**: Do you want Customer Service & Support (CSS) support for this product/project?
-
-- **No CSS support:** Fill out this template with information about how to file issues and get help.
-- **Yes CSS support:** Fill out an intake form at [aka.ms/onboardsupport](https://aka.ms/onboardsupport). CSS will work with/help you to determine next steps.
-- **Not sure?** Fill out an intake as though the answer were "Yes". CSS will help you decide.
-
-*Then remove this first heading from this SUPPORT.MD file before publishing your repo.*
-
 # Support
 
 ## How to file issues and get help  
@@ -16,10 +6,8 @@ This project uses GitHub Issues to track bugs and feature requests. Please searc
 issues before filing new issues to avoid duplicates.  For new issues, file your bug or 
 feature request as a new Issue.
 
-For help and questions about using this project, please **REPO MAINTAINER: INSERT INSTRUCTIONS HERE 
-FOR HOW TO ENGAGE REPO OWNERS OR COMMUNITY FOR HELP. COULD BE A STACK OVERFLOW TAG OR OTHER
-CHANNEL. WHERE WILL YOU HELP PEOPLE?**.
+For help and questions about using this project, please ask a question in Stack Overflow with [azure-app-configuration](https://stackoverflow.com/questions/tagged/azure-app-configuration) tag.
 
 ## Microsoft Support Policy  
 
-Support for this **PROJECT or PRODUCT** is limited to the resources listed above.
+Support for this project is limited to the resources listed above.

examples/.env.template

@@ -0,0 +1,17 @@
+# You can defined environment variables in .env file and load them with 'dotenv' package.
+# This is a template of related environment variables in examples.
+# Please rename this file to .env to make it working
+
+APPCONFIG_CONNECTION_STRING=<app-configuration-connection-string>
+
+# Used to specify endpoint when you are using role-based authentication instead of connection string.
+# Should be https://<resource-name>.azconfig.io
+APPCONFIG_ENDPOINT=<app-configuration-endpoint>
+
+# Used to authenticate using Microsoft Entra ID (Azure AD) as a service principal for role-based authentication.
+#
+# See the documentation for `EnvironmentCredential` at the following link:
+# https://docs.microsoft.com/javascript/api/@azure/identity/environmentcredential
+AZURE_TENANT_ID=<AD tenant id or name>
+AZURE_CLIENT_ID=<ID of the user/service principal to authenticate as>
+AZURE_CLIENT_SECRET=<client secret used to authenticate to Azure AD>

examples/README.md

@@ -0,0 +1,40 @@
+# Examples for Azure App Configuration JavaScript Provider
+
+These examples show how to use the JavaScript Provider for Azure App Configuration in some common scenarios.
+
+## Prerequisites
+
+The sample programs are compatible with [LTS versions of Node.js](https://github.com/nodejs/release#release-schedule).
+
+You need [an Azure subscription][freesub] and the following Azure resources to run these sample programs:
+
+- [Azure App Configuration account][createinstance_azureappconfigurationaccount]
+
+Samples retrieve credentials to access the service endpoint from environment variables. Alternatively, edit the source code to include the appropriate credentials. See each individual sample for details on which environment variables/credentials it requires to function.
+
+## Setup
+
+To run the samples using the published version of the package:
+
+1. Install the dependencies using `npm`:
+
+```bash
+npm install
+```
+
+2. Edit the file `.env.template`, adding the correct credentials to access the Azure service and run the samples. Then rename the file from `.env.template` to just `.env`. The sample programs will read this file automatically.
+
+3. Run whichever samples you like (note that some samples may require additional setup, see the table above):
+
+```bash
+node helloworld.mjs
+```
+
+Alternatively, run a single sample with the correct environment variables set (setting up the `.env` file is not required if you do this), for example (cross-platform):
+
+```bash
+npx cross-env APPCONFIG_CONNECTION_STRING="<appconfig connection string>" node helloworld.mjs
+```
+
+[freesub]: https://azure.microsoft.com/free/
+[createinstance_azureappconfigurationaccount]: https://docs.microsoft.com/azure/azure-app-configuration/quickstart-aspnet-core-app?tabs=core5x#create-an-app-configuration-store

examples/helloworld.mjs

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import * as dotenv from "dotenv";
+dotenv.config()
+
+/**
+ * This example retrives all settings starting with "app.settings.".
+ * Value of config "app.settings.message" will be printed.
+ *
+ * Below environment variables are required for this example:
+ * - APPCONFIG_CONNECTION_STRING
+ */
+
+import { load } from "@azure/app-configuration-provider";
+const connectionString = process.env.APPCONFIG_CONNECTION_STRING;
+const settings = await load(connectionString, {
+    selectors: [{
+        keyFilter: "app.settings.*"
+    }],
+    trimKeyPrefixes: ["app.settings."]
+});
+const message = settings.get("message");
+
+console.log(`Message from Azure App Configuration: ${message}`);

examples/helloworld_aad.mjs

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import * as dotenv from "dotenv";
+dotenv.config()
+
+/**
+ * This example retrives all settings starting with "app.settings.".
+ * Value of config "app.settings.message" will be printed.
+ *
+ * Below environment variables are required for this example:
+ * - APPCONFIG_ENDPOINT
+ * - AZURE_TENANT_ID
+ * - AZURE_CLIENT_ID
+ * - AZURE_CLIENT_SECRET
+ */
+
+import { load } from "@azure/app-configuration-provider";
+import { getDefaultAzureCredential } from "@azure/identity";
+const endpoint = process.env.APPCONFIG_ENDPOINT;
+const credential = getDefaultAzureCredential();
+const settings = await load(endpoint, credential, {
+    selectors: [{
+        keyFilter: "app.settings.*"
+    }],
+    trimKeyPrefixes: ["app.settings."]
+});
+const message = settings.get("message");
+
+console.log(`Message from Azure App Configuration: ${message}`);

examples/package.json

@@ -0,0 +1,7 @@
+{
+  "dependencies": {
+    "@azure/app-configuration-provider": "latest",
+    "@azure/identity": "^3.3.0",
+    "dotenv": "^16.3.1"
+  }
+}

examples/secretReference.mjs

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import * as dotenv from "dotenv";
+dotenv.config()
+
+/**
+ * This example retrives all settings and resolve secret value from keyvault.
+ * Before you run it, please add a sample keyvault secret reference "app.secret".
+ * Value of secret "app.secret" will be printed.
+ *
+ * Below environment variables are required for this example:
+ * - APPCONFIG_CONNECTION_STRING
+ * - APPCONFIG_ENDPOINT
+ * - AZURE_TENANT_ID
+ * - AZURE_CLIENT_ID
+ * - AZURE_CLIENT_SECRET
+ */
+
+import { load } from "@azure/app-configuration-provider";
+import { getDefaultAzureCredential } from "@azure/identity";
+const connectionString = process.env.APPCONFIG_CONNECTION_STRING;
+const settings = await load(connectionString, {
+    keyVaultOptions: {
+        credential: getDefaultAzureCredential()
+    }
+});
+const secretKey = "app.secret";
+const value = settings.get(secretKey);
+
+console.log(`Get the secret from keyvault key: ${secretKey}, value: ${value}`);