Added new basics-firstRun example that shows how to create a first run experience. This also resulted in adding a new Session.replaceDialog() method.

Node/examples/basics-firstRun/app.js

@@ -0,0 +1,52 @@
+/*-----------------------------------------------------------------------------
+This Bot demonstrates how to create a First Run experience using a piece of
+middleware. 
+
+The middleware function will be run for every incoming message and its simply
+using a flag persisted off userData to know if the user been sent to the 
+/firstRun dialog. The first run experience can be as simple or as complex as
+you'd like. In our example we're prompting the user for their name but if you
+just wanted to show a simple message you could have called session.send() 
+instead of session.beginDialog().
+
+You can also use a version number instead of a flag if say you need to 
+periodically update your Terms Of Use and want to re-show an existing user the 
+new TOU on their next interaction with the bot.
+
+Run the bot from the command line using "node app.js" and then type "hello"
+to wake the bot up.
+-----------------------------------------------------------------------------*/
+
+var builder = require('../../');
+
+var bot = new builder.TextBot();
+bot.add('/', function (session) {
+    session.send("Hi %s, what can I help you with?", session.userData.name);
+});
+
+// Install First Run middleware and dialog
+bot.use(function (session, next) {
+   if (!session.userData.firstRun) {
+       session.userData.firstRun = true;
+       session.beginDialog('/firstRun');
+   } else {
+       next();
+   }
+});
+bot.add('/firstRun', [
+    function (session) {
+        builder.Prompts.text(session, "Hello... What's your name?");
+    },
+    function (session, results) {
+        // We'll save the prompts result and return control to main through
+        // a call to replaceDialog(). We need to use replaceDialog() because
+        // we intercepted the original call to main and we want to remove the
+        // /firstRun dialog from the callstack. If we called endDialog() here
+        // the conversation would end since the /firstRun dialog is the only 
+        // dialog on the stack.
+        session.userData.name = results.response;
+        session.replaceDialog('/'); 
+    }
+]);
+
+bot.listenStdin();

Node/lib/Session.js

@@ -99,6 +99,19 @@ var Session = (function (_super) {
         dialog.begin(this, args);
         return this;
     };
+    Session.prototype.replaceDialog = function (id, args) {
+        var dialog = this.dialogs.getDialog(id);
+        if (!dialog) {
+            throw new Error('Dialog[' + id + '] not found.');
+        }
+        var ss = this.sessionState;
+        var cur = { id: id, state: {} };
+        ss.callstack.pop();
+        ss.callstack.push(cur);
+        this.dialogData = cur.state;
+        dialog.begin(this, args);
+        return this;
+    };
     Session.prototype.endDialog = function (result) {
         var ss = this.sessionState;
         var r = result || { resumed: dialog.ResumeReason.completed };

Node/lib/botbuilder.d.ts

@@ -750,7 +750,15 @@ export class Session {
      * @param id Unique ID of the dialog to start.
      * @param args Optional arguments to pass to the dialogs begin() method.
      */
-    beginDialog<T>(id: string, args?: T): Session
+    beginDialog<T>(id: string, args?: T): Session;
+
+    /**
+     * Ends the current dialog and starts a new one its place. The parent dialog will not be 
+     * resumed until the new dialog completes. 
+     * @param id Unique ID of the dialog to start.
+     * @param args Optional arguments to pass to the dialogs begin() method.
+     */
+    replaceDialog<T>(id: string, args?: T): Session;
 
     /**
      * Ends the current dialog. The dialogs parent will be resumed.

Node/src/Session.ts

@@ -110,6 +110,20 @@ export class Session extends events.EventEmitter implements ISession {
         return this;
     }
 
+    public replaceDialog<T>(id: string, args?: T): ISession {
+        var dialog = this.dialogs.getDialog(id);
+        if (!dialog) {
+            throw new Error('Dialog[' + id + '] not found.');
+        }
+        var ss = this.sessionState;
+        var cur: IDialogState = { id: id, state: {} };
+        ss.callstack.pop();
+        ss.callstack.push(cur);
+        this.dialogData = cur.state;
+        dialog.begin(this, args);
+        return this;
+    }
+
     public endDialog(result?: any): ISession {
         var ss = this.sessionState;
         var r: dialog.IDialogResult<any> = result || { resumed: dialog.ResumeReason.completed };

Node/src/botbuilder.d.ts

@@ -750,7 +750,15 @@ export class Session {
      * @param id Unique ID of the dialog to start.
      * @param args Optional arguments to pass to the dialogs begin() method.
      */
-    beginDialog<T>(id: string, args?: T): Session
+    beginDialog<T>(id: string, args?: T): Session;
+
+    /**
+     * Ends the current dialog and starts a new one its place. The parent dialog will not be 
+     * resumed until the new dialog completes. 
+     * @param id Unique ID of the dialog to start.
+     * @param args Optional arguments to pass to the dialogs begin() method.
+     */
+    replaceDialog<T>(id: string, args?: T): Session;
 
     /**
      * Ends the current dialog. The dialogs parent will be resumed.

Node/src/interfaces.d.ts

@@ -80,6 +80,7 @@ interface ISession {
     send(msg: IMessage): ISession;
     messageSent(): boolean;
     beginDialog<T>(id: string, args?: T): ISession;
+    replaceDialog<T>(id: string, args?: T): ISession;
     endDialog(result?: any): ISession;
     compareConfidence(language: string, utterance: string, score: number, callback: (handled: boolean) => void): void;
     reset(id: string): ISession;