January 12th, 2018

Microsoft Teams C# Sample App

Microsoft Teams team
Microsoft Teams team

We’ve heard you and we’ve delivered, the Microsoft Teams C# sample app is here! This sample app will give you all the tools you need to start developing for Microsoft Teams.

The sample app has two goals:

  1. To show you different examples of how an app can integrate into Teams.
  2. To give you a starting point of patterns, examples, and tools that can be used as a template for creating a larger, scalable, enterprise-level bot to work within Teams.

To get the sample app up and running, follow the directions below or in the readme.md file in Github.

Prerequisites

  1. Install Git for windows: https://git-for-windows.github.io
  2. Clone this repo:

git clone https://github.com/OfficeDev/microsoft-teams-sample-complete-csharp.git

  1. Install Visual Studio and launch it as an administrator.
  2. Build the solution to download all configured NuGet packages.
  3. Install some sort of tunneling service. These instructions assume you are using ngrok, which you can download from https://ngrok.com
  4. Install the Bot Emulator – click on “Bot Framework Emulator (Mac and Windows)”: https://docs.botframework.com/en-us/downloads

Steps to see the bot running in Bot Emulator

NOTE: Teams does not work nor render things exactly like the Bot Emulator, but it is a quick way to see if your bot is running and functioning correctly.

  1. Open the template-bot-master-csharp.sln solution with Visual Studio.
  2. In Visual Studio click the “Start Debugging” button (typically defaulted to running the Microsoft Edge configuration).
  3. Once the code is running, connect with the Bot Emulator to the default endpoint, “http://localhost:3979/api/messages,” leaving “Microsoft App ID” and “Microsoft App Password” blank.

Congratulations! You can now chat with the bot in the Bot Emulator!

Steps to see the full app in Microsoft Teams

  • Begin your tunneling service to get an https endpoint.
    • Open a new Command Prompt
    • Change to the directory that contains the ngrok.exe application.
    • Run the command ngrok http [port] –host-header=localhost(you’ll need the https endpoint for the bot registration) e.g.

ngrok http 3979 –host-header=localhost

  • The ngrok application will fill the entire prompt window. Make note of the “Forwarding” address that is using https. This address is required in the next step.
  • Minimize the Command Prompt window that’s running ngrok. It’s no longer referenced in this article, but it must remain running.
  • Register a bot in the Microsoft Bot Framework.

Bots in Teams must be built upon the Microsoft Bot Framework. For this sample, as part of the package download process, you’ll get the Bot Framework SDK and the Microsoft Teams extensions to Bot Framework.

In addition, every bot must be registered in the Bot Framework, so it is accessible by the services it uses like Microsoft Teams. Our samples are designed for you to run yourself, so you’ll need to create your own bot, which also includes a Microsoft App ID and password. Here’s how:

  • Using your work or school account, sign in to the Microsoft Bot Framework site https://dev.botframework.com/bots/new.
  • Display name – Give your app a name. This does not have to be unique. This will be the name displayed in Teams. We recommend that you make this the same name as your app name in the manifest (this sample uses Sample-App-csharp).
    • Note: If you decide to change the Display Name or icon after your bot is registered, it may take some time before your new name or icon will show up in your Teams client; logging out and logging back in will usually accelerate this.
  • Bot handle – Create a unique identifier for your bot.
    • Note: This cannot be changed and is not visible to users. If you change the Display name of your bot, your Bot handle will remain the same.
  • Long description – Enter a long description which may appear in channels or directories.
      • Note: In Microsoft Teams, the Store information will come from the Seller Dashboard.

Next, you need to configure your bot’s service endpoint so Microsoft Teams knows how to connect to your bot:

  • Messaging endpoint – Paste the ngrok URL that you copied to the clipboard and append the appropriate endpoint to it. For our samples, again, our code is listening for messages on “/api/messages”, so for example you’d enter “https://2d1224fb.ngrok.io/api/messages”
  • Create Microsoft App ID and password – This button will take you to the Application Registration Portal, where you will create a unique Microsoft App ID and password.
    • App name – This will be filled in from what you entered in the previous step
    • App ID – This is a unique GUID created for your app, e.g. 93fed3d5-6782-462e-8a58-6a3e83ca6eab
    • Generate an app password to continue – Click this button to generate an app password (you’ll sometimes see this called an app secret), e.g. qgSctpqT89ZdfAymt66Ukgf
      • Note: You’ll need to copy and save this in a secure location as you will need this, and the App ID later. The app password will only be shown once.
      • Click the “Finish and go back to Bot Framework” button.
  • On the new page that opens once your app is done being created, click on the Microsoft Teams icon under “Add a featured channel” in order to allow your bot to use this channel. You’ll return to the Registration page, with the App ID filled in, that matches the one created above. Check the box at the bottom to agree to the terms of use, and click “Register” to create your new accessible Bot Framework bot
    • Click on the Microsoft Teams icon under “Add a featured channel.”
      • Check the box to agree to the Terms of Service.
      • Click “Done” on the Configure MS Teams page in the bottom left hand corner.
    • Bots and Microsoft Azure – When you edit the properties of an existing bot in the list of your bots in Bot Framework such as its messaging endpoint, which is common when first developing a bot, especially if you use ngrok, you will see the “Migration status” column and a blue “Migrate” button that will take you into the Microsoft Azure portal. Don’t click on the “Migrate” button unless that’s what you want to do; instead, click on the name of the bot and you can edit its properties.
      • If you register your bot using Microsoft Azure, it does not need to be hosted on Microsoft Azure.
      • If you do register a bot using the Microsoft Azure portal, you must have a Microsoft Azure account. You can create one for free. To verify your identity when you create one, you must provide a credit card, but it won’t be charged; it’s always free to create and use bots with Microsoft Teams.
  • You project needs to run with a configuration that matches your registered bot’s configuration. To do this, you will need to update the web.config file:
    • In Visual Studio, open the web.config file. Locate the <appSettings>
    • Enter the BotId value. The BotId is the Bot handlefrom the Configuration section of the bot registration.
    • Enter the MicrosoftAppId. The MicrosoftAppId is the App ID from the Configurationsection of the bot registration.
    • Enter the MicrosoftAppPassword. The MicrosoftAppPassword is the auto-generated app password displayed in the pop-up during bot registration.
    • Enter the BaseUri. The BaseUri is the https endpoint generated from ngrok, e.g. https://2d1224fb.ngrok.io.

Here is an example for reference:

<add key=”BotId” value=”Bot_Handle_Here” /> <add key=”MicrosoftAppId” value=”88888888-8888-8888-8888-888888888888″ /> <add key=”MicrosoftAppPassword” value=”aaaa22229999dddd0000999″ /> <add key=”BaseUri” value=”https://#####abc.ngrok.io” />

 

  • In Visual Studio click the “Start Debugging” button.
  • Once the app is running, a manifest file is needed:
    • In the Solution Explorer pane of Visual Studio, navigate to the file, manifest/manifest.json – change all instances of the following patterns:
      • <<REGISTERED_BOT_ID>> (there are 3): change to your registered bot’s app ID
      • <<BASE_URI>> (there are 2): change to your https endpoint from ngrok
      • <<BASE_URI_DOMAIN>> (there is 1): change to your https endpoint from ngrok excluding the “https://” part
  • Save the changes to manifest.json.
  • Zip it and the bot_blue.png file located next to it together to create a “manifest.zip” file. Make sure that files are at the top level of the ZIP package, not a subfolder.

Congratulations! You have just created and sideloaded your first Microsoft Teams app! Try adding a configurable tab or at-mentioning your bot in a channel by its registered name (@Sample-App-csharp Hello).

 

If C# isn’t your language of choice, you may be interested in the Node.js version instead: https://github.com/OfficeDev/microsoft-teams-sample-complete-node.

As always, we welcome your feedback. We look forward to seeing what great experiences you can bring to Microsoft Teams.

 

Category
Microsoft Teams
Topics
Microsoft Bot Framework

Read next