Develop Bot For MS Teams With Bot Builder V4 SDK

Overview

 

MS Teams supports integration with various apps and services. Bot is one of them. Both v3 and v4 bots built on the Bot Framework work well with MS Teams. All new development should be targeting the Bot Builder v4 SDK. Bots can be developed using .NET or Node.js.

 

In this article, we will develop a bot framework bot and extend it to MS Teams. Please follow my previous article Getting Started with MS Teams Development to set up your development environment. 

 

Visual Studio Bot Template

 

The Microsoft Bot Framework v4 Templates for Visual Studio can be downloaded from here. It is available as a VSIX package. It helps to build new conversational AI bots using the Microsoft Bot Framework v4. Both v3 and v4 bots built on the Bot Framework work well with MS teams.

 

Once installed, the Bot Framework project creation option will be available for new project creation from Visual Studio.

 

Develop an Echo Bot

 

We will create a simple echo Bot in MS Teams. Follow the below steps to start developing a Bot.

1. Open Visual Studio 2017 as an administrator.
2. Click File > New > Project.
3. Under Visual C#, select Bot Framework > Echo Bot (Bot Framework v4).
   
   
   
   
4. Click OK.
5. Build the solution. This will download all referenced NuGet packages.
6. Open project properties.
7. Under Debug, note down the App URL.
   
   

Run the ngrok

 

Ngrok is a free program that exposes a process running on your localhost to the public internet. Run the ngrok secure tunnel application by executing the below steps.

On the command prompt, navigate to ngrok.exe location.

 

Execute the below command.

ngrok.exe http [port] -host-header=localhost:[port]

Replace [port] with the port mentioned in the App URL of solution. E.g.: 

ngrok.exe http 3978 -host-header=localhost:3978

Register Bot in MS Azure

1. Open MS Azure portal (https://portal.azure.com)
2. Click “Create a resource”.
3. Search for Bot in the marketplace.
4. Select Bot Channels Registration”.
   
   
   
   
5. Click Create.
6. Fill in the form details.
7. For “Messaging endpoint”, specify below value.
   
   https://[ngrok-address].ngrok.io/api/Messages
   
   Replace token [ngrok-address] with forwarding address from ngrok window. (e.g. https://4541d6ad.ngrok.io)
   
   
8. Choose to auto-create App ID and password.
   
   
   
   
9. Click Create.
10. Navigate to the resource, when created.
11. Under “Bot Management” section, click “Channels”.
    
    
    
    
12. Click “MS Teams” icon under the featured channel.
    
    
    
    
13. Click Save.
14. Agree to the “Terms of Service”.

Get the Bot Channel Registration Id and secret

1. Under the “Bot Management” section, click Settings.
2. Note down Microsoft App ID.
   
   
   
   
3. Click Manage link, next to Microsoft App ID.
4. Under “Client secrets”, click “New client secret”.
   
   
   
   
5. The dialog window will appear. Add description and expiration.
6. Click Add.
   
   
   
   
7. Copy the secret string.
8. In the Visual Studio, add MicrosoftAppId and MicrosoftAppPassword under appsettings.json.
   
    

Package Bot from Visual Studio

 

We will add manifest file and related resources that will be compressed as a zip file and added to MS Teams.

1. In Visual Studio, add folder “Manifest”.
2. Upload icons for color and outline.

Add file manifest.json with the below content.

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.3/MicrosoftTeams.schema.json",
  "manifestVersion": "1.3",
  "version": "1.0.0",
  "id": "[microsoft-app-id]",
  "packageName": "io.ngrok.[ngrok-address]",
  "developer": {
    "name": "Office Developer",
    "websiteUrl": "https://[ngrok-address].ngrok.io",
    "privacyUrl": "https://[ngrok-address].ngrok.io/privacy",
    "termsOfUseUrl": "https://[ngrok-address].ngrok.io/termsofuse"
  },
  "icons": {
    "color": "bot-icon-color-192x192.png",
    "outline": "bot-icon-outline-32x32.png"
  },
  "name": {
    "short": "office-content-management-bot ",
    "full": "Office Content Management Bot"
  },
  "description": {
    "short": "Office Content Management",
    "full": "Sample bot for the Office Content Management"
  },
  "accentColor": "#AB00B0",
  "bots": [
    {
      "botId": "[microsoft-app-id]",
      "supportsFiles": true,
      "scopes": [
        "personal",
        "team"
      ]
    }
  ],
  "composeExtensions": [],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": []
}

Replace token [microsoft-app-id] with MicrosoftAppId.

 

Replace token [ngrok-address] with forwarding address from ngrok window. (e.g. https://4541d6ad.ngrok.io)

 

Compress Manifest folder

1. In the Solution Explorer, right-click on the project and choose to unload.
2. Again, right-click on the project and choose to edit.
3. Since AfterBuild and AfterPublish targets are defined in the import <Project Sdk="Microsoft.NET.Sdk.Web"> it is expanded to include Sdk.props file before your project's content and Sdk.targets after them, the targets defined in the project will be overwritten by the targets defined by the SDK / "common targets".

Update the file as below,

<Project>

  <Import Project="Sdk.props" Sdk="Microsoft.NET.Sdk.Web" />
  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.Bot.Builder.Integration.AspNet.Core" Version="4.4.3" />
  </ItemGroup>

    <ItemGroup>
    <Content Update="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>
</Project>

Add below target at the end of file.

<Import Project="Sdk.targets" Sdk="Microsoft.NET.Sdk.Web" />
<Target Name="AfterBuild">
  <ZipDir InputBaseDirectory="manifest"
          OutputFileName="$(OutputPath)\$(MSBuildProjectName).zip"
          OverwriteExistingFile="true"
          IncludeBaseDirectory="false" />
</Target>

Add below task element at the end of file. 

<UsingTask TaskName="ZipDir" TaskFactory="CodeTaskFactory"
        AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.v4.0.dll">
  <ParameterGroup>
    <InputBaseDirectory ParameterType="System.String" Required="true" />
    <OutputFileName ParameterType="System.String" Required="true" />
    <OverwriteExistingFile ParameterType="System.Boolean" Required="false" />
    <IncludeBaseDirectory ParameterType="System.Boolean" Required="false" />
  </ParameterGroup>
  <Task>
    <Reference Include="System.IO.Compression" />
    <Reference Include="System.IO.Compression.FileSystem" />
    <Using Namespace="System.IO.Compression" />
    <Code Type="Fragment" Language="cs">
      <![CDATA[
    if (File.Exists(OutputFileName))
    {
      if (!OverwriteExistingFile)
      {
        return false;
      }
      File.Delete(OutputFileName);
    }
    ZipFile.CreateFromDirectory
    (
      InputBaseDirectory, OutputFileName,
      CompressionLevel.Optimal, IncludeBaseDirectory
    );
  ]]>
    </Code>
  </Task>
</UsingTask>

In the solution explorer, right-click and reload the project.

 

Build the solution. The AfterBuild target will run and compressed .zip file will be available under the bin folder.

 

Run the Visual Studio solution by pressing F5 key.

 

Upload app into Microsoft Teams

1. Open MS Teams.
2. Right-click on any existing team, click "Manage team".
   
   
   
   
3. Click the Apps tab.
4. Click “Upload a custom app”.
   
    
   
   
5. Upload the zip file generated inside the bin folder of Visual Studio solution.
6. The bot app will be available to use.
   
   
   

Test the Bot in MS Teams

1. Open MS Teams.
2. From the left menu, click Chat.
3. Our Bot (named OfficeContentManagement) should be listed out.
4. Send the messages to Bot, it should echo back.
   
    

In order to run the bot inside Microsoft Teams:

• The bot must be accessible from the internet.
• The bot must be registered with the bot connector.
• The AppId and AppPassword from the bot framework registration page have to be recorded in the project's web.config.
• The bot must be added to Microsoft Teams.

Summary

 

MS Teams supports integration with various apps and services including Bot. Both v3 and v4 bots built on the Bot Framework work well with MS Teams. Visual Studio offers ready templates for Microsoft Bot Framework v4. Ngrok exposes a process running on your localhost to the public internet.