@microsoft/applicationinsights-core-js 2.8.0-beta.2203-02 → 2.8.0-beta.2203-05

package/src/JavaScriptSDK/EventHelpers.ts

@@ -49,12 +49,12 @@ function _normalizeNamespace(name: string) {
     return name;
 }
 
-function _getEvtNamespace(eventName: string, namespaces: string | string[]): IEventDetails {
-    if (namespaces) {
+function _getEvtNamespace(eventName: string, evtNamespace?: string | string[]): IEventDetails {
+    if (evtNamespace) {
         let theNamespace: string = "";
-        if (isArray(namespaces)) {
+        if (isArray(evtNamespace)) {
             theNamespace = "";
-            arrForEach(namespaces, (name) => {
+            arrForEach(evtNamespace, (name) => {
                 name = _normalizeNamespace(name);
                 if (name) {
                     if (name[0] !== ".") {
@@ -65,7 +65,7 @@ function _getEvtNamespace(eventName: string, namespaces: string | string[]): IEv
                 }
             });
         } else {
-            theNamespace = _normalizeNamespace(namespaces);
+            theNamespace = _normalizeNamespace(evtNamespace);
         }
 
         if (theNamespace) {
@@ -96,18 +96,24 @@ export interface _IRegisteredEvents {
  * Get all of the registered events on the target object, this is primarily used for testing cleanup but may also be used by
  * applications to remove their own events
  * @param target - The EventTarget that has registered events
- * @param evtName - [Optional] The name of the event to return the registered handlers and full name (with namespaces)
+ * @param eventName - [Optional] The name of the event to return the registered handlers and full name (with namespaces)
+ * @param evtNamespace - [Optional] Additional namespace(s) to append to the event listeners so they can be uniquely identified and removed based on this namespace,
+ * if the eventName also includes a namespace the namespace(s) are merged into a single namespace
  */
-export function __getRegisteredEvents(target: any, evtName?: string): _IRegisteredEvents[] {
+export function __getRegisteredEvents(target: any, eventName?: string, evtNamespace?: string | string[]): _IRegisteredEvents[] {
     let theEvents: _IRegisteredEvents[] = [];
     let eventCache = elmNodeData.get<IAiEvents>(target, strEvents, {}, false);
+    let evtName = _getEvtNamespace(eventName, evtNamespace);
+
     objForEachKey(eventCache, (evtType, registeredEvents) => {
         arrForEach(registeredEvents, (value) => {
-            if (!evtName || evtName === value.evtName.type) {
-                theEvents.push({
-                    name: value.evtName.type + (value.evtName.ns ? "." + value.evtName.ns : ""),
-                    handler: value.handler
-                });
+            if (!evtName.type || evtName.type === value.evtName.type) {
+                if (!evtName.ns || evtName.ns === evtName.ns) {
+                    theEvents.push({
+                        name: value.evtName.type + (value.evtName.ns ? "." + value.evtName.ns : ""),
+                        handler: value.handler
+                    });
+                }
             }
         });
     });

package/src/JavaScriptSDK/HelperFuncs.ts

@@ -836,7 +836,7 @@ export function createEnumStyle<T>(values: T) {
         enumClass[field] = value;
         // Add Reverse lookup
         if (!isUndefined(enumClass[value])) {
-            throwError("Value: [" + value + "] already exists for " + field);
+            throwError("[" + value + "] exists for " + field);
         }
         enumClass[value] = field;
     });
@@ -871,7 +871,9 @@ export function optimizeObject<T>(theObject: T): T {
  * @param obj5 - object to merge.
  * @returns The extended first object.
  */
- export function objExtend<T1, T2, T3, T4, T5, T6>(obj?: boolean | T1, obj2?: T2, obj3?: T3, obj4?: T4, obj5?: T5, obj6?: T6): T1 & T2 & T3 & T4 & T5 & T6 {
+export function objExtend<T2, T3, T4, T5, T6>(deepExtend?: boolean, obj2?: T2, obj3?: T3, obj4?: T4, obj5?: T5, obj6?: T6): T2 & T3 & T4 & T5 & T6
+export function objExtend<T1, T2, T3, T4, T5, T6>(obj1?: T1, obj2?: T2, obj3?: T3, obj4?: T4, obj5?: T5, obj6?: T6): T1 & T2 & T3 & T4 & T5 & T6
+export function objExtend<T1, T2, T3, T4, T5, T6>(obj1?: T1 | any, obj2?: T2, obj3?: T3, obj4?: T4, obj5?: T5, obj6?: T6): T1 & T2 & T3 & T4 & T5 & T6 {
     // Variables
     let theArgs = arguments as any;
     let extended: T1 & T2 & T3 & T4 & T5 & T6 = theArgs[0] || {};

package/src/JavaScriptSDK/ProcessTelemetryContext.ts

@@ -6,16 +6,17 @@ import { IAppInsightsCore } from "../JavaScriptSDK.Interfaces/IAppInsightsCore";
 import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
 import { ITelemetryItem } from "../JavaScriptSDK.Interfaces/ITelemetryItem";
 import { IPlugin, ITelemetryPlugin } from "../JavaScriptSDK.Interfaces/ITelemetryPlugin";
-import { GetExtCfgMergeType, IBaseProcessingContext, IProcessTelemetryContext, IProcessTelemetryUnloadContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
+import { GetExtCfgMergeType, IBaseProcessingContext, IProcessTelemetryContext, IProcessTelemetryUnloadContext, IProcessTelemetryUpdateContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
 import { ITelemetryPluginChain } from "../JavaScriptSDK.Interfaces/ITelemetryPluginChain";
-import { safeGetLogger } from "./DiagnosticLogger";
+import { safeGetLogger, _throwInternal } from "./DiagnosticLogger";
 import { arrForEach, isArray, isFunction, isNullOrUndefined, isObject, isUndefined, objExtend, objForEachKey, objFreeze, objKeys, proxyFunctions } from "./HelperFuncs";
 import { doPerf } from "./PerfManager";
 import { eLoggingSeverity, _eInternalMessageId } from "../JavaScriptSDK.Enums/LoggingEnums";
 import { dumpObj } from "./EnvUtils";
-import { strCore, strDisabled, strEmpty, strIsInitialized, strTeardown } from "./InternalConstants";
+import { strCore, strDisabled, strEmpty, strIsInitialized, strTeardown, strUpdate } from "./InternalConstants";
 import { IDiagnosticLogger } from "../JavaScriptSDK.Interfaces/IDiagnosticLogger";
 import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
+import { ITelemetryUpdateState } from "../JavaScriptSDK.Interfaces/ITelemetryUpdateState";
 import { _getPluginState } from "./TelemetryHelpers";
 
 const strTelemetryPluginChain = "TelemetryPluginChain";
@@ -55,12 +56,25 @@ function _getNextProxyStart(proxy: ITelemetryPluginChain, config: IConfiguration
     return createTelemetryProxyChain([startAt], config, core);
 }
 
+/**
+ * @ignore
+ * @param telemetryChain
+ * @param config
+ * @param core
+ * @param startAt - Identifies the next plugin to execute, if null there is no "next" plugin and if undefined it should assume the start of the chain
+ * @returns
+ */
 function _createInternalContext<T extends IBaseProcessingContext>(telemetryChain: ITelemetryPluginChain, config: IConfiguration, core:IAppInsightsCore, startAt?: IPlugin): IInternalContext<T> {
     // We have a special case where we want to start execution from this specific plugin
     // or we simply reuse the existing telemetry plugin chain (normal execution case)
-    let _nextProxy: ITelemetryPluginChain = startAt ? _getNextProxyStart(telemetryChain, config, core, startAt) : telemetryChain;
+    let _nextProxy: ITelemetryPluginChain = null;  // By Default set as no next plugin
     let _onComplete: OnCompleteCallback[] = [];
 
+    if (startAt !== null) {
+        // There is no next element (null) vs not defined (undefined) so use the full chain
+        _nextProxy = startAt ? _getNextProxyStart(telemetryChain, config, core, startAt) : telemetryChain;
+    }
+
     let context: IInternalContext<T> = {
         _next: _moveNext,
         ctx: {
@@ -110,10 +124,11 @@ function _createInternalContext<T extends IBaseProcessingContext>(telemetryChain
                     try {
                         completeDetails.func.call(completeDetails.self, completeDetails.args);
                     } catch (e) {
-                        core.logger.throwInternal(
-                        eLoggingSeverity.WARNING,
-                        _eInternalMessageId.PluginException,
-                        "Unexpected Exception during onComplete - " + dumpObj(e));
+                        _throwInternal(
+                            core.logger,
+                            eLoggingSeverity.WARNING,
+                            _eInternalMessageId.PluginException,
+                            "Unexpected Exception during onComplete - " + dumpObj(e));
                     }
                 });
 
@@ -192,9 +207,9 @@ function _createInternalContext<T extends IBaseProcessingContext>(telemetryChain
  * @param plugins - The plugin instances that will be executed
  * @param config - The current config
  * @param core - The current core instance
+ * @param startAt - Identifies the next plugin to execute, if null there is no "next" plugin and if undefined it should assume the start of the chain
  */
 export function createProcessTelemetryContext(telemetryChain: ITelemetryPluginChain, config: IConfiguration, core:IAppInsightsCore, startAt?: IPlugin): IProcessTelemetryContext {
-
     let internalContext: IInternalContext<IProcessTelemetryContext> = _createInternalContext<IProcessTelemetryContext>(telemetryChain, config, core, startAt);
     let context = internalContext.ctx;
 
@@ -225,6 +240,7 @@ export function createProcessTelemetryContext(telemetryChain: ITelemetryPluginCh
  * @param plugins - The plugin instances that will be executed
  * @param config - The current config
  * @param core - The current core instance
+ * @param startAt - Identifies the next plugin to execute, if null there is no "next" plugin and if undefined it should assume the start of the chain
  */
 export function createProcessTelemetryUnloadContext(telemetryChain: ITelemetryPluginChain, config: IConfiguration, core:IAppInsightsCore, startAt?: IPlugin): IProcessTelemetryUnloadContext {
     let internalContext: IInternalContext<IProcessTelemetryUnloadContext> = _createInternalContext<IProcessTelemetryUnloadContext>(telemetryChain, config, core, startAt);
@@ -251,6 +267,38 @@ export function createProcessTelemetryUnloadContext(telemetryChain: ITelemetryPl
     return context;
 }
 
+/**
+ * Creates a new Telemetry Item context with the current config, core and plugin execution chain for updating the configuration
+ * @param plugins - The plugin instances that will be executed
+ * @param config - The current config
+ * @param core - The current core instance
+ * @param startAt - Identifies the next plugin to execute, if null there is no "next" plugin and if undefined it should assume the start of the chain
+ */
+ export function createProcessTelemetryUpdateContext(telemetryChain: ITelemetryPluginChain, config: IConfiguration, core:IAppInsightsCore, startAt?: IPlugin): IProcessTelemetryUpdateContext {
+    let internalContext: IInternalContext<IProcessTelemetryUpdateContext> = _createInternalContext<IProcessTelemetryUpdateContext>(telemetryChain, config, core, startAt);
+    let context = internalContext.ctx;
+
+    function _processNext(updateState: ITelemetryUpdateState) {
+        return context.iterate((plugin) => {
+            if (isFunction(plugin[strUpdate])) {
+                plugin[strUpdate](context, updateState);
+            }
+        });
+    }
+
+    function _createNew(plugins: IPlugin[] | ITelemetryPluginChain = null, startAt?: IPlugin) {
+        if (isArray(plugins)) {
+            plugins = createTelemetryProxyChain(plugins, config, core, startAt);
+        }
+
+        return createProcessTelemetryUpdateContext(plugins || context.getNext(), config, core, startAt);
+    }
+
+    context.processNext = _processNext;
+    context.createNew = _createNew;
+
+    return context;
+}
 
 /**
  * Creates an execution chain from the array of plugins
@@ -326,6 +374,7 @@ export function createTelemetryPluginProxy(plugin: ITelemetryPlugin, config: ICo
         },
         processTelemetry: _processTelemetry,
         unload: _unloadPlugin,
+        update: _updatePlugin,
         _id: chainId,
         _setNext: (nextPlugin: IInternalTelemetryPluginChain) => {
             nextProxy = nextPlugin;
@@ -391,7 +440,8 @@ export function createTelemetryPluginProxy(plugin: ITelemetryPlugin, config: ICo
 
                         // Either we have no next plugin or the current one did not attempt to call the next plugin
                         // Which means the current one is the root of the failure so log/report this failure
-                        itemCtx.diagLog().throwInternal(
+                        _throwInternal(
+                            itemCtx.diagLog(),
                             eLoggingSeverity.CRITICAL,
                             _eInternalMessageId.PluginException,
                             "Plugin [" + plugin.identifier + "] failed during " + name + " - " + dumpObj(error) + ", run flags: " + dumpObj(hasRunContext));
@@ -468,6 +518,33 @@ export function createTelemetryPluginProxy(plugin: ITelemetryPlugin, config: ICo
         }
     }
 
+    function _updatePlugin(updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState) {
+
+        function _callUpdate() {
+            // Setting default of hasRun as false so the proxyProcessFn() is called as teardown() doesn't have to exist or call unloadNext().
+            let hasRun = false;
+            if (plugin) {
+                let pluginState = _getPluginState(plugin);
+                let pluginCore = plugin[strCore] || pluginState.core;
+
+                // Only update the plugin if it was initialized by the current core (i.e. It's not a shared plugin)
+                if (plugin && (!pluginCore || pluginCore === updateCtx[strCore]()) && !pluginState[strTeardown]) {
+                    if (plugin[strUpdate] && plugin[strUpdate](updateCtx, updateState) === true) {
+                        // plugin told us that it was going to (or has) call unloadCtx.processNext()
+                        hasRun = true;
+                    }
+                }
+            }
+
+            return hasRun;
+        }
+        
+        if (!_processChain(updateCtx, _callUpdate, "update", () => {}, false)) {
+            // Only called if we hasRun was not true
+            updateCtx.processNext(updateState);
+        }
+    }
+
     return objFreeze(proxyChain);
 }
 

package/src/JavaScriptSDK/TelemetryInitializerPlugin.ts

@@ -7,6 +7,7 @@ import { IProcessTelemetryContext } from "../JavaScriptSDK.Interfaces/IProcessTe
 import { ITelemetryInitializerContainer, ITelemetryInitializerHandler, TelemetryInitializerFunction } from "../JavaScriptSDK.Interfaces/ITelemetryInitializers";
 import { ITelemetryItem } from "../JavaScriptSDK.Interfaces/ITelemetryItem";
 import { BaseTelemetryPlugin } from "./BaseTelemetryPlugin";
+import { _throwInternal } from "./DiagnosticLogger";
 import { dumpObj } from "./EnvUtils";
 import { arrForEach, getExceptionName } from "./HelperFuncs";
 import { strDoTeardown } from "./InternalConstants";
@@ -68,7 +69,8 @@ export class TelemetryInitializerPlugin extends BaseTelemetryPlugin implements I
                         } catch (e) {
                             // log error but dont stop executing rest of the telemetry initializers
                             // doNotSendItem = true;
-                            itemCtx.diagLog().throwInternal(
+                            _throwInternal(
+                                itemCtx.diagLog(),
                                 eLoggingSeverity.CRITICAL,
                                 _eInternalMessageId.TelemetryInitializerFailed,
                                 "One of telemetry initializers failed, telemetry item will not be sent: " + getExceptionName(e),

package/src/JavaScriptSDK/UnloadHandlerContainer.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { eLoggingSeverity, _eInternalMessageId } from "../JavaScriptSDK.Enums/LoggingEnums";
+import { IProcessTelemetryUnloadContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
+import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
+import { _throwInternal } from "./DiagnosticLogger";
+import { dumpObj } from "./EnvUtils";
+import { arrForEach } from "./HelperFuncs";
+
+export type UnloadHandler = (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+
+export interface IUnloadHandlerContainer {
+    add: (handler: UnloadHandler) => void;
+    run: (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void
+}
+
+export function createUnloadHandlerContainer() {
+    let handlers: UnloadHandler[] = [];
+
+    function _addHandler(handler: UnloadHandler) {
+        if (handler) {
+            handlers.push(handler);
+        }
+    }
+
+    function _runHandlers(unloadCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) {
+        arrForEach(handlers, (handler) => {
+            try {
+                handler(unloadCtx, unloadState);
+            } catch (e) {
+                _throwInternal(
+                    unloadCtx.diagLog(),
+                    eLoggingSeverity.WARNING,
+                    _eInternalMessageId.PluginException,
+                    "Unexpected error calling unload handler - " + dumpObj(e));
+            }
+        });
+        handlers = [];
+    }
+
+    return {
+        add: _addHandler,
+        run: _runHandlers
+    }
+}

package/src/JavaScriptSDK.Enums/SendRequestReason.ts

@@ -38,6 +38,11 @@ export const enum SendRequestReason {
      * The event(s) being sent as a retry
      */
     Retry = 5,
+
+    /**
+     * The SDK is unloading
+     */
+    SdkUnload = 6,
     
     /**
      * Maximum batch size would be exceeded

package/src/JavaScriptSDK.Enums/TelemetryUnloadReason.ts

@@ -13,15 +13,15 @@
     /**
      * Just this plugin is being removed
      */
-    //PluginUnload = 1,
+    PluginUnload = 1,
 
     /**
      * This instance of the plugin is being removed and replaced
      */
-    //PluginReplace = 2,
+    PluginReplace = 2,
 
     /**
      * The entire SDK is being unloaded
      */
-    //SdkUnload = 50
+    SdkUnload = 50
 }

package/src/JavaScriptSDK.Enums/TelemetryUpdateReason.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+/**
+ * The TelemetryUpdateReason enumeration contains a set of bit-wise values that specify the reason for update request.
+ */
+ export const enum TelemetryUpdateReason {
+    /**
+     * Unknown.
+     */
+    Unknown = 0,
+
+    /**
+     * The configuration has ben updated or changed
+     */
+    //ConfigurationChanged = 0x01,
+
+    /**
+     * One or more plugins have been added
+     */
+    PluginAdded = 0x10,
+
+    /**
+     * One or more plugins have been removed
+     */
+    PluginRemoved = 0x20,
+}

package/src/JavaScriptSDK.Interfaces/IAppInsightsCore.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT License.
 import { ITelemetryItem } from "./ITelemetryItem";
 import { IChannelControls } from "./IChannelControls";
-import { IPlugin } from "./ITelemetryPlugin";
+import { IPlugin, ITelemetryPlugin } from "./ITelemetryPlugin";
 import { IConfiguration } from "./IConfiguration";
 import { INotificationManager } from "./INotificationManager";
 import { INotificationListener } from "./INotificationListener";
@@ -11,6 +11,7 @@ import { IProcessTelemetryContext } from "./IProcessTelemetryContext";
 import { IPerfManagerProvider } from "./IPerfManager";
 import { ICookieMgr } from "./ICookieMgr";
 import { ITelemetryInitializerHandler, TelemetryInitializerFunction } from "./ITelemetryInitializers";
+import { UnloadHandler } from "../applicationinsights-core-js";
 
 export interface ILoadedPlugin<T extends IPlugin> {
     plugin: T;
@@ -29,6 +30,8 @@ export interface ILoadedPlugin<T extends IPlugin> {
      * (unless it's also been re-initialized)
      */
     setEnabled: (isEnabled: boolean) => void;
+
+    remove: (isAsync?: boolean, removeCb?: (removed?: boolean) => void) => void;
 }
 
 export interface IAppInsightsCore extends IPerfManagerProvider {
@@ -106,14 +109,38 @@ export interface IAppInsightsCore extends IPerfManagerProvider {
      */
     getProcessTelContext() : IProcessTelemetryContext;
 
+    /**
+     * Unload and Tear down the SDK and any initialized plugins, after calling this the SDK will be considered
+     * to be un-initialized and non-operational, re-initializing the SDK should only be attempted if the previous
+     * unload call return `true` stating that all plugins reported that they also unloaded, the recommended
+     * approach is to create a new instance and initialize that instance.
+     * This is due to possible unexpected side effects caused by plugins not supporting unload / teardown, unable
+     * to successfully remove any global references or they may just be completing the unload process asynchronously.
+     */
+    unload(isAsync?: boolean, unloadComplete?: () => void): void;
+
     /**
      * Find and return the (first) plugin with the specified identifier if present
      * @param pluginIdentifier
      */
     getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
   
+    /**
+     * Add a new plugin to the installation
+     * @param plugin - The new plugin to add
+     * @param replaceExisting - should any existing plugin be replaced
+     * @param doAsync - Should the add be performed asynchronously
+     */
+    addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void;
+  
     /**
      * Returns the unique event namespace that should be used when registering events
      */
     evtNamespace(): string;
-}
+  
+    /**
+     * Add a handler that will be called when the SDK is being unloaded
+     * @param handler - the handler
+     */
+    addUnloadCb(handler: UnloadHandler): void;
+ }

package/src/JavaScriptSDK.Interfaces/IInstrumentHooks.ts

@@ -12,6 +12,11 @@ export type InstrumentorHooksCallback = (funcArgs:IInstrumentCallDetails, ...org
  * You must always supply the error callback
  */
 export interface IInstrumentHooksCallbacks {
+    /**
+     * [Optional] Namespace details (same as the namespace used for events), useful for debugging and testing to
+     * identify the source of the instrumented hooks
+     */
+    ns?: string | string[];
 
     /**
      * The hook callback to call before the original function is called
@@ -40,20 +45,20 @@ export interface IInstrumentHooksCallbacks {
  */
 export interface IInstrumentHook {
     /** Unique Id for this callback on the hooked method */
-    id:number;
+    id: number;
 
     /** Holds the callbacks */
-    cbks:IInstrumentHooksCallbacks;
+    cbks: IInstrumentHooksCallbacks;
 
     /** Remove this hook from the function */
     rm: () => void;
 }
 
 export interface IInstrumentHooks {
-    i:number;               // Used to create unique ids
-    n:string;               // Function name
-    f:any;                  // Original Function
-    h:IInstrumentHook[];    // The hook
+    i: number;               // Used to create unique ids
+    n: string;               // Function name
+    f: any;                  // Original Function
+    h: IInstrumentHook[];    // The hook
 }
 
 export interface IInstrumentCallDetails {

package/src/JavaScriptSDK.Interfaces/IProcessTelemetryContext.ts

@@ -9,6 +9,7 @@ import { ITelemetryItem } from "./ITelemetryItem";
 import { IPlugin, ITelemetryPlugin } from "./ITelemetryPlugin";
 import { ITelemetryPluginChain } from "./ITelemetryPluginChain";
 import { ITelemetryUnloadState } from "./ITelemetryUnloadState";
+import { ITelemetryUpdateState } from "./ITelemetryUpdateState";
 
 export const enum GetExtCfgMergeType {
     None = 0,
@@ -110,8 +111,8 @@ export interface IProcessTelemetryContext extends IBaseProcessingContext {
 }
 
 /**
- * The current context for the current call to processTelemetry(), used to support sharing the same plugin instance
- * between multiple AppInsights instances
+ * The current context for the current call to teardown() implementations, used to support when plugins are being removed
+ * or the SDK is being unloaded.
  */
 export interface IProcessTelemetryUnloadContext extends IBaseProcessingContext {
 
@@ -131,3 +132,25 @@ export interface IProcessTelemetryUnloadContext extends IBaseProcessingContext {
      */
      createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryUnloadContext;
 }
+
+/**
+ * The current context for the current call to the plugin update() implementations, used to support the notifications
+ * for when plugins are added, removed or the configuration was changed.
+ */
+export interface IProcessTelemetryUpdateContext extends IBaseProcessingContext {
+    /**
+     * This Plugin has finished unloading, so unload the next one
+     * @param updateState - The update State
+     * @returns boolean (true) if there is no more plugins to process otherwise false or undefined (void)
+     */
+    processNext: (updateState: ITelemetryUpdateState) => boolean | void;
+
+    /**
+     * Create a new context using the core and config from the current instance, returns a new instance of the same type
+     * @param plugins - The execution order to process the plugins, if null or not supplied
+     *                  then the current execution order will be copied.
+     * @param startAt - The plugin to start processing from, if missing from the execution
+     *                  order then the next plugin will be NOT set.
+     */
+     createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryUpdateContext;
+}

package/src/JavaScriptSDK.Interfaces/ITelemetryPlugin.ts

@@ -5,9 +5,10 @@
 import { ITelemetryItem } from "./ITelemetryItem";
 import { IConfiguration } from "./IConfiguration";
 import { IAppInsightsCore } from "./IAppInsightsCore";
-import { IProcessTelemetryContext, IProcessTelemetryUnloadContext } from "./IProcessTelemetryContext";
+import { IProcessTelemetryContext, IProcessTelemetryUnloadContext, IProcessTelemetryUpdateContext } from "./IProcessTelemetryContext";
 import { ITelemetryPluginChain } from "./ITelemetryPluginChain";
 import { ITelemetryUnloadState } from "./ITelemetryUnloadState";
+import { ITelemetryUpdateState } from "./ITelemetryUpdateState";
 
 export interface ITelemetryProcessor {
     /**
@@ -18,6 +19,16 @@ export interface ITelemetryProcessor {
      * to later plugins (vs appending items to the telemetry item)
      */
     processTelemetry: (env: ITelemetryItem, itemCtx?: IProcessTelemetryContext) => void;
+   
+    /**
+     * The the plugin should re-evaluate configuration and update any cached configuration settings or
+     * plugins. If implemented this method will be called whenever a plugin is added or removed and if
+     * the configuration has bee updated.
+     * @param updateCtx - This is the context that should be used during updating.
+     * @param updateState - The details / state of the update process, it holds details like the current and previous configuration.
+     * @returns boolean - true if the plugin has or will call updateCtx.processNext(), this allows the plugin to perform any asynchronous operations.
+     */
+    update?: (updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState) => void | boolean;
 }
 
 /**

package/src/JavaScriptSDK.Interfaces/ITelemetryUpdateState.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { TelemetryUpdateReason } from "../JavaScriptSDK.Enums/TelemetryUpdateReason";
+import { IConfiguration } from "./IConfiguration";
+import { IPlugin } from "./ITelemetryPlugin";
+
+export interface ITelemetryUpdateState {
+
+    /**
+     * Identifies the reason for the update notification, this is a bitwise numeric value
+     */
+    reason: TelemetryUpdateReason;
+
+    /**
+     * If this is a configuration update this was the previous configuration that was used
+     */
+    //prvCfg?: IConfiguration,
+
+    /**
+     * If this is a configuration update is the new configuration that is being used
+     */
+    //newCfg?: IConfiguration,
+
+    /**
+     * This holds a collection of plugins that have been added (if the reason identifies that one or more plugins have been added)
+     */
+    added?: IPlugin[];
+
+    /**
+     * This holds a collection of plugins that have been removed (if the reason identifies that one or more plugins have been removed)
+     */
+     removed?: IPlugin[]
+}

package/types/JavaScriptSDK/BaseCore.d.ts

@@ -1,15 +1,18 @@
 import { IAppInsightsCore, ILoadedPlugin } from "../JavaScriptSDK.Interfaces/IAppInsightsCore";
 import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
-import { IPlugin } from "../JavaScriptSDK.Interfaces/ITelemetryPlugin";
+import { IPlugin, ITelemetryPlugin } from "../JavaScriptSDK.Interfaces/ITelemetryPlugin";
 import { IChannelControls } from "../JavaScriptSDK.Interfaces/IChannelControls";
 import { ITelemetryItem } from "../JavaScriptSDK.Interfaces/ITelemetryItem";
 import { INotificationManager } from "../JavaScriptSDK.Interfaces/INotificationManager";
 import { INotificationListener } from "../JavaScriptSDK.Interfaces/INotificationListener";
 import { IDiagnosticLogger } from "../JavaScriptSDK.Interfaces/IDiagnosticLogger";
-import { IProcessTelemetryContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
+import { IProcessTelemetryContext, IProcessTelemetryUpdateContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
 import { IPerfManager } from "../JavaScriptSDK.Interfaces/IPerfManager";
 import { ICookieMgr } from "../JavaScriptSDK.Interfaces/ICookieMgr";
 import { ITelemetryInitializerHandler, TelemetryInitializerFunction } from "../JavaScriptSDK.Interfaces/ITelemetryInitializers";
+import { UnloadHandler } from "./UnloadHandlerContainer";
+import { ITelemetryUpdateState } from "../JavaScriptSDK.Interfaces/ITelemetryUpdateState";
+import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
 export declare class BaseCore implements IAppInsightsCore {
     static defaultConfig: IConfiguration;
     config: IConfiguration;
@@ -60,10 +63,32 @@ export declare class BaseCore implements IAppInsightsCore {
      * @returns - A ITelemetryInitializerHandler to enable the initializer to be removed
      */
     addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler | void;
+    /**
+     * Unload and Tear down the SDK and any initialized plugins, after calling this the SDK will be considered
+     * to be un-initialized and non-operational, re-initializing the SDK should only be attempted if the previous
+     * unload call return `true` stating that all plugins reported that they also unloaded, the recommended
+     * approach is to create a new instance and initialize that instance.
+     * This is due to possible unexpected side effects caused by plugins not supporting unload / teardown, unable
+     * to successfully remove any global references or they may just be completing the unload process asynchronously.
+     */
+    unload(isAsync?: boolean, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void;
     getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
+    addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void;
     /**
      * Returns the unique event namespace that should be used
      */
     evtNamespace(): string;
+    /**
+     * Add an unload handler that will be called when the SDK is being unloaded
+     * @param handler - the handler
+     */
+    addUnloadCb(handler: UnloadHandler): void;
     protected releaseQueue(): void;
+    /**
+     * Hook for Core extensions to allow them to update their own configuration before updating all of the plugins.
+     * @param updateCtx - The plugin update context
+     * @param updateState - The Update State
+     * @returns boolean - True means the extension class will call updateState otherwise the Core will
+     */
+    protected _updateHook?(updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState): void | boolean;
 }