DEV Community: Tomomi Imura 🐱

Customizing F5 Debugging in Teams Toolkit for VS Code

Tomomi Imura 🐱 — Mon, 31 Oct 2022 19:16:52 +0000

Earlier this year, Teams Toolkit has introduced a few new features that have been added in the latest Toolkit to improve your debugging experience, including Prerequisite Checker and Customizing Debug Settings.

With the latest Toolkit in v.4.1.0 and greater, you can now customize the debugging experiences even more!

If this is the first time with Teams Toolkit, please check out these tutorials first:

🐛 Debugging Experiences in Teams Toolkit

Debugging in VS Code is casually referred to as F5 among developers, is one of the key features of Visual Studio Code, and this built-in debugger helps accelerate your edit, compile, and debug loop.

When you created any project with Teams Toolkit in VS Code, you also use this F5 debugger to run the code. While you are waiting, Teams Toolkit runs various process, check prerequisites, and output the results like this:

In the Output section, you can view what the debugger is doing. In this screenshot, you can see a checklist, including whether you have a specific Node.js, your M365 account status, etc.

So, where these tasks and the checklist are defined? It is in .vscode/tasks.json in the generated project, and you can customize in the way you want. So let's take a look at some customization examples for both a tab app and bot app.

🗂 Customizing tasks.json for Tab Apps

First, let's create a new app by choosing the SSO-enabled Tab from the menu:

Once the project is generated, open .vscode/tasks.json and see what are defined:

You may want to try debugging and see how each item defined in the tasks.json runs and display in the Output by default:

Now, see how to customize the debugging flow by editing the tasks.json file.

✅ Customizing Prerequisites

For example, if you want to skip certain processes, such as checking prerequisites and installing npm packages, just comment out where they are defined in "tasks":

"tasks": [
  {
    "label": "Start Teams App Locally",
    "dependsOn": [
      //"Validate & install prerequisites",
      //"Install npm packages",
      "Set up tab",
      "Set up SSO",
      "Build & upload Teams manifest",
      "Start services"
  ],

Or you can select prerequisites validation independently. Scroll down to the next object in JSON then editing these lines. For example, if you want to skip checking if Node.js is installed, comment the line out:

{
  "label": "Validate & install prerequisites",
  "type": "teamsfx",
  "command": "debug-check-prerequisites",
  "args": {
    "prerequisites": [
      //"nodejs",
      "m365Account", 
      "devCert", 
      "portOccupancy"
    ],

Try running F5 and see if the processes are skipped.

🛎 Customizing npm Commands

Also, you can customize npm install commands by adding an optional argument, for example, --force to force npm to fetch remote resources even if a local copy exists:

{
  "label": "Install npm packages",
  "type": "teamsfx",
  "command": "debug-npm-install",
  "args": {
    "projects": [
      {
        "cwd": "${workspaceFolder}/tabs",
        "npmInstallArgs": [
          "--no-audit",
          "--force" // added!
        ]
...

🛳 Changing Service Port

Tabs in tab apps are basically web pages embedded in Teams client, and they run on a specific port when you debug locally. By default, it is set 53000 and the web portion of your app can be debugged in https://localhost:53000. The Toolkit debugger checks if the port is available.

If you would like to change the port, you need to edit two places in the JSON file:

{
  "label": "Validate & install prerequisites",
  "type": "teamsfx",
  "command": "debug-check-prerequisites",
  "args": {
    "prerequisites": [
      "nodejs",
      "m365Account", 
      "devCert", 
      "portOccupancy"
    ],
    "portOccupancy": [
        33000 // was 53000
    ]
  }

and

{
  "label": "Set up tab",
  "type": "teamsfx",
  "command": "debug-set-up-tab",
  "args": {
    "baseUrl": "https://localhost:33000" // was 53000
  }
},

And you can customize more by deleting/commenting out lines, edit values, and add values in the JSON file.

Some values are commented out by default, such as SSO setup, so you can enable some by uncommenting the lines too. Just customize as your app needs!

🤖 Customizing tasks.json for Bots

Next, let's take a look at a bot app. You can customize the tasks in the way I showed you for tab apps (such as the prerequisites checks), except there are some differences between tabs and bots.

Let's create a new command bot and see how the tasks are different.

Open the file at .vscode > tasks.json. You can see some tasks are different from the tab app. There are bot-specific tasks including, "Set up bot" and "Start local tunnel":

"tasks": [
  {
    "label": "Start Teams App Locally",
    "dependsOn": [
      "Validate & install prerequisites",
      "Install npm packages",
      "Start local tunnel",
      "Set up bot",
      "Build & upload Teams manifest",
      "Start services"
    ],
    "dependsOrder": "sequence"
  }
...

When you run the debugger, you can see the process in the Output pane, in the same way you saw for the tab app.

Customization can be done in the same manner, so if you want to skip certain tasks, you can comment the lines out.

Next, we are going to take a look at the bot-specific tasks and settings.

🛳 Changing Bot Service Port

Bots use ports to run bot services, where tabs run web services.

Just like the port for tabs you just learned, you can manually change the "PortOccupancy". Let's change the bot service port to something different from the default, 3978:

"args": {
  "prerequisites": [
    ...
  ],
  "portOccupancy": [
    4978, // bot service port. By default it it 3978
    9239 // bot inspector port for Node.js debugger
  ]
}

And you also need to change this in "ngrokArgs" setting, as well as in another file. You can search and replace the port number:

🏔 Using Your Own Local Tunneling Service

By default, the local tunnel is created with a tool called, ngrok, however, you can replace it with something else you prefer.

To make the change, first, comment out the "Start local tunnel" from the tasks' "dependsOn":

"tasks": [
  {
    "label": "Start Teams App Locally",
    "dependsOn": [
      "Validate & install prerequisites",
      "Install npm packages",
      //"Start local tunnel",
      "Set up bot",
      "Build & upload Teams manifest",
      "Start services"
    ],
...

Then, change the "botMessagingEndPoint" to your own tunnel URL at the bot setup task. I want to use my contoso service, so I am using the preferred path:

{
  "label": "Set up bot",
  "type": "teamsfx",
  "command": "debug-set-up-bot",
  "args": {
   "botMessagingEndpoint": "https://contoso.com/api/message"
  }
},

Note: Contoso is a fictional service, in case you are not familiar with this Microsoft's favorite fake company name 😉

Run F5 and see the changes.

I didn't cover every possible task scenarios here, but I hope you found the article helpful for debugging your Teams apps. Please don't hesitate to drop your comments and feedback here.

Mahalo and see you soon 👋

📚 Learn More

📢 Shoutout

Teams Toolkit Engineering team, especially Ji Dong 🌟

Roll A Dice! - Building a Command Bot for Microsoft Teams Using Team Toolkit v4 with VS Code

Tomomi Imura 🐱 — Thu, 20 Oct 2022 20:50:27 +0000

In the previous post, I announced the Teams Toolkit for Visual Studio Code v4 made GA (generally available) status and what's new. And in this tutorial, I will walk you through how to use one of the new features to build a command bot.

We are going to build a dice bot, which returns a random number between 1 and 6, when a user sends a command, "dice".

So let's get started! 🎲

🔧 Setting up

If this is the first time using Teams Toolkit, please go to this tutorial, Using VS Code Teams Toolkit Extension for Teams App Development first, and follow the Prerequisites then, Installing Teams Toolkit section. The tutorial was written for the earlier version of Toolkit, but the initial setup process is the same.

I have created a YouTube video this time, so check it out!

🏗 Scaffolding a Command Bot Template

In Teams Toolkit extension in VS Code, click Create a new Teams app then select the Command bot from the menu. See the screenshot below:

Follow the Teams Toolkit by choosing a language, well, let's choose JavaScript for this tutorial, then, where in your local folder to create the project. Now give the app a name. Let's name it "RollADice".

After you are done, Teams Toolkit will generate the scaffolding for you. Take a look around the code structure and familiarize yourself with the files!

⌨️ Running the Template Code in Teams

Now, let's try running the scaffolded code on Teams client and see how the bot user-experience is like.

From the Run and Debug menu, choose Debug (Edge) (Chrome is fine, if you prefer!), and run by clicking the Start debugging green triangle. Or alternatively, press F5 key on your keyboard.

Teams Toolkit will do some works for you, including checking prerequisites, Azure provision and bot registration, running ngrok to tunnel your local server, etc. You will be asked to sign in to your M365 account if this is your first time. Just follow the Toolkit instructions.

It will take a while, but when it is done, a browser will load Teams client, then ask you to install the bot. So, go ahead and click Add to install your bot:

Once you add the bot, play around and see how it works. Notice that the command suggestions box pops up, like the screenshot below. This is a hint for the users what commands are available for the bot. Try clicking it to send the command to the bot.

🎲 Creating Roll-A-Dice Bot

Now, let's go back to VS Code and modify the code to turn it into a dice bot.

🪄 Defining the Command Suggestion

We are going to edit the suggestions content first, and this is the result of what we are going to do here:

Go to the file, templates > appPackage > manifest.template.json.

This is the file where the suggestions UI content is defined. Find the commands in commandLists in the JSON and change the title and description to:

"commands": [
  {
    "title": "dice",
    "description": "Roll a dice!"
  }
]

and save the file.

💬 Command and Response

Now, go to bot > src > helloWorldCommandHandler.js.

In the HelloWorldCommandHandler class, find the line, where the triggerPatterns is defined and edit the command to "dice":

triggerPatterns = 'dice';

You don't need to worry about the case of the command. Users can type "dice", "Dice", "DICE", "DiCe", and they are all valid commands!

Then, define the bot reply message. In the handleCommandReceived function, let's create a message content with a generate random number:

async handleCommandReceived(context, message) {
  // Generate a random number between 1 and 6
  const result = Math.floor(Math.random() * 6) + 1;

  // Images of dice faces (Using creative commons images from Wikimedia)
  const images = [
  'https://upload.wikimedia.org/wikipedia/commons/thumb/6/62/Kismet-Ace.png/240px-Kismet-Ace.png',
 'https://upload.wikimedia.org/wikipedia/commons/thumb/6/6d/Kismet-Deuce.png/240px-Kismet-Deuce.png',
 'https://upload.wikimedia.org/wikipedia/commons/thumb/f/f2/Kismet-Trey.png/240px-Kismet-Trey.png',
 'https://upload.wikimedia.org/wikipedia/commons/thumb/1/11/Kismet-Four.png/240px-Kismet-Four.png',
 'https://upload.wikimedia.org/wikipedia/commons/thumb/8/8e/Kismet-Five.png/240px-Kismet-Five.png',
 'https://upload.wikimedia.org/wikipedia/commons/thumb/4/4e/Kismet-Six.png/240px-Kismet-Six.png',
    ];

  // Reply message - rendered in an Adaptive Card
    const cardData = {
      title: 'Roll a Dice 🎲',
      body: `You've got ${result}!`,
      thumbnail: images[result - 1],
    };

  return MessageBuilder.attachAdaptiveCard(helloWorldCard, cardData);
  }

🪪 Creating Message UI with Adaptive Cards

Here, I want to display a dice image along with the result in a reply message nicely, so we are going to use Adaptive Cards to customize the message UI layout.

The layout is defined in JSON in the file at bot > src > adaptiveCards > helloworldCommand.json. But let's hold on to it and we'll come back to the file later because we are going to use a visual tool to create the JSON first.

In a browser, go to Adaptive Cards Editor tool section in Developer Portal at dev.teams.microsoft.com/cards, create a new card by clicking Create new card.

Let's use the Thumbnail card template as a starting point. In the preview pane, delete the buttons and text in the template and leave only a thumbnail, title, and subtitle, to create a simple UI.

The edit I made for the tutorial are:

Remove buttons and text from the template
Set the thumbnail layout property for size to "medium"
Double-click the title and change to a variable, "${title}"
Set the title style property for weight to "bolder"
Change the subtitle to "${body}"

But feel free to customize in the way you want!

Now, copy the generated JSON into the helloworldCommand.json.

In the YouTube tutorial, you can follow the instruction at 4:46 and watch me how to use the tool. In the video, I copy & paste the JSON first then modify some content manually, instead of editing all properties in the visual tool. You can do in either way.

🤖 Running the Bot

Let's run the code in Teams client again, using the "F5" tool and see how it works. Once added the bot, try sending the "dice" command.

I hope your bot works as it should 🎲

💡 Hacking it More

Now, you know the basics of command bots for Teams, so I suggest you to tweak the bot further to make it more interesting.

The bot we just created is a 6-faced dice and only replies you with a number between 1 and 6. But it would be more interesting if each user can decide the type of dice, such as, 12 sided dodecahedron, 20 sided icosahedron, chiliagon with 1000 sides, or any n-sided theroritical dice.

So we can make the bot to take a parameter along with the command, such as dice 12 so that the dice bot can return a number between 1 and 12. Or between 1 and 1000 for dice 1000 command.

You can tweak the code to read a parameter like this:

const strs = message.text.split(' ');

const max = strs[1] ? parseInt(strs[1]) : 6;
if (isNaN(max)) {
  return MessageBuilder.attachHeroCard(`Invalid number: ${strs[1]}`);
}
const result = Math.floor(Math.random() * max) + 1;

const cardData = {
  title: `Roll a ${max}-sided dice 🎲`,
  body: `You've got ${result}!`,
};

Don't forget to modify the command suggestion UI content too. I totally encourage you to modify the code more and add features to create your own dice bot!

Or Use your imagination to build something else, like weather bot, cryptocurrency bot, dad joke bot... The ideas are endless.

If you build some interesting bots, please let me know! Mahalo, and see you in the next blog post 🤙

📖 Learn More

📺 YouTube: Roll A Dice! - Building a Command Bot for Microsoft Teams Using Team Toolkit v4 with VS Code 🎲
📄 Docs: Teams Toolkit Overview
📄 Docs: Developer Portal for Teams - Overview

Microsoft Teams Toolkit for VS Code is now GA 🎉

Tomomi Imura 🐱 — Tue, 24 May 2022 18:04:35 +0000

Previously, I introduced Teams Toolkit Preview in a series of blog posts. And I am happy to announce that Teams Toolkit for Visual Studio Code and the Teams Toolkit CLI are generally available as of today! And for everyone building .NET web apps, Teams Toolkit for Visual Studio is available now in preview. I hope you caught the announcement at Microsoft Build 2022 too.

There have been a lot of updates and improvement since the preview versions, however, in this post, I'd like to highlight some of the key new features with Teams Toolkit for VS Code that probably excite you the most!

🎞 Introducing Scenario-based Teams Apps

Before this release, Teams Toolkit Preview has provided app template code based on the Teams capabilities, such as Tabs, Bots, and Messaging Extensions.

However, in the reality, we design products based on the real-life scenarios.

So, with this GA release, we have added the scenario-based Teams app template, along with the existing basic capabilities templates.

Here are the newly added features—

🤖 Bot Notifications

Sending bot notification can be a common scenario for a chat bot applications and for Teams app too. However, the development process for Teams apps has been cumbersome... Well, we made the process simpler as Toolkit now can help you create the notification feature for your app by tweaking the generated code!

When you are first setting up a new app in Teams Toolkit, click Notification bot under Scenario-based Teams app. to let Toolkit generate the scaffolding to create a bot that sends notifications.

You can specify the event for that message—a trigger or a timer. If you want your bot to send Teams periodical reminder of something, choose the Timer Trigger.

If you are using JavaScript, take a look at the file, source/adaptiveCards/notification-default.json and see where specifies the message structure in JSON. You can keep the message just with some simple text, or with a list, table, buttons, etc.

You can also live-preview how the JSON is displayed as the Adaptive Card too. Just click where it says Preview and Debug Adaptive Cards to preview, or get the VS Code extension.

And in src/timerTrigger.js (for Timer-based notifications), you can see how the message to be sent is applied to the Adaptive Card. Try changing the strings and see how it works on Teams client!

for (const target of await bot.notification.installations()) {
    await target.sendAdaptiveCard(
      AdaptiveCards.declare(notificationTemplate).render({
        title: 'Aloha! This is your daily reminder.',
        appName: 'Contoso Bot',
        description: `This is a sample time-triggered notification (${timeStamp}).`,
        notificationUrl: 'https://www.adaptivecards.io/',
      })
    );
  }

Once you run the bot with the F5 debugger, the bot sends you a notification in your scheduled time.

There are more you can do with bots—

💬 Command Bot

Another common scenario would be a bot that respond to a command. You might think about some conversational bot but for most cases, all you need is a simple bot that answers your commands, like what you may have used "slash commands" in some services.

Now with the Toolkit, you can start creating a command bot easier than ever.

After clicking Create a new Teams app in Teams Toolkit, select the Command bot from the menu and proceed the rest.

Once the template code is generated, see the commandHandler function. For example, if you chose JavaScript, the file, bot/src/helloWorldCommandHandler.js you see the trigger word and response message.

You can alter the handler (or create a new handler) to create your command:

class HelloWorldCommandHandler {
  triggerPatterns = 'Hi kitty';

  async handleCommandReceived(context, message) {
 // render your adaptive card for reply message
    const cardData = {
      title: 'MeowBot 🐱 says',
      body: 'Meow meow meow',
      image: 'https://placekitten.com/500/400',
      imageAlt: 'cat'
    };
    return MessageBuilder.attachAdaptiveCard(helloWorldCard, cardData);
  }
}

And define the response message UI with the Adaptive Cards previewer in bot/src/adaptiveCards/helloworldCommand.json.

Now, when a user send a "Hi kitty" message to the bot, the bot will respond.

📬 Expand Your Apps to Outlook and Office

Another exciting news is that now your Teams apps can run on Outlook and Office!

When you create a new app, the previous version of Toolkit only allowed you to choose one of the capabilities, however, with the new Toolkit, now you have more choices.

To create an app that runs on other M365 products, like Outlook and Office, choose one from the Extended Teams app across Microsoft 365, which will generate a scaffolding code with helpful code template and samples, either in JavaScript or TypeScript (which, you can choose one!).

The "F5" debug feature is your friend when you are testing out your code in VS Code, and now the debug profile in Teams Toolkit includes Outlook and Office, where you can simply select one and see your app running!

📢 More Updates for Teams Development

There are more updates with Teams and M365 app developments.

📜 Teams SDK v2 & Updated Manifest

Teams client SDK has been around for you to create tabs and task modules, and come with functionalities like tab configurations and theme detection, as well as authentication. Now it is upgraded to v2, and the latest version comes with functionalities to extend Teams app to run in Outlook and Office.

The new Teams Toolkit utility also allows you to upgrade your existing apps that uses Teams-js SDK v1 to use the SDK v2, which updates imports & API calls.

Toolkit also revises a Teams manifest to the latest schema to support Office and Outlook.

🖼 Fluent UI Component Library for Tabs App

When creating a tab app (which is a web embed in Teams), you would want the UI for your app to look and feel like Teams.
The Teams UI Component Library is here to help with that.

Teams UI Component Library is a UI library built on top of Fluent UI React.
Fluent is Microsoft’s design system that provides you with a set of UI libraries for all M365.

And the base components library, Fluent UI React is now upgraded to v9, which supports design tokens and has major performance improvements 🎉

I hope you found the article makes you get started with your Teams app development with Teams Toolkit, especially if you are new to Teams app development!

Please don't hesitate to drop your comments and feedback here.

See you again at the next post 👋

📚 Learn More

📢 Shoutout

A big hurrah to Teams Toolkit Engineering team, and thank you, Yu Zhang, Zhidi Shang, John Miller, Zhenya Savchenko, and Pierce Boggan, for helping me writing this article ❤️

Debugging Teams App Locally with Teams Toolkit

Tomomi Imura 🐱 — Fri, 04 Mar 2022 06:20:43 +0000

In the previous post, I introduced some of the new features in Teams Toolkit v3 to empower enterprise Teams developers.

In this article, I will show you the improved local debug experience in Toolkit and new features introduced in version 3.4.

First of all, you need to install Teams Toolkit extension in Visual Studio Code, or update it to the latest version if you already have it. And if this is the first time interacting with Teams Toolkit, I recommend to go through the step-by-step tutorial, Get started with JavaScript on Microsoft Teams developer platform documentation first.

⌨ Debugging with "F5"

Debugging, casually referred to as F5 (function key) among developers, is one of the key features of Visual Studio Code, and this built-in debugger helps accelerate your edit, compile, and debug loop.

Teams Toolkit uses the VS Code feature to let you run your app in Teams client and debug it during the development.

To enable local debugging in Teams Toolkit, first, make sure you are logged in with your M365 account under the Accounts section in Toolkit. Then:

On VS Code, go to the Run and Debug view in the Activity Bar
Select either Debug (Chrome) or Debug (Edge) from the dropdown menu on the debug button and click the ▶️ (Start) icon

Alternatively, you can just press F5 function key on your keyboard.

Toolkit will launch Teams client in a new Chrome or Edge browser, where you can add your app.

⚠️ If this is the first time with Teams Toolkit, you will be prompted to confirm to add an SSL certificate. Please agree to continue.
Since Teams requires https Tab hosting endpoint, a localhost development certificate will be automatically generated and installed to your system after your confirmation.

📍 Using Breakpoints

Breakpoints in VS Code is available in Toolkit too to debug your code for tab, bot, message extension, and Azure Functions. You can toggle the breakpoints while your app is running on Teams client on browser.

Click the left margin next to the line you wish to stop so the breakpoint will appear as a red dot 🔴. Then run the code (F5).

Your code will pause before the marked execution.

Once a debug session starts, the Debug toolbar will appear on the top of the editor:

Continue / Pause F5
Step Over F10
Step Into F11
Step Out ⇧F11
Restart ⇧⌘F5
Stop ⇧F5
Multi-target debug

The last action in a dropdown menu is for selecting a multi-target debugging. In Teams Toolkit, selecting "Attach to Frontend" (for tabs) or "Attach to Bot" (for bots and messaging extension) will trigger a Node.js debugger, as well as Edge or Chrome debugger to launch a new browser instance and open a web page to load Teams client. "Attach to Backend" will start a Node.js debugger to attach to the Azure functions source code.

Also note that Hot reload is enabled in Toolkit so you can just update your code and save the changes, then your app will automatically reload and re-attach the debugger.

To end the debugging, disconnect in the floating toolbar. Once the session is terminated, it is safe to run again.

🐞 What's New with Local Debug Experience in Toolkit v3.4?

There are a few new features that have been added in the latest Toolkit to improve your local debugging experience.

✅ Prerequisite Checker

In case you wonder, when you press the F5 key, the Teams Toolkit does:

Register your app with Azure Active Directory
Start app services for both backend and frontend
Start Microsoft Teams in a web browser with a command to instruct Teams to sideload the app from localhost
Create an app manifest and register the app in Teams Developer Portal

These processes require specific versions of Node.js, packages, various tools, also M365 credentials.

Now in Toolkit v3.4, it checks all the requirements and lists up and displays in Output channel:

This gives you more transparency and clear ideas about what is going on and easier to figure out when something goes wrong.

⚙️ Customizing Local Debug Settings

Another new feature is that now Toolkit allows you to customize the debug settings. This gives you control over your debugging experience.

Skipping Prerequisites

You can skip some of the prerequisites in VS Code Settings:

Go to Settings
Find Extensions in the list and expand it
Find Teams Toolkit (Preview) and click Prerequisite Check

Now you have the checkboxes so you can uncheck the items you would like to skip.

Using Your Own Bot Endpoint

Teams Toolkit uses the 3rd party tool called, ngrok to tunnels your localhost to the internet to run bots. If you wish to use your own bot endpoint,

At Prerequisites Check in VS Code Settings, uncheck "Ensure Ngrok is installed and started. (ngrok)"
Set botDomain and botEndpoint configuration in .fx/configs/localSettings.json to your own domain and endpoint

Using Your Own Development Certificate

Similarly, you can use your own development certificate,

At Prerequisites Check in VS Code Settings, uncheck "Ensure development certificate is trusted. (devCert)".
Set sslCertFile and sslKeyFile configuration in .fx/configs/localSettings.json to your own certificate file path and key file path.

You can learn more about the certificate in TeamsFx documentation on GitHub.

🔧 Manual Customizations

You can also customize your local debug settings manually with editing configuration files.

Using Your Own Start Scripts

For tab:

Update dev:teamsfx script in tabs/package.json.

For bot or messaging extension:

Update dev:teamsfx script in bot/package.json.

For Azure functions:

Update dev:teamsfx script in api/package.json. In addition for TypeScript, update watch:teamsfx script.

⚠️ The ports required by tab app, bot app, messaging extension app and Azure functions are not supported to be customized currently

Adding Environmental Variables

You can add environment variables to .env.teamsfx.local file for tab, bot, messaging extension and Azure functions.

Teams Toolkit will load the environment variables you added to start services during local debug.

⚠️ The environment variables are not supported to hot reload. You need to start a new local debug after adding new environment variables.

Debugging Partial Component

Teams Toolkit utilizes VS Code multi-target debugging to debug tab, bot, messaging extension and Azure functions at the same time.

You can updates .vscode/launch.json and .vscode/tasks.json to debug partial component. Let's say, you want to debug tab only in an app with tab and bot capabilities with Azure functions project, you can take the following steps:

Comment out these lines in .vscode/launch.json:

{ 
  "name": "Debug (Edge)", 
  "configurations": [ 
    "Attach to Frontend (Edge)", 
    // "Attach to Bot", 
    // "Attach to Backend" 
  ], 
  ...

Comment out these lines in .vscode/tasks.json:

{ 
  "label": "Start All", 
  "dependsOn": [ 
    "Start Frontend", 
    // "Start Backend", 
    // "Start Bot" 
  ] 
},

I hope you found the article helpful for debugging your Teams apps and the new features give you more confidence debugging your Teams app development!

Please don't hesitate to drop your comments and feedback here.

See you until the next post 👋

📚 Learn More

📢 Shoutout

Teams Toolkit Engineering team, especially Kuojian Lu and Yu Zhang ❤️

Developing Enterprise-Ready Microsoft Teams Apps with Teams Toolkit v3.0

Tomomi Imura 🐱 — Wed, 01 Dec 2021 21:54:04 +0000

In the earlier posts, I introduced Teams Toolkit v2 Developer Preview extension for Visual Studio Code that generates scaffolding for you to help you get started with Microsoft Teams apps, also, introduced TeamsFx, the core library that lets you handle things like authorization and making Graph API calls.

Since then, the tool has evolved with more powerful features and better user-experience. Thereby, in this article, I would like to introduce new features in the Toolkit v3.0, especially to empower enterprise Teams developers 🚀

Quick Intro—What are Teams Toolkit & TeamsFx CLI?

Teams Toolkit is a collection of development tools that helps you to create and deploy Microsoft Teams apps with integrated identity, access to cloud storage, data from Microsoft Graph, and other services in Azure and Microsoft 365.

There are a visual interface tool and a command line interface—With Teams Toolkit extension for Visual Studio, you can take advantage of the familiar VS Code visual interface for Teams app development. Teams Toolkit comes with a Command-line tool, called TeamsFx CLI, which lets you run tasks with keyboard-centric experience, as well as enabling CI/CD scenarios.

Now, let's take a look at what the new features these tools offer! And if you are looking to learn how to get started with Teams Toolkit and the requirement to start developing Teams apps in general, I'd recommend reading Get started documentation on Microsoft Teams developer platform docs first.

☁️ Multi-Env Management

You typically start developing in your local environment, but sooner or later, you will need to manage multiple environments as you go. Besides your local env, you probably end up having multiple environments, such as, dev, qa, stage, and the production environment, prod to deploy.

Teams Toolkit provides a simple way for you to create and manage multiple environments. When you created a new project with Teams Toolkit, it generates local for your local machine configurations, and dev, to represent a remote environment configurations by default.

Now, with this new Toolkit, you can enable more remote environment 🎉

To add an extra environment:

Open a project in Teams Toolkit, and find Environment on the left pane
Click the Create new environment button (a little "Plus sign" button)

3.Give a name to the new environment and press Enter key

To add more environments, select an existing environment to add a new one. Every time you create an extra environment, the configuration file (config.<your_new_env>.json and azure.parameters.<your_new_env>.json) will be copied from an existing one.

For more info, please read Manage multiple environments in Teams Toolkit.

🤝 Collaboration Among Multiple Developers

Have you wished it was easier to collaborate on a Teams app project with your coworkers? Well, I have good news! This much-anticipated feature to manage multiple environments was introduced in the latest version of Teams Toolkit, and it supports project collaborations among multiple developers.

Previously, you needed to manually handle the permissions for Teams and Azure AD. But from now on, the Toolkit handles this for you.

To add a collaborator:

First, make sure you have logged in to both M365 and Azure accounts from the menu under Account in Teams Toolkit

2.Under Development , click Provision in the cloud
3.Then choose an environment (if you have multiple working environments).

You may see some popup notifications. Follow the instructions. This will create necessary cloud resources.

4.Once the provision process is completed, now you see the Collaborators list is available under Environment. Click the little Add M365 Teams App (with AAD App) Owners icon

5.Then enter an email address of the person who you want to invite

6.To view collaborators in the environment, select List M365 Teams App (with AAD App) Owners button, then collaborators will be listed in the output channel

Once the collaborator joins, they can develop, provision and deploy the project. You can push the project to GitHub, so that your collaborators can clone the repository and work on the project remotely by signing in on their own M365 and Azure account credentials!

💪 Provision Azure Resources Using ARM and Bicep

One of the last major upgrades of Teams Toolkit (v2) was the features that let you provision Azure resources using infrastructure-as-a-code approach and deploy your apps to Azure.

Now with this new Teams Toolkit v3, you can declaratively provision to author ARM (Azure Resource Manager) template, which is a set of Bicep files that defines the infrastructure and configuration for your project.

Bicep is a domain-specific language (DSL) that uses declarative syntax to deploy Azure resources. The advantage of using Bicep instead of JSON is that Bicep is verbose and uses simpler syntax to develop your ARM templates.

To provision with ARM, you can customize Azure resources by changing these two sets of files:

Azure parameters

└ 📁 .fx/configs
  ├ 📄 `azure.parameters.{your_env_name}.json`
  ├ 📄 `azure.parameters.{your_env2_name}.json`
  ├ ...

ARM Templates (Bicep files)

└ 📁 templates/azure
  ├ 📄 main.bicep
  ├ 📄 provision.bicep
  ├ 📄 config.bicep
└ 📁 provision
  ├ 📄 {each_Azure_resource}.bicep
  ├ ...

There are predefined parameters and templates. To learn what exactly you can customize and how, please read Customize resource provision section in the documentation.

🥽 CI/ CD Support

In your real-life development process, your team is highly likely to rely on a CI/CD platform to automate your builds, testing, and deployment.

Now with Toolkit v3, you can enable CI/CD workflows to automate Teams app development process for multiple environments scenario.

The Toolkit bundles with TeamsFx CLI that comes with various useful commands for your Teams app development, including the integration for the automated CI/CD workflows.

We prepared sample configuration files, including GitHub, Jenkins, Azure DevOps, and other platforms by scripts (Grab templates of your choice!), as well as GitHub Actions template, which I will show you how—

Setting Up GitHub Actions

For example, if you would like to set up CI/CD flow with GitHub Actions with TeamsFx from the web interface:

On your project repo on GitHub.com, click Actions tab
Click set up a workflow yourself
Copy the sample file for Continuous Integrations (CI)
Paste it in the editor
Customize the workflow to fit your scenarios
Click Start commit button to commit the file
Repeat the process with the sample file for Continuous Deployment (CD)
Fill out your M365 and Azure credentials in the CD config file, under the env section
Commit the file

See how to set up GitHub Actions in this GIF:

These files are now stored under .github/workflows.

If you run into a problem with your M365 account permission, please disable the multi-factor authentication from Microsoft 365 admin center. You should be able to change the setting at Users > Active users > Multi-factor authentication.

Also, for Azure account, the account's security defaults should be turned off at Azure Portal, at Azure Active Directory > Properties > Manage security defaults.

Setting Up CI/CD Pipelines with Something Else

If you would like to set up your workflow with other platforms, such as Azure DevOps and Jenkins, please refer to the docs at CI or CD support for Teams application developers.

I hope these new features give more confidence to your Teams app development workflow and we are looking forward to seeing your amazing apps on production! And please don't hesitate to drop your comments and feedback here.

📚 Learn More

Fetching Teams User Info from Microsoft Graph with TeamsFx SDK

Tomomi Imura 🐱 — Thu, 29 Jul 2021 21:26:21 +0000

😘 TL;DR

First of all, this tutorial became far longer than I initially intended, so I decided to include this quick summary of the article:

There are various tools and SDKs for Teams app development so you need to pick the right & preferred tools!
TeamsFx is a great tool when you build app that uses Microsoft Graph API for fetching data, such as basic user info
TeamsFx handles the OAuth 2.0 authorization code grant flow, getting an access token, and use the token to make Graph API calls
Use the Graph wrapper, client.api(path).get to make the call

Now, proceed to the main content!

In my previous tutorial, I showed you how to use a VS Code extension, Teams Toolkit to start building a Teams bot. In this tutorial, I walk you through the sample bot app from Toolkit and introduce you Microsoft Graph and TeamsFx. But before getting into the code, let me quickly explain about development tools.

🔧 Teams Development Tools

In my other Microsoft Teams-related tutorials, I mentioned Teams SDK to build Tabs core user interface, Bot Framework to build bots and messaging extensions, Adaptive Cards for UI components in messages, and Teams Toolkit VSCode extension for quick scaffolding all types of Teams apps.

Some of the tools are not only created for Teams development, but for multiple Microsoft products. Here's a quick table of available tools for Teams:

Product	What it is	What it does for Teams app development	What else it is used for
Teams SDK (Teams.js)	Teams Client SDK	Tabs development (Front-end)	(Teams-specific)
Bot Framework	Bot SDK	Teams bots development	Web & mobile chat, Skype, Facebook, Amazon Alexa, Slack, Twilio, etc.
Adaptive Cards	Platform-agnostic UI snippets (JSON)	Rich-format messages & cards	Web & mobile UI, Outlook messages, etc.
App Studio	Visual tool	Create & configure Teams app packages	(Teams-specific)
Teams Toolkit	VS Code Extension	Register & configure app. App scaffold	(Teams-specific)
TeamsFx	SDK & CLI	Implement identity and access to Graph resources	(Teams-specific)
Microsoft Graph	REST API	Provides access to data stored across Microsoft 365 services, including Teams	Access & manage calendar, mail, oneDrive, etc.
Developer Portal for Microsoft Teams (Preview)	Web tool	Configurations & references	(Teams-specific)

There are more tools you can use for Teams, but I am not covering everything in this tutorial!

Usually during development, you would use a combination of some of them. For example, in this tutorial we are going to use Teams Toolkit, Bot Framework (that includes wrapper methods for Adaptive Cards), and TeamsFx (that includes Graph API wrappers).

Now, let's start off where we left off in the previous tutorial, Using VS Code Teams Toolkit Extension for Teams App Development.

🤖 Using Microsoft Bot Framework

After you build and run the template code from the Toolkit, let's take a look at bot directory, where the bot code is stored.

Now, let's walk through the template code together quickly—

📄 bot/index.js

In index.js, notice botbuilder (Microsoft Bot Framework) is imported.

This is where the adapter is created so that it allows your bot to communicate with the user and send responses.



const { BotFrameworkAdapter, ConversationState, MemoryStorage, UserState } = require("botbuilder");
...
const adapter = new BotFrameworkAdapter({
  appId: process.env.BOT_ID,
  appPassword: process.env.BOT_PASSWORD,
});

Teams Toolkit already has handled registering your bot to Azure Active Directory so you don't need to manually configure your Bot ID and password 🙌

Also, Restify is set up to HTTP server and routing HTTP requests.



const server = restify.createServer();
server.listen(process.env.port);

// Listen for incoming requests.
server.post("/api/messages", async (req, res) => {
  await adapter.processActivity(req, res, async (context) => {
    await bot.run(context);
  })...
});

To simplify the tutorial, I am not explaining how to manage states, and what turn means. If you would like to learn the concept of bot, read How bot works.

📄 bot/teamsBot.js

The bot/teamsBot.js is the main entry point for the bot.

The TeamsBot class is being created here. Its run function is called by the adapter and routed to bot's activity logic through Restify middleware (from index.js).

In the constructor, it overrides some of the TeamsActivityHandler methods by extending it to customize bot behavior and message text.



class TeamsBot extends TeamsActivityHandler {
  ...
  constructor(conversationState, userState, dialog) {
    super();
    ...

    this.onMessage(async (context, next) => {
      ...
    });

    this.onMembersAdded(async (context, next) => {
      ...
    });

  }
}

For example, methods overridden are onMessage and onMembersAdded in this sample. They register the event handlers for the message event, emitted for every incoming message activity, and MembersAdded event emitted when a new member is added to the conversation, respectively.

Message event

When a message is sent to bot from a user (like, show command), onMessage gets triggered.



this.onMessage(async (context, next) => {
  await this.dialog.run(context, this.dialogState);
  await next();
});

Then, it runs the Dialog with the new message Activity.

📄 bot/dialogs/mainDialogs.js



const { Dialog, DialogSet, DialogTurnStatus, WaterfallDialog } = require("botbuilder-dialogs");

The dialogs library 💬 provides a state-based model to manage a long-running conversation with the user. A dialog performs a task that can represent conversational thread.

Okay, this was a quick walk-through of what some of the code does. Now, let's get to the main topic, TeamsFx and Graph.

🪅 What is TeamsFx?

TeamsFx is a framework, created to make the integrations of Microsoft Graph API and implementing identity and access with Teams easier. For example, it handles the OAuth 2.0 authorization code grant flow, getting an access token, and use the token to make Graph API calls.

Microsoft Graph API

So what is Microsoft Graph API, first of all? It is a REST API lets you to connect the data from Microsoft 365 services.

M365 platform holds various people-centric data and insights across the Microsoft cloud services, including Teams, Outlook, Calendars, etc. It means whenever you want to access to the data within your Teams app, you need to use Graph to access the data.

For example, in this sample app, when a user asks a bot to display the user's info with the show command, the app make an API call to fetch the data from Graph.

🪅 Using TeamsFx to call Graph API

In bot/dialogs/mainDialogs.js, both TeamsFx and Graph libraries are imported:



const {createMicrosoftGraphClient, loadConfiguration, OnBehalfOfUserCredential, TeamsBotSsoPrompt} = require("@microsoft/teamsfx");
const { ResponseType } = require("@microsoft/microsoft-graph-client");

🔏 User Authentication & Authorization

The app creates and authenticates a MicrosoftGraphClient by calling loadConfiguration().

Then, a new instance of TeamsBotSsoPrompt is added as a named dialog. TeamsBotSsoPrompt is integrated with Bot Framework to simplify the authentication process for bots:



loadConfiguration();
dialogs.add(
  new TeamsBotSsoPrompt("TeamsBotSsoPrompt", {
    scopes: ["User.Read"],
  })
);

The scopes are the types of permission it requires to call Graph APIs for Teams. The resource-specific permissions are granular and define what an application can do within a specific resource.

There are various permission scopes that can read or write (create, edit, delete). For instance, User.Read is the scope needed to read users info, as the name suggests. And to enable the permissions, the app must ask the user for their consent.

This operation creates a new prompt that leverages Teams Single Sign On (SSO) support for bot to automatically sign in user to receive OAuth token 🏅.

Authentication and authorization are big topics here. I would need another tutorial to explain deeply about Microsoft identity platform. In the meantime, please read Authentication and authorization basics for Microsoft Graph.

📇 Calling Graph API

In the app, when a user sends the "show" command to the bot, the app calls an API from Graph to fetch the user info. (The app asks the user a permission by popping up a SSO window before fetching the user's info, as explained in the previous section.)

Every API call requires the access token 🏅 that has been acquired at the SSO sign-in process. (The token is attached in the Authorization header of the request).

Also, to access the Microsoft Graph API for Teams, you will need the Teams credentials to do authentication to create a Graph client object.

3 credential classes that are used to help simplifying authentication in TeamsFx:

TeamsUserCredential - Teams current user's identity. Using this credential will request user consent at the first time.
M365TenantCredential - Microsoft 365 tenant identity. It is usually used when user is not involved like time-triggered automation job.
OnBehalfOfUserCredential - on-behalf-of flow. It needs an access token and you can get a new token for different scope.

For bot scenarios, we are using OnBehalfOfUserCredential here:



const oboCredential = new OnBehalfOfUserCredential(tokenResponse.ssoToken);
const graphClient = createMicrosoftGraphClient(oboCredential, ["User.Read"]);

Now, you have authentication setup and an instance of Graph client, you can finally begin to make calls to the service!

This is how you can fetch the basic user information, then making the bot to send a message to Teams client:



const me = await graphClient.api("/me").get();

if (me) {
  await stepContext.context.sendActivity(
  `You're logged in as ${me.displayName} and your job title is: ${me.jobTitle}`
  );
 ...

Now this is the simplified flow of what you have just learned:

Build and run on Teams client if you haven't. Try the show command to ask the bot to display your info.
When everything goes well, this is how it looks like:

Ta-da 🎉

🧺 More with Graph

Try making more Graph calls with the api method. All requests start with client.api(path) and end with an action, get or post:

To get the Teams group the user have joined:



const profile = await graphClient.api("me/joinedTeams").get();

The response gives you a list of groups including the group IDs.

To get the members of a Teams group:



const profile = await graphClient.api("groups/{Teams group ID}/members").get;

Also, try Graph Explorer to test out the REST API and visualize the response!

I hope you enjoyed the tutorial. There are many things you would want to know, such as concepts of bots, OAuth, identity management, etc. but I tried not to make this tutorial too wordy by flooding with info, so I simplified everything by not diving deep into the details on purpose. But hopefully, this tutorial still made sense to you!

If you would like to dive deep, please check out the docs and code repos listed below!

📚 Learn More

Microsoft Bot Frameworks
Bot Services Documentation - How bot works?
TeamsFx SDK references
TeamsFx GitHub repo
Microsoft Graph API
Authentication and authorization basics for Microsoft Graph

Using VS Code Teams Toolkit Extension for Teams App Development

Tomomi Imura 🐱 — Wed, 21 Jul 2021 22:12:08 +0000

In my previous posts related to the Microsoft Teams developer platform, I introduced a few of Teams app types and how to build your first tabs, bots, and message extensions. These tutorials instructed you to use App Studio for manual configurations and minimal local setup, to focus on familiarizing you with the concept of Teams app features.

However, in this tutorial, I am showing another way to develop, using a newly introduced developer tool, called Teams Toolkit (Preview) for VS Code, which was created to help you build and deploy Teams apps with integrated identity, access to cloud storage, data from Microsoft Graph, and other services in Azure and M365.

Before you begin, let's check if you have set up your working environment to develop on Teams.

📓 Prerequisites

First, make sure if your Teams client allows you to "sideload" custom apps. Check Enable custom Teams apps and turn on custom app uploading before you begin.

Or you can sign up for Microsoft 365 developer program, a free, renewable subscription that comes with a developer tenant sandbox and sample data pack, like mock user data!

And if you haven't using it already, get the latest version of Visual Studio Code. (Earlier versions might not work with the toolkit.)

🖥 Installing Teams Toolkit

Launch VS Code and now install an extension that helps you develop Teams apps.

Select Extensions icon on the left Activity Bar and install the Microsoft Teams Toolkit. If you see two different versions of Teams, Toolkit, make sure to select the "Preview" version 2.x for this tutorial:

🔧 Optional Tools

The following tools will be installed by the Teams Toolkit extension as you need. However, if using Linux (including WSL), you need to install these tools before using:

🧰 Creating New Project with Toolkit

Select Microsoft Teams icon on the left Activity Bar and click Create New Project. At the popup, select Create a new Teams app :

In the Select capabilities section, select one. For this tutorial (and for the next tutorial), let's pick Bot, and deselect Tab and select OK.

In the Bot registration section, select Create a new bot registration:

In the Programming Language section, select JavaScript:

Select a workspace. A new folder will be created within your workspace for the project:

Enter some name for your app. Press Enter to continue:

It will take some time to set it up for you.

In this setup process, the toolkit is preparing these for you:

registering an Azure Active Directory Application within the M365 tenant
creating an app manifest
running API locally using Azure Functions Core Tools to support your app
installing and setting up ngrok, to securely tunnel from your localhost to the Teams client

🤖 Running a Sample Bot Locally

Once your project is set up, take a look around and see how the template app looks like:

But for now, let's just build this sample app and run it locally.

Press F5 key to enable the debug mode.

Alternatively, click the debug icon from the side menu:

This can take up a few minutes to complete as all dependencies are downloaded and the app is built for the first time.

Once it is done, Teams web client will be automatically opened in a browser window. Install it locally by clicking Add:

Once the app is installed, try the bot by typing a command or pick from the menu:

🔏 Granting User Permissions

When you try show command, you should notice the app asks your permission to display your information like this:

and once you hit Continue, it will open an authorization screen:

So, it means that your app (and any 3rd party apps!) just cannot automatically grab a user's information without the user's consent!

In next tutorial, I will explain about Microsoft Graph to access user information and how you can implement it for Teams, so stay tuned 👋

Support Web Monetization and HODL! — How to receive micropayment in $BTC (or $Ɖoge) on your website

Tomomi Imura 🐱 — Sun, 21 Feb 2021 23:38:34 +0000

👋 You may think this a clickbait. But no, this post really is about web platform!

As I am writing this on Feb 20, 2021, Bitcoin (CRYPTO:BTC) has hit a $1 trillion market cap. Investors who thought it was a joke have started jumped into the cryptocurrency frenzy.

Although the ideas of decentralized market and blockchain are fascinating, I didn’t think the value of BTC would increase much, so I have spent them on things like yoga pants and flights to Europe. I try not to think about how much worth it in today's rate. There are just too many what-if scenarios in my life. (BTW, the economy-class ticket I got was about 1.3 BTC. I let you figure it out.)

Now friends are asking me about advice on cryptocurrency and Coinbase referrals, however, because I can be the worst financial advisor to ruin your life, I am not going to tell you how to invest, or even how to mine in this article, instead, I am going to tell you about Web Monetization and how to receive micropayments in $BTC and other currencies including various cryptocurrencies, like $DOGE if you want, through your website.

I may sound like I am selling you snake oil, but I just thought this may be a good opportunity to talk about the web standard topic.

Web Monetization & Interledger

According to the draft submitted to W3C, Web Monetization is an API that allows websites to request small payments from users facilitated by the browser and the user's Web Monetization provider.

In a nutshell, Web Monetization is an open web API, consists of HTML, JavaScript API, and uses the Interledger protocol, an open protocol for moving money and enabling payments.

Implementing Web Monetization

Although implementation for browsers is straight-forward, it requires some prerequisits as currently, you need (1) a Web Monetization service provider and (2) an Interledger Protocol-enabled wallet to monetize on web.

The services I personally use to implement Web Monetization are:

Coil - Web Monetization service provider
Uphold - ILP-enabled wallet

How Coil works is that is checks if the website is web monetized, and if it does, stream the payment to the site. A small amount is paid by Coil members, who pay a flat fee to access exclusive content and ad-free experiences. Coil provides browser extensions for browsers including Chrome, Edge, and Firefox, while Puma browser is natively powered on Coil and supports Web Monetization API out of the box.

And Uphold is a digital wallet that allows you to receive payments with an Interledger payment pointer. This is where you can receive the payment also sell, buy, and trade.

Setting up Your Wallet

Coil supports multiple wallets, but I am using Uphold to generate your Interledger payment pointer here.

First, open an Uphold account.

Once you signed up and all, you are going to generate an ILP address (Interledger payment pointer).

Go to Transact, then from the Anything to Anything (Right pane), select From dropdown menu:

Select Interledger:

Then pick a currency of your choice— USD, BTC, ETH, XRP, DOGE… there are 27 fiat currencies and
34 Cryptocurrencies to choose from:

![Screenshot - Uphold 3]!(https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6c7z5t7bp02j871sc0gc.png)

Copy the address that looks like $ilp.uphold.com/SoMethIngLiKEthis0:

You will need the address in Coil (the next step) and in your HTML code later.

Setting up Coil

There are two membership types— Coil membership to support web-monetized content and creator membership for monetization. I am walking you through the latter.

First, sign up for a Coil creator account and click Start monetizing. It's free button.

Once you created your account (and verified your email etc.), you will need to set up your payout wallet.

Go to Payout, click Setup under Uphold (unless you chose Gatehub as your wallet):

and enter the ILP address that you generated at Uphold and save:

Next, you are going to include a meta tag with the information on your website to finalize.

Monetizing Your Web

If you already have some website or web apps, you are ready to monetize. All you need is to include the <meta> in your head of HTML:

<html>
 <head>
   <title>Welcome to My Homepage</title>
   <meta
     name="monetization"
     content="$ilp.uphold.com/6NxbkHNq9N84">
 </head>
</html>

Make sure to use your own ILP address as the meta content, unless you want me to receive all of your payment. Then, deploy your web and you are ready to monetize 💰

Monetizing Your Content Here on Dev.to

Even if you don’t have your own websites, some content platforms do support Web Monetization. Take a look at the list of providers.

If you are a writer here on Dev.to too, you can include your ILP address to monetize your content there too.

That’s it.
Now all you need is to wait to get paid in BTC (or whatever you picked) and HODL ;-)

I hope you enjoyed the article. Web platform to the moon 🚀🌕

Beginners Guide to MS Teams Development #3 Messaging Action

Tomomi Imura 🐱 — Tue, 03 Nov 2020 22:56:33 +0000

Hello, I hope you enjoyed the previous two tutorials on how to get started with Microsoft Teams development, (Developing Tabs on Teams and Bots

This is the third one of the beginner series, and this time, I will walk you through how to invoke an action from a message.

There are many different paths to learn how to build Teams apps, and this tutorial uses a bare-minimum code and minimal toolsets. Also, this tutorial is independent of the hosting environment, so I am not starting the process with the Azure setup, and basically, this should run on any environment, as long as you can run a browser.

In this tutorial, I am introducing another Teams platform feature, Messaging Extensions. This feature comes with two different types, Action and Search, and it depends on how it interact with the UI elements and flows.

In this tutorial, I am showing how to built an Action command.

Teams features: Messaging Extensions - Action Command

Action commands allow you to present your users with a modal popup to collect or display information. When they submit the form, your web service can respond by inserting a message into the conversation directly, or by inserting a message into the compose message area and allowing the user to submit the message.

Building a Morse Code message action

The app we are going to build invokes an action from a user message, extract the text, and convert it to a Morse code!

How the app works is:

A user hovers a message to open the message menu, and choose the Morse Bot from the menu
When the user action is trigered, a payload is sent to your messaging endpoint (/api/messages)
This invokes the fetchTask - the message text data is extracted
A popup dialog is displayed. The user can edit the text content if they want, then submit
The app translate the text into a morde code, and display the content as a reply
The user can send the result to the client

This is how the result would look like:

📓 Prerequisites

To be able to install apps to Teams, your organization's admin needs to grant permission.

Otherwise, you can sign up for Microsoft 365 developer program, a free, renewable subscription that comes with a developer tenant sandbox and sample data pack, like mock user data!

Permission to develop on Teams or developer tenant (Sign up for M365 developer program!)
App Studio - look for the app from the Apps menu in Teams client and install to your workspace
Experience with Node.js and basic understanding of Express.js

👾 Technology to be used in this tutorial

Node.js
Microsoft Bot Framework
Adaptive Cards for building some UI snippets

Building an action

🎏 Grabbing the code sample

In this tutorial, I am using the 3rd party tool, Glitch to host and run this project and the rest of the tutorial series. For a little more details what Glitch is and why I am using it, please refer my previous tutorial!

First, let's just click this Glitch link to remix the project. Remixing is like the forking a repo on GitHub, so it generates a copy of the project for you, so you can modify the code in the way you want without messing with the original 🙌

Once you get your own project repo, it serves up the app automatically and you get your own web server URL. You will need the URL when you are setting up an app with App Studio later.

⚙️ App Configuration: Creating App Manifest with App Studio

The basic idea of App Package for Teams, please refer to the previous tutorial.

🎛 Using App Studio

Open App Studio app in Teams client.

In App Studio, click the Manifest Editor tab from the top, then select Create a new app and fill out all the required fields including the Bot names, descriptions, etc.

Then, generate an App ID.

🔖 Configuring a Messaging Extension

From the left menu, select Capabilities > Massaging Extensions. Go ahead and click the Setup button to set up.

Give your app a name.

🔐 App credentials

Copy the ID next to your bot name (something looks like 2cd53e8a-e698-4exx-...) and paste it as an environment variable in your .env file, which is supposed to be a hidden file (Rename the .env-sample to .env).

Under App Passwords, generate a new password, and copy it. Then paste it in your .env file.

These credentials are used to initialize your bot adapter. (See index.js).

(Step 3 in the screen image above will be explained at the next step.)

🎬 Configuring an Action

At Messaging Endpoint, enter your web server URL, like, https://[your project].glitch.me/api/messages if you have remixed the sample repo.

Scroll to Command and click "Add".

In the dialog box -

Select "Allow users to trigger actions in external service..."
Select "Fetch a dynamic set of parameters from your bot"
Fill out the command ID and title text. Click "Massage" (Unselect other checkboxes if they are pre-selected). Leave the rest blank, then save.

📦 Installing the app manifest package

Go to Finish > Test and distribute.

If you get any errors, go fix it, otherwise, click Install your client.

You can also download the zip file that contains manifest.json, and two icon images to install later or distribute.

As long as you remixed the code sample, the bot should work already. But let me quickly explain how it is coded before trying the bot.

🤖 Microsoft Bot Framework

The Microsoft Bot Framework is an open source SDK that allows you to build intelligent, enterprise-grade bots.

This SDK is a powerful platform that not only for Teams, but also designed to work for wide types of chat bots, including web & mobile chat, Skype, Facebook, Amazon Alexa, Slack, Twilio, and more!

🔧 Initiating the bot service

First, there are two JS files in the Glitch code sample repo, index.js and bots.js.

I am using Express to set up an HTTP server and routing HTTP requests. And the way to initiate the service is the same as the previous Bots tutorial, but this is the recap of the initialization, and creating a bot adapter:

// Import bot services
const { BotFrameworkAdapter } = require('botbuilder');

// Bot's main dialog
const { ReverseBot } = require('./bot');

// App credentials from .env
const adapter = new BotFrameworkAdapter({
  appId: process.env.MicrosoftAppId,
  appPassword: process.env.MicrosoftAppPassword
});

// Create the main dialog
const myBot = new MorseBot();

Note: In this example, I am using botbuilder version 4.10.0. If your code doesn't work as expected, check the version you are using!

🦉 Forwarding requests to the bot logic

Use Express to handle the routing to listen for incoming requests:

app.post('/api/messages', (req, res) => {
  adapter.processActivity(req, res, async context => {
    await myBot.run(context);
  });
});

You have set up the URL in App Studio in the previous step. The /api/messages is your application’s endpoint URL to respond to client requests.

🙋‍♀️ Handling the request

Once a request is received at the endpoint and forwarded to the bot logic, your app receive the context of the request, then create a custom reply in bots.js.

See the TeamsActivityHandler is extended to create an appropriate handler for the request:

class MorseBot extends TeamsActivityHandler {

  // Triggers when the message action is invoked by a user
  handleTeamsMessagingExtensionFetchTask(context, action) {
    /*
      We're going to create an adaptive card UI (modal dialog) here.
      In the dialog, the user confirms what text to be encoded to Morse code.
    */
  }

// Triggers when the dialog box is submitted from the FetchTask
  handleTeamsMessagingExtensionSubmitAction(context, action) {
    // display the result 
  }

The TeamsActivityHandler is a Teams specific class that handles messages- such as messages events and sending replies.

In this scenario, when a user triggers an action from a message, handleTeamsMessagingExtensionFetchTask gets invoked, so your bot received the information about the message when the action was made from.

You can learn more about it at Create and send the task module on Teams documentation

📇 Displaying a modal dialog with Adaptive Cards

The dialog UI is created with Adaptive Cards, which is a Microsoft open source to build snippets of UI in JSON, and can be used in Microsoft Teams, Outlook Actionable Messages, Cortana Skills, etc.

When handleTeamsMessagingExtensionFetchTask is invoked, get the message content text, and display it in a Adaptive card as a modal dialog, as the response.

To defining an Adaptive card and the content:

const card = {
  type: 'AdaptiveCard',
  version: '1.0'
};

card.body = [
  { type: 'TextBlock', text: 'The message to be encoded to Morse code:', weight: 'bolder'},
  { id: 'editedMessage', type: 'Input.Text', value: content },
];
card.actions = [{
  data: { submitLocation: 'messagingExtensionFetchTask'},
  title: 'Encode to Morse!',
  type: 'Action.Submit'
}];

const adaptiveCard = CardFactory.adaptiveCard(card);

return {
  task: {
    type: 'continue',
    value: {
    card: adaptiveCard
  }
}

I am displaying the extracted message text in the type: 'Input.Text' so that the user can edit the text to be Morse-coded!

To view the full code, please see the bot.js file in the code sample in Glitch.

📮 Handling the user submission

Once a user submits the task module, handleTeamsMessagingExtensionSubmitAction gets triggered and your web service will receive an object with the command id and parameter values set.

In this sample code, it just checks if the custom data, editedMessage is there. And if so, grab the value (should be a string) and convert it and display the content to be composed as a new message.

async handleTeamsMessagingExtensionSubmitAction(context, action) {

  if(action.data.editedMessage) {
    const text = action.data.editedMessage;
    const morseText = await encodeToMorse(text);

    return {
      composeExtension: {
      type: 'result',
        attachmentLayout: 'list',
        attachments: [
          // The message UI component here
          // Please refer to the sample code on Glitch to see the entire code
        ]
      }
    }
  }
}

In the code sample shown in the bots.js, I am using the simple UI "card" called Thumbnail Card that comes with Bot Framework to compose the result message, but you can use Adaptive Card too!

🤖💬 Trying your Message Action

Now, let's try the action! Go to the Teams client, and click one of the text messages (not in rich format or image).

If everything works as expected, you should be able to convert any text messages into a Morse code!

I hope you get some good ideas about what you can do with Microsoft Teams platform with this tutorial, I hope you find better use cases than this and create something amazing!

The next tutorial will walk you through how to build another type of Messaging Extension, which is a search command. See you next time 👋

Beginners Guide to MS Teams Development #2: Bots

Tomomi Imura 🐱 — Mon, 05 Oct 2020 21:41:23 +0000

Hello, I hope you enjoyed my previous tutorial on how to get started with Microsoft Teams development.

This is the second one of the beginner series, and this time, I will walk you through how to build a conversational bot.

There are many different paths to learn how to build Teams apps, and this tutorial uses a bare-minimum code and minimal toolsets. Also, this tutorial is independent of the hosting environment, so I am not staring the process with the Azure setup, and basically, this should run on any environment. (Although this article is listed under MS Azure 😉)

In last article, I showed you how to embed a tab, but in this tutorial, I am going to show you a completely different feature, bots.

Teams features: Bots

There are a variety of features you can use to build Teams app, like Messaging extensions, tabs, etc. and bots turn words into actions, such as, generate an order, review my code, check ticket status, etc. A bot can kick off these kinds of workflows right inside Teams.

What you are going to do in this tutorial

You are going to create a plain bot, which replies what you say in backward. Yes, this is not a useful bot at all, but hopefully, this sample gives some good ideas about what you'll build in the future.

Configure your app with App Studio
Set up your code on an online IDE and run
Use Microsoft Bot Framework to handle bot conversation

The end result would look like this:

📓 Prerequisites

To be able to install apps to Teams, your organization's admin needs to grant permission.

Otherwise, you can sign up for Microsoft 365 developer program, a free, renewable subscription that comes with a developer tenant sandbox and sample data pack, like mock user data!

Permission to develop on Teams or developer tenant (Sign up for M365 developer program!)
App Studio - look for the app from the Apps menu in Teams client and install to your workspace
Experience with Node.js and basic understanding of Express.js

Unlike the previous tutorial, that requires some front-end coding skills, to work with bots, you need a different skill set, and for this tutorial, Node.js.

Building a chat bot

🎏 Grabbing the code sample

In this tutorial, I am using the 3rd party tool, Glitch to host and run this project and the rest of the tutorial series. Glitch is a web-based IDE that you can write and run your node.js code, so at least for now, you can focus on learning the concepts and basics of Teams app development without worrying about running and tunneling localhost, or deploying. (I will cover them in the future!)

Once you get your own project repo, it serves up the app automatically and you get your own web server URL. For example, if your generated project name, usually it consists of a few random words, is achieved-diligent-bell, your Node server URL would be https://achieved-diligent-bell.glitch.me. You can customize the name too if you want, too. You will need the URL when you are setting up an app with App Studio later.

⚙️ App Configuration: Creating App Manifest with App Studio

This section is exactly the same as one in my previous tutorial to build tabs.

When you are building any apps for Teams, you must create an app package to be installed to Teams client. The package includes:

📁 your-app-package
    └── 📄 manifest.json
    └── 🖼 color.png (192x192)
    └── 🖼 outline.png (32x32)

and the rest of the app code and assets must be hosted on your webserver. (In this tutorial, we are using Glitch to automatically serve your app).

We are not creating the manifest file manually today, but instead, we are going to create the app package using a visual tool called App Studio so you can create the package directly to Teams client.

🎛 Using App Studio

Installed App Studio app in Teams client, if you haven't. Then, open the app.

In App Studio, click the Manifest Editor tab from the top, then select Create a new app and fill out all the required fields including the Bot names, descriptions, etc.

At the App URLs section, fill out your privacy and Terms of Use webpage URLs. In this example, I am just using the placeholder URL, https://example.com, but when you're developing apps to publish, you must have the web pages with the statements.

Also, generate an App ID.

🔖 Configuring a bot

From the left menu, select Capabilities > Bots.

Then click Set up to configure a new bot.

Fill out the bot name, and let's just select the Personal scope for now. A personal bot allows conversing between bots and a single user. (To learn more about the scopes, read Conversation basics on docs.)

Then, click Generate new password. At the modal popup, copy the password, which you will need to paste it in your .env file at the next step!

🔐 App credentials

Under App Passwords, generate a new password, and copy it. Then paste it in your .env file.

These credentials are used to initialize your bot adapter. (See index.js).

At Messagind Endpoint, enter your bot server, which should be https://[your project].glitch.me/api/messages.

📦 Installing the app manifest package

Go to Finish > Test and distribute.

If you get any errors, go fix it, otherwise, click Install your client.

You can also download the zip file that contains manifest.json, and two icon images to install later or distribute.

As long as you remixed the code sample, the bot should work already. But let me quickly explain how it is coded before trying the bot.

🤖 Microsoft Bot Framework

The Microsoft Bot Framework is an open source SDK that allows you to build intelligent, enterprise-grade bots.

This SDK is a powerful platform that not only for Teams, but also designed to work for wide types of chat bots, including web & mobile chat, Skype, Facebook, Amazon Alexa, Slack, Twilio, and more!

🔧 Initiating the bot service

First, there are two JS files in the Glitch code sample repo, index.js and bots.js.

Note: Glitch automatically pulls all dependencies from the pre-defined package.json so you do not need to install the packages manually.

In index.js, you need to include the libraries, botbuilder, and a library to set up an HTTP server and routing HTTP requests. I am using Express but you can use something else you prefer, such as, Restify.

index.js:

// Import Express & set up HTTP server
const express = require('express');
const app = express();
const server = app.listen(process.env.PORT || 3978);

// Import bot services
const { BotFrameworkAdapter } = require('botbuilder');

// Bot's main dialog
const { ReverseBot } = require('./bot');

Note: In this example, I am using botbuilder version 4.10.0. If your code doesn't work as expected, check the version you are using!

Then, set up the adapter that allows your bot to communicate with the user and send responses.

const adapter = new BotFrameworkAdapter({
  appId: process.env.MicrosoftAppId,
  appPassword: process.env.MicrosoftAppPassword
});

// Error handlings (See the Glitch sample for details!)

// Create the main dialog
const myBot = new ReverseBot();

🦉 Forwarding requests to the bot logic

Use Express to handle the routing to listen for incoming requests:

app.post('/api/messages', (req, res) => {
  adapter.processActivity(req, res, async context => {
    await myBot.run(context);
  });
});

You have set up the URL in App Studio in the previous step. The /api/messages is your application’s endpoint URL to respond to client requests.

💬 Handling the request and post bot replies

Once a request is received at the endpoint and forwarded to the bot logic, your app receive the context of the request, then create a custom reply in bots.js.

See the TeamsActivityHandler is extended to create an appropriate handler for the request:

const { TeamsActivityHandler, MessageFactory } = require('botbuilder');

class ReverseBot extends TeamsActivityHandler {
  constructor() {
    super();
    this.onMessage(async (context, next) => {
      const backward = [...context.activity.text].reverse().join(''); // reverse string
      const replyText = `🙃 *${ backward }*`; // you can use markdown
      await context.sendActivity(MessageFactory.text(replyText));

      await next();
    });
  }
}

The TeamsActivityHandler is a Teams specific class that handles messages- such as messages events (e.g. onMembersAdded method is called whenever a member is added to the conversation), and sending replies.

In the example, when a message is send to the client, the onMessage is triggered, and you can grab the message text and use it to create the custom reply, in this case, reverse the string and send back to the user.

🤖💬 Trying your bot

Now, let's try the bot! Go to the Teams client, and click launch the bot from the left menu bar.

If everything works as expected, you should be able to converse with the bot like this:

This example only shows you how to send a text reply, however, you can create more interactive messages using buttons and other UI components. I will explain more about it later.

I hope you enjoyed the tutorial, I hope you find better use cases than this and create something amazing! See you next time 👋

📚 Learn more

MS Teams Documentation - What are conversational bots?
Microsoft Bot Frameworks
Bot Services Documentation - How bot works?
Microsoft Azure tutorials & articles on Dev.to

Beginners Guide to MS Teams Development #1: Tabs

Tomomi Imura 🐱 — Thu, 01 Oct 2020 21:47:32 +0000

I hope you are all doing well while the pandemic is still at large. Well, since we all stay indoors most of the time, we can leverage the time to learn something new rather than hibernate 🐻💤

So this tutorial is my first of the beginner series for Microsoft Teams development. This is good for developers, who are using Microsoft Teams at your work and thinking about building some apps (can be internal tools, or publish for everybody) that run inside of Teams, and/or who have published some app on other platforms like Slack and want to gain more users on Teams. Also, you don't need to have prior experience with any Microsoft cloud technology to try this tutorial!

There are many different paths to learn how to build Teams apps, and this tutorial uses a bare-minimum code and minimal toolsets with some visual approach. Alternatively, try the tutorial on the Microsoft docs, if you want to jump ahead with the full-scale approach.

Okay, as the very first of this beginner series, let me quickly explain what tabs feature is.

Teams features: Tabs

There are a variety of features you can use to build Teams app, like Messaging extensions, conversational bots, etc. and Tabs are where you can display any information in any visual interface.

Technically, tabs are just iframes, where you can display any webpages. You just have to configure to display it correctly on Teams!

Here, I am going to show you how to create two types of Tabs - a personal tab (only viewable by the person who installed it) and a team tab (a team-level tab).

What you are going to do in this tutorial

Configure your app with App Studio
Build a personal tab on an online IDE and serve from there
Re-configure to modify it to a channel/group tab
Add more functions for the team tab
Add the dark mode support

The end result would look like this:

📓 Prerequisites

To be able to install apps to Teams, your organization's admin needs to grant permission.

Otherwise, you can sign up for Microsoft 365 developer program, a free, renewable subscription that comes with a developer tenant sandbox and sample data pack, like mock user data!

Permission to develop on Teams or developer tenant (Sign up for M365 developer program!)
App Studio - look for the app from the Apps menu in Teams client and install to your workspace
Basic knowledge of JavaScript

1. Building a Personal Tab

🎏 Grabbing the code sample

Go to the sample code page and remix the project. Remixing is like the forking a repo on GitHub, so it generates a copy of the project for you, so you can modify the code in the way you want without messing with the original 🙌

Once you get your own project repo, it serves up the app automatically and you get your own web server URL. For example, if your generated project name, usually it consists of a few random words, is achieved-diligent-bell, your webserver URL would be https://achieved-diligent-bell.glitch.me. You can customize the name too if you want, too.

⚙️ App Configuration: Creating App Manifest with App Studio

When you are building apps for Teams, you must create an app package to be installed to Teams client. The package includes:

📁 your-app-package
    └── 📄 manifest.json
    └── 🖼 color.png (192x192)
    └── 🖼 outline.png (32x32)

and the rest of the app code and assets must be hosted on your webserver. (In this tutorial, we are using Glitch to automatically serve your app).

We are not creating the manifest file manually today, but instead, we are going to create the app package using a visual tool called App Studio so you can create the package directly to Teams client.

🎛 Using App Studio

Once you have installed App Studio app in Teams client, open the app. You can launch it by clicking the . . . from the left menu bar.

Then, click the Manifest Editor tab from the top, then select Create a new app.

You are going to need to fill out all the required fields including the app names, descriptions, etc.

At the App URLs section, fill out your privacy and TOU webpages. In this example, I am just using the placeholder URL, https://example.com, but when you're developing apps to publish, you must have the web pages with the statements.

🔖 Configuring a personal tab

From the left menu, select Capabilities > Tabs.

Click the Add button under Add a personal tab and enter the info.
Under Content URL, enter your webpage URL (should be https://[your-project-name].glitch.me/index.html).

Currently, the index.html file has nothing more than a few lines of static HTML code (and some CSS):

<h1>Hello world! </h1>
<p>This is the bare-minimum setting for MS Teams Tabs. </p>

Feel free to tweak the content in the index.html as you want. This is the content to be displayed in your Teams client.

🎉 Finish creating the app manifest package

Go to Finish > Test and distribute.

If you get any errors, go fix it, otherwise, click Install your client.

Ta-da, now you have the personal tab at the left menu 🎉

If something is wrong after installing it properly, check if the Content URL is set correctly. Make sure that you're using your own web server URL, like https://[your-project-name].glitch.me/index.html.

You can stop here, or proceed to make it into a team tab at the next step.

2. Building a Channel/Group Tab

Now, let's transform this into a channel/group tab. It requires a few extra steps.

🎏 Grabbing the code sample on Glitch

You can directly remix the code sample by clicking the remix link here this time. Or feel free to continue with the previous code sample and modify the code.

Notice that this code sample has the additional config.html, also some JavaScript code added.

⚙️ Tweaking App Configuration

Go back to App Studio, open the app you just create, and let's modify the tabs settings. (Or create a new app if you want a fresh one! In this case, you will need to fill out the app details for the new app.)

🔖 Configuring a team tab

Go to Capabilities > Tabs. You can either leave or delete the personal tab you have created previously.

Click the "Add" button under Team tab, and enter the info.
Under Configuration URL, enter your web URL (should be https://[your-project-name].glitch.me/config.html). Even if you don't have any configurable content, this field is required.

Using JavaScript SDK for Tabs to load the content

Unlike the personal tab, which can be just a plain static HTML, for the team tab, let's use the SDK to load the main content.

Notice that these lines of code are included in the config.html:

<script src="https://statics.teams.cdn.office.net/sdk/v1.6.0/js/MicrosoftTeams.min.js"></script>

Note: As you may notice, this example uses SDK version 1.6.0. If your code doesn't work as expected, check the version you are using!

microsoftTeams.initialize();

microsoftTeams.settings.setSettings({
  contentUrl: 'https://msteams-teamtab-minimum.glitch.me/index.html',
  });
microsoftTeams.settings.setValidityState(true);

You can add some dynamic values like some user locale info by using the getContext() method. To learn more about the Teams SDK, read the SDK documentation.

Then, try the app by going to Finish > Test and distribute and install the app.

If everything goes well, your app appears at the top of the client 🎉

🔦 Theming (Supporting Dark Mode & High-Contrast Mode)

But wait, what if you and your potential app users are in the dark mode? Does it automatically handle the color change in the iframe?

No. So let's fix that.

Take a look at one of the view HTML files. Notice it has JavaScript to handle the theme detection (and theme change event handling).

In this example, on the default (light) theme, the default text color (typically black) is used, otherwise, white.

microsoftTeams.getContext((context) => {
  if(context.theme !== 'default') {
    document.body.style.color = '#fff';
  }
});

microsoftTeams.registerOnThemeChangeHandler((theme)=> { 
  if(theme !== 'default') {
    document.body.style.color = '#fff';
    document.body.style.color = 'inherit';
  }
});

Now, let's toggle the theme and see how the change is reflected.

You can change the client theme color by going to the settings menu from your avatar at the top-right.

The font color should be white in the dark or high-contrast mode like this:

🙌

I hope you have better ideas on how you can get started with Microsoft Teams app development.

In the tutorial, to make as simple as possible, I did not tell you how to use the recommended toolsets, however, in the reality, you probably create a full-fledged app with more tools with VS Code and probably some front-end framework like React with a build manager, etc, and deploy to Azure! Stay tuned for these tutorials too.

To learn more, please go check the links below.

In the next tutorials, I will show you how to create interactive message extensions. So, see you next time 👋

Learn more

MS Teams Documentation - Overview
Build a Hello World App - this instruction uses VSCode, ngrok, and React.js
Microsoft Azure tutorials & articles on Dev.to

Spread Syntax "Three-dots" Tricks You Can Use Now

Tomomi Imura 🐱 — Thu, 18 Jun 2020 01:51:40 +0000

This articles is created based on my own tweet posted on May 22, 2020

ES6 (ECMAScript 2015, the 6th edition) was finalized 5 years ago, and brought us a significant amount of new syntax and features to help you write complex code better and simpler.

I am assuming that many of you have consumed more calories from the syntactic sugar by adopting new features like class declarations, let / const, and arrow function expression, and so on, but how about some of the lesser-known Spread operator?

Here, I would like to share some good usages of spread operator, a.k.a three-dots that I've found while I was coding (and StackOverflowing, I don't lie about how I code!).

What do Three Dots do?

First, there are two "three-dots" sugars introduced in ES6. One is Rest parameter, which allows us to use an arbitrary number of arguments, and another is Spread operator, which also has the similar syntax with three dots, but it is more like the reversed version- it takes the array itself, not arguments.

In this article, I am showing tricks that uses spread syntax. Looking at the practical examples may be far easier to understand what it does than by reading the definitions!

Concat

You say "cat" so I say meow.

Let's concatenate two arrays. Here we have two arrays that represent cat fur coat colors:

const arr1 = ['solid', 'bicolor', 'tabby'];
const arr2 = ['calico', 'tortoiseshell'];

This is how we traditionally did before ES6 using concat():

var conCats = arr1.concat(arr2);
// ['solid', 'bicolor', 'tabby', 'calico', 'tortoiseshell']

Now you can simply write with the ES6 spread syntax like this:

const conCats = [...arr1, ...arr2]; 
// ['solid', 'bicolor', 'tabby', 'calico', 'tortoiseshell']

Convert a string to array

Have you been asked to reverse a string, or check if a string is a palindrome at job interviews? The questions you got may be more complex, but these are pretty common interview questions for software engineers.

Anyway, the first step to solve the question is likely to convert the given string to an array.

You have a given string:

const str = 'kitty';

With pre-ES6 JavaScript, use split() to get each letter in an array:

var newArr = str.split(''); // ['k', 'i', 't', 't', 'y'];

Now with the ES6 spread syntax, you can achieve the same as:

const newArr = [...str]; // ['k', 'i', 't', 't', 'y'];

Find Max or Min

Let's say, you have a given set of numbers,

10, 9, 6, 12

To find the largest (or smallest) number from the set of numbers, you can use Math.max() (or Math.min()) and pass the given numbers as input parameters like this:

var max = Math.max(10, 9, 6, 12);

Now with the ES6 spread syntax, you can pass an array of numbers:

const nums = [10, 9, 6, 12];
const max = Math.max(...nums); // 12

Copy an Array

You can also create a shallow copy of an array with the spread syntax.

You have an array,

const allCatNames = ['chewie', 'leia', 'yoda', 'chewie', 'luke', 'leia'];

And onne way to get a shallow copy of the array with the pre-ES6 is using slice():

var allCatNamesCopy = allCatNames.slice();

Now with ES6 spread syntax, you can simply do:

const allCatNamesCopy = [...allCatNames];

Remove Dups from an Array

The array, allCatNames above has some duplicated values (chewie and leia appeared twice in the list). If want to remove the duplicates, you'll write multiple lines of code with pre-ES6 JavaScript-

You probably would iterate the array. And at each loop, map each value in an object to track if the key in the object is unique, and if yes, the value is pushed to a new array. Then at the end of the loop, you have the new array only with unique values.

You can actually achieve this in one line of code with spread syntax by creating a new array with combination of the spread syntax with the Set object:

const catNames = [...new Set(allCatNames)]; 
// ['chewie', 'leia', 'yoda', 'luke'];

Ta-da, this saves a lot of code!

Collecting HTML Elements in an Array

If you are a front-end JavaScript developer, this trick may be useful when you manipulate DOM-

Let's say, when you re trying to grab every element with the class name, .cat, you probably use querySelectorAll() to get the collection of the DOM nodes.

But document.querySelectorAll('.cat') returns a static NodeList, which is an array-like, but not exactly an array that you can iterate over it.

So in some occasions, you need to convert a NodeList to Array. Traditionally, you probably have been writing code like this, which doesn't seem so intuitive:

var catElementArray = [].slice.call(document.querySelectorAll('.cat'));

Now with the spread syntax, you can rewrite as followings:

const catElementArray = [...document.querySelectorAll('.cat')];

This looks more intuitive, doesn't it?

Well, if you like the three-dots notation or not, now you see that the spread operator can be quite handy when you work with arrays and objects.

I would be happy if I just convinced you to use the three-dots in your daily code from now on. Surely, there are more clever ways to write code with using the spread operator, so if you know the tricks, please share with me and the rest of the JS community!

Wants to find out more about ES.Next?

I will be giving a talk, ECMeowScript - What’s new in JavaScript Explained with Cats at Forward JS (~~San Francisco~~ virtual) and Web Directions (~~Sydney~~ virtual) in September, so I hope you can catch my talk! 🐱

(Edit: Conference month has been updated.)

Ciao!