Archive for March 2019

This is my version of the how bots work doco page, customised to explain the Enterprise Bot Template.
The reason that I have done my own version is that for me I’d rather read well commented (overly commented) code to understand how something works than reading a paragraph of text, then associating it with code.
Sources
Bot Class

public class EnterpriseBotSample : IBot
{
private readonly BotServices _services;
private readonly ConversationState _conversationState;
private readonly UserState _userState;
private readonly IBotTelemetryClient _telemetryClient;
private DialogSet _dialogs;

The main bot logic is defined in the EnterpriseBotSample class that derives from the IBot interface.
IBot defines a single method OnTurnAsync.
OnTurnAsync

public async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default(CancellationToken))

OnTurnAsync: updated with my code comments. I wouldn’t usually write this many comments in code 😉

// Turncontext provides information about the incoming activity.
public async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default(CancellationToken))
{

//The incoming activity corresponds to the inbound HTTP request.
// Activities can be of various types, so we check to see if the bot has received a message.
if (turnContext.Activity.Type == ActivityTypes.Message)
{
//If it is a message, we get the conversation state from the turn context, increment the turn counter, and then persist the new turn counter value into the conversation state.

// Get the conversation state from the turn context.
var oldState = await _accessors.CounterState.GetAsync(turnContext, () = > new CounterState());

// Bump the turn count for this conversation.
var newState = new CounterState { TurnCount = oldState.TurnCount + 1 };

// Set the property using the accessor.
await _accessors.CounterState.SetAsync(turnContext, newState);

// Save the new turn count into the conversation state.
await _accessors.ConversationState.SaveChangesAsync(turnContext);

// And then send a message back to the user using SendActivityAsync call.
// The outgoing activity corresponds to the outbound HTTP request.

// Echo back to the user whatever they typed.
var responseMessage = $”Turn {newState.TurnCount}: You sent ‘{turnContext.Activity.Text}’n”;
await turnContext.SendActivityAsync(responseMessage);
}
else
{
await turnContext.SendActivityAsync($”{turnContext.Activity.Type} event detected”);
}
}

Set up services
The ConfigureServices method in the startup.cs file
is where .NET Core configure Dependency Injection as per the docs
it loads the connected services from .bot file,
catches any errors that occur during a conversation turn and logs them,
sets up your credential provider and
creates a conversation state object to store conversation data in memory.

services.AddBot(options = >
{
// Creates a logger for the application to use.
ILogger logger = _loggerFactory.CreateLogger();

var secretKey = Configuration.GetSection(“botFileSecret”)?.Value;
var botFilePath = Configuration.GetSection(“botFilePath”)?.Value;

// Loads .bot configuration file and adds a singleton that your Bot can access through dependency injection.
BotConfiguration botConfig = null;
try
{
botConfig = BotConfiguration.Load(botFilePath ?? @”.BotConfiguration.bot”, secretKey);
}
catch
{
//…
}

services.AddSingleton(sp = > botConfig);

// Retrieve current endpoint.
var environment = _isProduction ? “production” : “development”;
var service = botConfig.Services.Where(s = > s.Type == “endpoint” && s.Name == environment).FirstOrDefault();
if (!(service is EndpointService endpointService))
{
throw new InvalidOperationException($”The .bot file does not contain an endpoint with name ‘{environment}’.”);
}

options.CredentialProvider = new SimpleCredentialProvider(endpointService.AppId, endpointService.AppPassword);

// Catches any errors that occur during a conversation turn and logs them.
options.OnTurnError = async (context, exception) = >
{
logger.LogError($”Exception caught : {exception}”);
await context.SendActivityAsync(“Sorry, it looks like something went wrong.”);
};

// The Memory Storage used here is for local bot debugging only. When the bot
// is restarted, everything stored in memory will be gone.
IStorage dataStore = new MemoryStorage();

// …

// Create Conversation State object.
// The Conversation State object is where we persist anything at the conversation-scope.
var conversationState = new ConversationState(dataStore);

options.State.Add(conversationState);
});

Startup.cs – configuring state
Note: this is different to the getting started doc. It works differently in the enterprise template – we aren’t configuring the stateaccessors in the ConfigureServices method
Understanding state

var dataStore = new CosmosDbStorage(cosmosOptions);
var userState = new UserState(dataStore);
var conversationState = new ConversationState(dataStore);

services.AddSingleton(dataStore);
services.AddSingleton(userState);
services.AddSingleton(conversationState);
services.AddSingleton(new BotStateSet(userState, conversationState));

startup.cs – Configure method
The Configure method finishes the configuration of your app by specifying that the app use the Bot Framework and a few other files. All bots using the Bot Framework will need that configuration call. ConfigureServices and Configure are called by the runtime when the app starts.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}

app.UseBotApplicationInsights()
.UseDefaultFiles()
.UseStaticFiles()
.UseBotFramework();
}

The bot file
The .bot file contains information, including the endpoint, app ID, and password, and references to services that are used by the bot. This file gets created for you when you start building a bot from a template, but you can create your own through the emulator or other tools. You can specify the .bot file to use when testing your bot with the emulator.

{
“name”: “echobot-with-counter”,
“services”: [
{
“type”: “endpoint”,
“name”: “development”,
“endpoint”: “https://localhost:3978/api/messages”,
“appId”: “”,
“appPassword”: “”,
“id”: “1”
}
],
“padlock”: “”,
“version”: “2.0”
}

State

– User state is available in any turn that the bot is conversing with that user on that channel, regardless of the conversation
– Conversation state is available in any turn in a specific conversation, regardless of user (i.e. group conversations)
– Private conversation state is scoped to both the specific conversation and to that specific user

Source: Managing State

public class OnboardingDialog : EnterpriseDialog
{
private static OnboardingResponses _responder = new OnboardingResponses();
private IStatePropertyAccessor _accessor;
private OnboardingState _state;

public OnboardingDialog(BotServices botServices, IStatePropertyAccessor accessor, IBotTelemetryClient telemetryClient)
: base(botServices, nameof(OnboardingDialog))
{
_accessor = accessor;
InitialDialogId = nameof(OnboardingDialog);

var onboarding = new WaterfallStep[]
{
AskForName,
AskForEmail,
AskForLocation,
FinishOnboardingDialog,
};

// To capture built-in waterfall dialog telemetry, set the telemetry client
// to the new waterfall dialog and add it to the component dialog
TelemetryClient = telemetryClient;
AddDialog(new WaterfallDialog(InitialDialogId, onboarding) { TelemetryClient = telemetryClient });
AddDialog(new TextPrompt(DialogIds.NamePrompt));
AddDialog(new TextPrompt(DialogIds.EmailPrompt));
AddDialog(new TextPrompt(DialogIds.LocationPrompt));
}

public async Task AskForName(WaterfallStepContext sc, CancellationToken cancellationToken)
{
_state = await _accessor.GetAsync(sc.Context, () = > new OnboardingState());

if (!string.IsNullOrEmpty(_state.Name))
{
return await sc.NextAsync(_state.Name);
}
else
{
return await sc.PromptAsync(DialogIds.NamePrompt, new PromptOptions()
{
Prompt = await _responder.RenderTemplate(sc.Context, sc.Context.Activity.Locale, OnboardingResponses.ResponseIds.NamePrompt),
});
}
}

Dialogues
See the docs
Gathering user input via Dialogues

This is a draft agenda for the bot workshops that Valeriia and I run with our customers.
I intend to flesh this out and improve it as we run more and more.
Demo of the Enterprise Bot Template
Enterprise Bot Template Architecture Discussion
Intro to LUIS
configure global LUIS Intents
configure app specific LUIS Intents
Intro to QnA Maker
configure global QnA Maker
configure app specific QnA Maker
Intro to the Dispatcher
wiring together the LUIS & QnA Maker docs
Installing the Enterprise Bot Template
Deploying the Enterprise Bot Template
Deploying your bot
Customise the Enterprise Template
Customise the template
Review Project Structure
Update Intro Message
Update Bot Responses
(skip updating cognitive models – already done)
Add a new dialog
View bot analytics & Telemetry
Code inspection
Typing indicators
Language support
Transcripts
Consuming external APIs
Configure Authentication

images from https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-concept-dialog?view=azure-bot-service-4.0
Resources:

Setup Requirements
The requirements for the Enterprise Bot Template (as per https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-enterprise-template-deployment?view=azure-bot-service-4.0 )
Enterprise Template Bots require the following dependencies for end to end operation.
Azure Web App
Azure Storage Account (Transcripts)
Azure Application Insights (Telemetry)
Azure CosmosDb (Conversation State storage)
Azure Cognitive Services – Language Understanding
Azure Cognitive Services – QnA Maker (includes Azure Search, Azure Web App)
Azure Cognitive Services – Content Moderator (optional manual step)
Deploy the Enterprise Template before the workshop
Because the workshop covers a lot of ground, it is best if before the workshop a developer on the project follows the Create, Customise and Deploy steps for the bot template.
The instructions are very straight forward and clear. Once this is done – in the workshop we can spend time explaining the code and best practices as opposed to going through the exact steps in the doco.
Create the project https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-enterprise-template-create-project?view=azure-bot-service-4.0
Customer the template https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-enterprise-template-customize?view=azure-bot-service-4.0
Deploy the template https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-enterprise-template-deployment?view=azure-bot-service-4.0
I’m looking forward to building a bot together !

2019-03-08PERSONAL ·Project Lessons Success

Lessons learnt after recently completing a successful projectA colleague and I recently finished a short 3-week project with a client, the result of which is one very happy client, and an MVP finished before the deadline. Below are the lessons that I learnt during that project.
Success
First, let me define success in this situation.

Completing the Minimum Viable Product feature set within the strict budget constraints set by the client.
A product the end-user can easily use
Intuitive integration points that just work
A Happy client

I for one was extremely surprised with the result, as going into it I still wasn’t 100% sure what the final implementation would look like, and even though the estimates from the spec review suggested it would be possible, I was still worried.
From an architectural and technology point of view, there wasn’t anything tricky, this was a standard UI and API. Given our tight time constraints, and also the great feedback from Jason Taylor’s Clean Architecture video, this was where we started. https://github.com/JasonGT/NorthwindTraders. This is a well laid out and easy to understand implementation of the clean architecture pattern.
DON’T Start from scratch
Thanks Jason for the hard work, I was expecting to spend days or more on building a base framework, but having this reference meant it was pretty much done within the first day. However simply cutting and pasting the code isn’t enough, being familiar with how and why it works is even more important, especially the Nswag integration as it isn’t obvious to start with. If you are unsure, I’m happy to answer questions, as I assume Jason would be too. This also goes for the UI, Leveraging past projects to have a basic UI template, Angular (No Ngrx on this one) + FlexLayout + Angular material + Nswag also helped with lesson 2 below. Note: Starring Jason’s Repo, and publicly acknowledging/thanking him (eg twitter) is not only a nice thing to do, but it also helps Jason realise the positive impact he has on our community. This goes for all resources you find helpful.
Lesson 1: Use (and understand) a reference architecture, don’t waste time starting from scratch. If one doesn’t exist CREATE One just as Jason did
Lesson 1a: If you do use someone’s reference, acknowledge them and thank them, let them know how it helped, it’s easy to do, it’s free, and it’s the nice thing to do. Preferably publicly, so their hard work gets noticed, otherwise privately at the very least, so they know they have helped out in some way.
Get the UI up and running before the first demo, and validate early
As the project was moving along at a rapid pace, and we were also aware of the limited time/budget for the project, we made a point of ensuring there was some form of UI available for our first sprint demo, to ensure the UI was on the right path, and to ensure the client felt like there was progress.
Lesson 2: Validate your UI design with the Product Owner as soon as you have something to show, and make sure you can demo at first sprint review
Don’t underestimate the Bureaucratic processes of large enterprises
As much as we put an emphasis on getting DevOps up and running within the first sprint, We (well I) severely underestimated the complexity involved in getting environments set up in a large bureaucratic enterprise, it wasn’t until the second last day before we eventually got an automated deployment to a staging environment. We decided to finish up early, to save some time up our sleeve, to allow for user testing, before going live.
Lesson 3: When dealing with a large organisation try to get someone from the infrastructure/provisioning team allocated to your project in the early days, to get the environments up and running as soon as possible.
Lesson 3a: Have a backup plan, If needed use your free Azure credits, so the client can test early.
Communication
We were fortunate enough to have good access to the Product Owner and the Domain experts that we needed to integrate with. The discussions we had between Us and the PO (non-technical); Us and Integration team (Technical) and even between ourselves, resulted in catching incorrect assumptions before they became difficult to rectify, or helped clarify (and alleviate) some concerns the Product Owner may have had, and also meant that our integrations went very smoothly even though we had limited opportunity to test this early.
Lesson 4: Communicate with EVERYONE more than you think is necessary.
Lesson 4a: Spend time educating a Non-Technical Product Owner as to the “WHY” things are implemented the way they are, don’t get bogged in the “HOW”. The client mentioned their appreciation of this on more than one occasion
Lesson 4b: Technical resources from the client may not be as experienced, the time spent educating them on the “HOW” and the “WHY” will help maximise the likelihood of successful integrations
Lesson 4c: Technical conversations/discussions/arguments, whiteboarding amongst the technical team is invaluable, and only benefit the project
Closing thoughts
Of all of these lessons, I cannot understate that 4a, Taking the time to explain and discuss with the Product Owner your decisions in a non-technical manner was by far, the most valuable lesson, and resulting in a client that was extremely happy throughout the process, so much so, that there is already talk of a follow up project orders of magnitude larger than this.
Even though the timeframes and the environment provided us with our fair share of challenges and stresses (don’t they all), hitting all of our milestones and working so closely with the client helped ensure that this was not only a successful project, but we had fun along the way. Best of all, I learnt plenty, especially the non-technical stuff.

I’ve left WordPress. Finally.
WordPress isn’t bad. In fact for most people I think WordPress or Medium are probably the right choice – but for about 18 months I’ve wanted to move to a solution where I hosted my content on GitHub and then published it from there.
Why ? (the original reasons from 18 months ago)
I love writing in MarkDown. I want to write more blogs and in order to write more – I need to enjoy doing it.
I wanted the content without HTML formatting. This allows me to do more with it.
I wanted to be able to collaborate with my blog content. I want other people to be able to make corrections / update / contribute to my content. If you want to make a change or an addition – feel free to make a pull request.
I wanted to own all my content in a portable format. I use a little Jekyll syntax, but most of the content on the site is written in pure, portable markdown
Why? (the driving reasons that made me finally do it)
I like having some ‘real’ projects to maintain
I wanted to be able to easily edit content offline
I wanted a project to use for Azure demos around topics like DevOps, containers and Azure FrontDoor
Why not ? (Reasons this approach is silly for most people)
You are maintaing code and investing time in something that someone else will do for (Almost) free
Other Solutions that I considered
Hosted Services
Medium https://medium.com/
If you just want to elegantly write content Medium is clean and awesome. This is a great option.
Hosted WordPress https://wordpress.com
WordPress.com is where I hosted my blog for the last 7 years. I set it up, and it just ran. I paid about $5/month to remove the adds and have a custom domain. It supports a huge ecosystem of plugins and functionality. For most developers this is probably my recommended solution. Official hosted wordpress – https://wordpress.com Alternative hosted WordPress (My friend Jason has used this for years and loves it) https://www.bluehost.com/
Hosted Ghost https://ghost.org
Ghost is where all the cool kids were at. If hosted Ghost were not 6x more expensive that WordPress, everyone would use this. This article from Troy Hunt is a great summary of why it’s the best choice if you are happy to pay the money. https://www.troyhunt.com/its-a-new-blog/
Self Hosted Services
Self Hosted Wordpress
Don’t do it.If you are going to do it yourself – Host Ghost
Self Hosted Ghost https://blog.ghost.org/2-0/
Watch this space for more on running Ghost images on Azure.
Resources and Thanks
I got the idea for this method from the old version of the Azure Docs which used Jekyll. I created this project from scratch because the old docs used very outdated versions of dependencies like Jekyll and Bootstrap but I have taken the page templates and a few scripts from their repo… so big thanks to the team who put it together !!!