Microsoft 365 Community Microsoft Teams, 11 Oct 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Build your first Command bot for Microsoft Teams with Teams Toolkit for Visual Studio Code

Description

In this 26-minute developer/designer focused demo, Garry Trinder shows how command bots automate repetitive tasks through a conversational interface. Teams Toolkit expedites the creation of command bots, and TeamsFX provides a layer of abstraction that simplifies working with bot framework. Create a command bot using Teams Toolkit, look at what was scaffolded, see Adaptive Cards in UI and then go deep into the code to understand implementation. Add command bots to a team, chat or meeting. This PnP Community demo is taken from the weekly Microsoft 365 Platform Community call recorded on October 11, 2022.

Demo Presenter
• Garry Trinder (Microsoft) | @garrytrinder

Supporting materials
• Documentation - Teams Toolkit Overview | https://learn.microsoft.com/microsoftteams/platform/toolkit/teams-toolkit-fundamentals?pivots=visual-studio-code
• Documentation - Create a new Teams project | https://learn.microsoft.com/microsoftteams/platform/toolkit/create-new-project?pivots=visual-studio-code
• Documentation - TeamsFx SDK | https://learn.microsoft.com/microsoftteams/platform/toolkit/teamsfx-sdk
• Repo - Microsoft Teams Toolkit | https://github.com/OfficeDev/TeamsFx

Related demos
• Demo - Getting started with Teams Toolkit for Visual Studio – Garry Trinder (Microsoft) | @garrytrinder | https://youtu.be/qFxLUagga80?t=1310
• Demo - Build your first Notification bot for Microsoft Teams with Teams Toolkit for Visual Studio Code – Garry Trinder (Microsoft) | @garrytrinder | https://youtu.be/X3spdOS4jOk?t=1203

Learn more
• Microsoft 365 Unified Sample gallery - https://aka.ms/m365/samples
• Microsoft 365 Platform Community in YouTube - https://aka.ms/m365/videos
• Microsoft 365 Platform Community - http://aka.ms/m365/community

A

B

Is going to be build your first command bot, using teams toolkit for visual studio code just to introduce myself? My name is Gary trinder I'm, a senior Cloud developer Advocate at Microsoft and I'm focused on Microsoft 365. lots of links in in this slide.

B

If you want to get in touch with me with any questions after this session, or you know just check out the things that I've been doing and sharing uh loads of links on there, please do check them out, and you know, if you have any questions, please do not hesitate to uh to just get in touch with me. I'll do everything that I can to uh to help you out?

B

Okay, just a quick agenda, uh so um first I'm going to go through. What's the command bot I'm going to cover quickly teams toolkit for visual studio code? For those who don't know what it is, I'm going to step through then creating this first project, quick overview of of what has been created for that project, running a bot for the first time.

B

So we're going to see it in action and then I'm going to go back through the code and explain how it works in the way that it does and and also then show you how you can Implement new commands and before we wrap up with a summary and some resources for you to basically get started, building a Bots using the teams toolkit for visual studio code and I'd really love to know what you build after this. um So, let's start with what is a command bot, so a command bot is something that is useful.

B

To repeat repetitive, commands through a conversational interface. So let's say you just want to go into themes. Ask a bot to I know, send an email to your boss. You can instruct that bot through a command and run some logic that is as simple as I could probably put it. There'll, be lots of different use cases, um but that is essentially it. You have a bot with several commands that you can invoke and then get a response, we're going to build this going through this session today, using teams toolkit for visual studio code.

B

So for those who are not aware of teams, toolkit teams toolkit Visual Studio code is an extension that you can install for the marketplace which enables you to create new projects really quickly for Microsoft teams apps, and it sets up debug and also has lots of features in there for publishing that app as well to your store and also to azure, there's also a team's toolkit for visual studio.

B

Just to make you aware, so, if you're a net developer, that's something that might interest you I'm not going to cover it today, but we'll cover it in in other sessions, and so for today, we're going to be focused on JavaScript and typescript as the technology that we're going to use you'll be glad to know that is the end of the slides really for now and we're going to jump into Visual Studio code and I'm actually going to show you things um running.

B

So, let's begin so like I mentioned we're going to use teams toolkit Visual Studio code, quick way of installing that we can go to the extensions pane in Visual Studio code. We can simply look for teams toolkit, not returning the results. You can click install, that's it it'll install in a matter of seconds when it has installed.

B

You'll get the team's icon in the sidebar click that you can open the team's toolkit and you're going to get the options immediately and to create a new project because we're just in an empty Visual, Studio code window here, there's some also some samples that you can take advantage of as well. So um if you're looking for ideas, check out the samples and you can install those as well and and run them, so let's create a new teams. App uh we've got very several capabilities that we can add to our app.

B

So we've got Bots, we've got tabs and we've got message, extensions as well, and so we're going to concentrate on the command bot for now. So, let's select command bot um I mentioned. We've got uh JavaScript and typescript support for the programming language that you want to use, I'm going to use typescript and I'm just going to select a folder on my machine for where we're going to actually create this.

B

uh This project so I'm going to give it a name call it Community call, and that has started the scaffolding of the project and in fact it's done. It's nice and quick. So let's just take a quick run over as to what's actually been created here. So let's go through the folders, so we've got an fx folder in here. There's some configuration files, so these are used by teams toolkit as as part of um some of the uh the features that it it uses to launch Bots really quickly against your developer.

B

Tenant we've got a vs code folder, so this contains debug profiles. So this enables us to basically use F5 in Visual Studio code to launch our bot and open a web browser and and test it out really quickly and also the debug profile.

B

So you can actually put breakpoints in code as well and then follow that code execution, which is really really useful, and we have our bot folder, which is where our our logic is held for the bot that we're going to create I'll jump back into that for a second we'll just skip to templates folder.

B

So these templates folders uh it contains two types of templates, so one we've got a template for our app manifest that we publish to teams and we've also got an Azure folder, which provides us with templates, uh bicep templates that we can use to deploy and provision uh all the resources that are needed to uh to have this running in the cloud and not running on our local machine. So toolkit provides all of that for us, which is really really great skip into the uh the bot folder.

B

So here we've got our source code um in here. We've got some command handlers. We've got some adaptive cards and some internal files, where uh toolkit has already set up things like uh configuring out a bot um and uh and wiring up the app IDs app passwords handling.

B

All that complexity for us and what I'm going to do is we're going to jump and I'm going to show you the bot actually running and then we'll come back and I'll jump into these individual files to just explain how the functionality that I show you is is implemented in this project, so I'm just going to jump to a project that I've already created just quickly jump back. So here's one that I've I've already created I've already hit F5.

B

um So when you hit F5 teams talk, it's going to do a number of um activities for you and it's going to check. Make sure that everything on your machine is uh good and valid. So you've got a a supply. Node version.

B

um You've got everything installed on your machine like the npm packages that are needed, um as well as connecting to your Microsoft 365 tenant, so I'm going to show you that I've already connected to my Microsoft 365 tenant.

B

uh If I look at the team's toolkit tab, so I've already signed in it's telling me that side loading is enabled, which is something that we need to be enabled on the tenant uh to uh to basically launch our app and and and and test it, and so this is enabled by default, if you're, using a Sandbox uh tenant from the developer program. If you're not. uh This might be something that you need to configure yourself. So it's a setting in the team's admin Center that you just need to go and switch.

B

um There might be a slight delay before that uh becomes enabled, um but once that's been done, you don't have to redo that again for that uh for that tenant, so I've already signed in. So what I'm going to do is I'm going to run uh the uh the bot and we've got some profiles there for Chrome and Edge I'm, going to run this in Edge, so I can hit the run. The debug button or I can just hit F5 on my keyboard. It'll do the same thing.

B

So, let's run it so this is going to run by quite quick, but what this is doing, teams toolkit is. It's checking all those prerequisites, uh it's uh like I say it's checking for node. It's checking our 365 account it's checking for npm packages, it's also checking and installing ngrok as well, which is uh needed for for tunneling.

B

So um you don't have to pre-install that um you don't have to do anything with ngrok team's toolkit, Visual Studio code, we'll install it for you and launch it as well. In the background so now this has launched, we've got teams uh opened in the web browser and we will get the uh the app loading pane. So we've got different places where we can install this to start a team or a chat or actually into a meeting as well.

B

So if you want to have a um a bot that is available in a meeting for people to kind of make invoke commands in then you can, you can add this, this bot to those meetings, I'm just going to add it as a personal app at the moment. So it's just installed for for my user.

B

um You can probably see there's some usage of it already, um but this is what a command bot is. uh If you go to the the text box, the the bot provides certain commands so out the box. We've got a hello world. Commandment, we get this nice suggestion um as well from from the UI. So if you've got multiple commands, you'll have a nice list here and as you're typing, um the uh the different commands that I've got available to you.

B

It will provide you with the one that matches uh your your message and what I can do is I can just invoke this I can just send the message to the bot and in this example, when we send hello world, uh it will reply with an Adaptive card and also it will uh reply with the uh I think yeah.

B

It replies with the uh the text as as well in there with using adaptive cards, you've got the ability to add actions as well, and so these are just buttons that go to URLs at the moment, but you can imagine if you want to invoke a uh a command that maybe has a form or you want to send some information somewhere.

B

This is a a you know: a use case of using a a command bot you're just invoke in some functionality uh by by sending the bot a a message, so I'm going to quickly jump back to visual studio code now and let's take a look at the code um to show you how this is all set up, so first I'm going to go to the internal folder and go to the initialize file.

B

Now this is where our bot is defined so um convention that our bot has been set up for us by teams toolkit it's gone away to the bot framework service. It's registered a bot in that service as well. It's pulled the ID and the password for us and basically inject that into this this new object.

B

What we've also got is further configuration, so we there's a command property uh that allows you to include different handlers, so a Handler would be a Handler for a particular message that comes in.

B

If we take a look at the hello world command Handler which has been created for us, we can see that there is a class hello world command Handler, which is uh in implementing a an interface from teams. Fx teams FX is a SDK. That's basically provided us with a layer of abstraction over the bot framework. It's making it easy for us to to create new commands using this team's FX class.

B

So one of the things that this class allows us to do is allows us to define the trigger patterns. So if there is a message sent to this bot that matches this string, it will run the handle command received function and that will be where our logic will uh will will fire. So this trigger pattern. Actually uh it can accept a string, but it can also accept regex as well. So you can have you know a command that could be fired by different uh different words at different times, and so it can be really flexible.

B

If we just take a quick look at the handle command received function, so we can see that we're logging out that the bot received a message. So we do actually get the message back. If we take a look at that, so we can see the actual text that was sent to us and also matches as well. So, let's say, for instance, I did hello world and a name. At the end, we were able to pick out the different values that have been sent through on that command.

B

So you could, you know, easily, have a command that accepts a a parameter and then use that within your logic, foreign.

B

So the next thing that this spot does is that it's actually going to send an Adaptive card back and the way that it does. That is that it can use this message Builder from teamsfx again, um and we have a attach adaptive card method where we can pass in our uh hello world adaptive card and some data with it as well. So we have this variable here with title and a body and we're going to send that to our bot, along with the Adaptive card definition which is held in this Json file here.

B

So we can see that we have placeholders for title and for body, and we've also got actions in there to open URLs in teams and so there's various different actions that are available in adaptive cards. So you can have execute for for forms as well, um but this example it's just using open URL for the moment. So this might be great for let's say I know a q, a bot. uh You want to ask a question: you get a response. You have some buttons provided that take you to a documentation.

B

Page people can then fire their answers from.

B

So if we look at the implementation of these, so we've we've got uh our Handler. um Our Handler knows that it is triggered by a particular pattern, in this case Hello World. One thing that we did see was we had suggestions. So when I went to the uh the text box, the compose box, it actually came up and said- oh here, are some suggested commands that you can, uh that you can use, so those are defined actually in the app manifest endpoint.

B

So if we go to templates uh app packages and manifest template.json, we have here a command list um array and in there there is a a command array is where we can Define our commands that are available, and so this this list here. This array is the list of commands that you want to be able to show the user of your Bot um quick examples of you know what messages can you send and what functionality is going to be provided?

B

So you can just simply add in new ones and new handlers, just add in a title and a description.

B

And then, when that next gets uploaded to um the teams, that will be available as a new suggestion. So if you're wanting to let's say Implement new command, then the way that you would do that is, you would update those uh two different locations um in um in in our source folder. So, first we would come to initialize. We would add our new Handler in here foreign, something like this, and we would actually create a new class that implements from the teamsfx bot command, Handler and we'd.

B

Add in the trigger patterns, add in the handle command received, and then that would be picked up and that would be a new command that users would be able to to use so the way that um Team stalker has provided us with really the the basics of. How do we register new commands? How do we invoke commands? What suggestions are available to to users and how do we, you know?

B

How do we send data back to the user is, is all handled quite nicely through this command Handler and through the handle command received function and using the attach adaptive card method? To then send you know a nice adaptive card rack. If we didn't want to send an Adaptive card, we can also just send text. So we have something called the turn context which is provided for us and we can send an activity back which can just contain plain text, so we can actually keep sending messages as well.

B

um So, as part of you know the uh the functionality of this command, uh you could just have you know single line messages and then provide an Adaptive card um as well for users to to actually follow.

B

Okay, so that really covers the basics of getting started with a command bot. So let me just quickly jump back to my slides, so I just want you to to Really summarize uh kind of what we what I'd shown. um So you know command. Bots are a great way of being able to automate those repetitive tasks through that conversational interface. So you know, rather than having a button on a page, maybe something that's a bit more interactive like a bot and that you can use.

B

As you know, maybe like your personal assistant to just say you know, but do a particular action, and that's that's a great way of being being able to implement that and it's the starting point as well, for you know a q, a bot, a more advanced conversational, but adding um cognitive services like Lewis as well, and to really kind of enhance that, but at its basic uh implementation level, it's a user is inputting something that the bot is then reacting to with some.

B

You know certain logic, whether that is displaying uh information through an Adaptive card are actually capturing information uh back as well. um So I've shown you teams talk it as provide the quickest way to get started developing. Certainly these command, Bots and and just teams apps in general. You should I showed you how quickly uh and easily it was to just create that initial project and then get that running um as well, using F5 and also that teams FX is providing this layer of abstraction to simplify working with the bot framework.

B

So you were able to just create a single Handler and Define the trigger pattern, and that would invoke the logic in that command and then how that was wired up with the the bot definition as well um and yeah. Again theme store kits kind of handling a lot of the complexities there just making it really easy. So you can focus on what your command needs to do so resources.

B

So there's plenty of resources on docs, so definitely check out teams toolkit overview, and so whether you are interested in in the visual studio code, extension or even the visual studio enhancement as well, and then definitely check out that page. So everything is provided on there with some quick starts about creating a new teams. App and there's also more on teams FX SDK, so that is on GitHub, definitely check out the repository and the docs.

B

There's lots of information down there and samples as well um about you know how you can take this further extra things that you can do with the the command handlers and finally, just want to say. Thank you very much and I think we jump into the questions. I can see Victor's already in there. There's lots of activity in there. So I don't know if there's anything that hasn't been answered, I'm just quickly, jumping back through I.

C

Think most of it's already answered there's a couple like more governance. Questions like around you know how to manage this. These many Bots and there was one about moving from Dev to prod and I. Think Victor is actually communicating. Some of the you know communicating answers to some of that, or at least give some suggestions.

C

B

I think I found one question from Scott: are there Enterprise supported options, not using anger up, so I would say that, as um you may be working for an organization that can't use ngrok. So at the moment there isn't um in the visual studio code extension, and it is very opinionated in that it uses engrock. However, it is on the roadmap to use other tunneling services, so this is something that definitely the team are aware of and are actively working to to provide an alternative.

B

But at the moment uh yeah, if you're, using the visual studio code um version, uh it's tied to uh engrock.

A

Yeah I think there's two other interesting questions. The first one I partially answered, but it was about. Where do you place the logic for your command bot? If you just don't want to show that card, but you want to have some business logic or whatever? Where would you do do that and the second one is: uh do we require actual app services to run this uh house? Everything being set up essentially.

B

So I can answer the second one quite quickly, um so one thing which I I didn't actually mention was the implementation of of that uh bot. So it that project template uses uh restify as part of its implementation, which means it will need a an app service to uh to to run when you revision that and deploy it to azure.

B

So that will just need the um like, say: a normal app service. In fact, the the bicep files there's I think it uses B one of the dev test skus uh to provision that app service for you. So that is something that you need. It doesn't use it as your functions.

B

um You definitely need that that app service in terms of the the logic um in terms of uh so where will the? Where will the data save? So at this the out the box um there's conversation history, which is saved in memory.

B

That's something that when you move to production, you're going to need to add some persistent storage easiest way to do that is using Azure, Cosmos, DB or table storage, and to save that that conversation uh data to, um but at the moment that that bot is, is very much just it's running in memory, nothing saved anywhere. So that's something that you would have to look into and Implement yourself, however, saying that team's toolkit does have a feed feature.

B

So there's an ad features get wizard in there, which gives you options to stand up a SQL database and Azure functions as well in your project. So it's a bit more advanced from what I was going through today. It was very much a. How do you get started and but if that's something that you're really interested in then that's something that we can definitely look to cover in another call, as we start to delve into you know going past the just getting started and creating your your first project.

B

um So you know if any feedback like that, definitely want to hear it. You know we want to do kind of sessions that are going to help you progress using teams toolkit so uh yeah just uh get in touch.

C

Absolutely that is a fantastic demo, fantastic messaging.