Get started on the Microsoft Teams platform with C#/.NET and App Studio

The Microsoft Teams developer platform makes it easy for you to extend Teams and integrate your own applications and services seamlessly into the Teams workspace. These apps can then be distributed to your enterprise or for teams around the world.

To extend Microsoft Teams, you will need to create a Microsoft Teams app. A Microsoft Teams app is a web application that you host. This app can then be integrated into the user's workspace in Teams.

This tutorial helps you get started creating a Microsoft Teams app using C# on .NET. You can test the app by loading it into a Team that you have permissions for, or into a test tenant created using the Office Developer Program.

Before you start this tutorial

You will need an Office 365 tenant that has been set up for development, and you will need to configure teams to allow you to upload apps. You can work with your Office 365 administrator to confirm that your tenant is ready, or you can install a private evaluation version of Office 365 that you can manage. For more information see these topics:

Get prerequisites

To complete this tutorial, you need to get the following tools:

If you see an option to add git to the PATH during installation, choose to do so. It will be handy.

Verify your git installation by running the following in a terminal window:

Note

Use the terminal window that you are most comfortable with on your platform. These examples use Bash, but will run on most platforms.

$ git --version
git version 2.17.1.windows.2

Make sure to launch Visual Studio 2017 and install any updates if shown.

You can continue to use this terminal window to run the commands that follow in this tutorial.

Download the sample

We have provided a simple Hello, World! sample in C# to get you started. In a terminal window, run the following command to clone the sample repository to your local machine:

git clone https://github.com/OfficeDev/msteams-samples-hello-world-csharp.git

Tip

You can fork this repo if you want to modify and check in your changes to GitHub for future reference.

Build and run the sample

Once the repo is cloned, use Visual Studio to open the solution file Microsoft.Teams.Samples.HelloWorld.sln from the root directory of the sample and click Build Solution from the Build menu. You can run the sample by pressing F5 or choosing Start Debugging from the Debug menu.

When the app starts, you will see a browser window open with the root of the app launched. You can navigate to the following URLs to verify that all the app URLs are loading:

Host the sample app

Remember that apps in Microsoft Teams are web applications exposing one or more capabilities. For the Teams platform to load your app, your app must be reachable from the internet. To make your app reachable from the internet, you need to host your app. You can either host it in Microsoft Azure for free or create a tunnel to the local process on your development machine using ngrok. When you finish hosting your app make a note of its root URL. It will look something like: https://yourteamsapp.ngrok.io or https://yourteamsapp.azurewebsites.net.

Tunnel using ngrok

For quick testing you can run the app on your local machine and create a tunnel to it through a web endpoint. ngrok is a free tool that lets you do just that. With ngrok you can get a web address such as https://d0ac14a5.ngrok.io (this URL is just an example). You can download and install ngrok for your environment. Make sure you add it to a location in your PATH.

Once you install it, you can open a new terminal window and run the following command to create a tunnel. The sample uses port 3333, so be sure to specify it here.

ngrok http 3333 -host-header=localhost:3333

Ngrok will listen to requests from the internet and will route them to your app running on port 3333. You can verify by opening your browser and going to https://d0ac14a5.ngrok.io/hello to load your app's hello page. Please be sure to use the forwarding address displayed by ngrok in your console session instead of this URL.

Note

If you have used a different port in the build and run step above, make sure you use the same port number to setup the ngrok tunnel.

Tip

It is a good idea to run ngrok in a different terminal window to keep it running without interfering with the app which you might later have to stop, rebuild and rerun. The ngrok session will return useful debugging information in this window.

The app will only be available during the current session on your development machine. If the machine is shut down or goes to sleep the service will no longer be available. Remember this when sharing the app for testing by other users. If you have to restart the service it will return a new address and you will have to update every place that uses that address. The paid version of Ngrok does not have this limitation.

Host in Azure

Microsoft Azure lets you host your .NET application on a free tier using shared infrastructure. This will be sufficient to run this Hello World sample. See creating a new free account for more information.

Visual Studio has built-in support for app deployment to different providers, including Azure. For more details see Publish your .NET Teams app in Azure.

Use App Studio to update the app package

App Studio is a Teams app that you can install from the Teams store. It simplifies the creation and registration of an app.

To install App Studio in Teams, click on the app store icon at the bottom of the left hand bar, and search for App Studio.

Once you find the tile for App Studio, click on it and choose install in the dialog that pops up.

Once App Studio is installed click on the Manifest editor tab to begin creating the app package for your Teams app.

The sample comes with its own pre-made manifest, and is designed to build an app package when the project is built. On .NET this is done in Visual Studio, and on Node JS this is done by typing gulp at the command line in the root directory of the project.

$ gulp
[13:39:27] Using gulpfile ~\documents\github\msteams-samples-hello-world-nodejs\gulpfile.js
[13:39:27] Starting 'clean'...
[13:39:27] Starting 'generate-manifest'...
[13:39:27] Finished 'generate-manifest' after 11 ms
[13:39:27] Finished 'clean' after 21 ms
[13:39:27] Starting 'default'...
Build completed. Output in manifest folder
[13:39:27] Finished 'default' after 62 μs

The name of the generated app package is helloworldapp.zip. You can search for this file if the location is not clear in the tool you are using.

In the next part of this walkthrough you are going to modify this app package by selecting the Import an existing app tile in the Manifest Editor.

Once the app package has been imported App Studio should look like this:

Click on the tile for your newly imported app, Hello World.

There is a list of steps in the left-hand side of the Manifest editor, and on the right a list of properties that need to be filled in for each of those steps. Since you started with a sample app, much of the information is already filled out. The next steps will walk you through changing the parts that still need to be updated.

App details

Click on the App details entry under Details. Click the Generate button to create a new app id.

Your new app id should look something like: 2322041b-72bf-459d-b107-f4f335bc35bd.

Look through the rest of the App details in the right hand pane, and familiarize yourself with some of the entries such as Developer information and Branding. These sections are important if you are writing a new app for distribution.

Capabilities: Tabs

Tabs are among the simplest elements to add to a Teams app. The sample app already supports several tabs, and you can enable them as follows.

Team tab

Your app can only have one Team tab.

In this sample, the Team tab is where your configuration page goes. Click on the ... symbol at the end of the entry and choose Edit from the drop-down. Change the URL to https://yourteamsapp.ngrok.io/configure where yourteamsapp.ngrok.io should be replaced by the URL that you used above when hosting your app.

Personal tabs

Your app can have up to 16 tabs, including the team tab.

Personal tabs are represented differently from the team tab. You should see Hello Tab already listed in the personal tabs list. At the moment it has a placeholder value com.contoso.helloworld.hellotab. Click on the ... symbol at the end of the entry and choose Edit from the drop-down. The following dialog will appear.

There are two fields that you need to update with your app URL.

  • Change Content URL to https://yourteamsapp.ngrok.io/hello
  • Change Website URL to https://yourteamsapp.ngrok.io/hello

Where yourteamsapp.ngrok.io should be replaced by the URL that you used above when hosting your app.

Bots

Bots are the most common way to add functionality to your app. The hello world sample already has a bot as part of the sample, but it has not been registered with Microsoft yet.

The bot that was imported from the sample does not have an App ID associated with it yet. You will have to create a new bot so that App Studio can create a new App ID and register it with Microsoft. Note that this is the App ID for the bot, which is different from the App ID that we created for the app in a earlier step. Each bot in an app requires its own App ID.

Click the delete button next to the Imported bot in the bot list.

Now there are no bots left to show. Click Setup. This will display the Set up a bot dialog.

Add a bot name such as Contoso bot, and click both the buttons under scope.

Choose Create bot to exit the dialog. App Studio will spend a moment registering your bot with Microsoft, and then should display your new bot in the bot list. Now would be a good time to open a text file in notepad and copy and paste your new bot id into it. You will need this id later.

Click Generate New Password, and make a note of the password in the same text file you noted your Bot app ID in. This is the only time your password will be shown, so be sure to do this now.

Update the Bot endpoint address to https://yourteamsapp.ngrok.io/api/messages, where yourteamsapp.ngrok.io should be replaced by the URL that you used above when hosting your app.

Now would be a good time to save your text file if you have not done so already. You will add this information to your hosted app later in this walkthrough, which will allow secure communication with your bot.

Messaging extensions

Messaging extensions let users ask for information from your service and post that information, in the form of cards, right into the channel conversation. Messaging extensions appear along the bottom of the compose box.

Click on Messaging extensions under Capabilities in the left hand column of App Studio to begin configuring the messaging extension.

The sample messaging extension is listed in the right hand pane under Messaging Extensions. Click Delete again to remove this entry, and then click the Set up button following the same steps as you followed for bots. This will display the Messaging Extension dialog.

In the Messaging Extension dialog, choose the Existing tab, then under Bot ID choose Select from one of my existing bots.

Expand the drop down below Bot ID and choose the ID of the bot you created previously. Then choose the Save button. This returns you to the main page for Messaging Extensions.

In the Messaging endpoint section update the Bot endpoint address to https://yourteamsapp.ngrok.io/api/messages where yourteamsapp.ngrok.io should be replaced by the URL that you used above when hosting your app.

You now need to add a Command to your messaging extension. Do this by clicking the Add button in the Command section of Messaging Extensions. The New command dialog will appear.

In the New command dialog enter the following values.

Under New command:

  • Command ID = getRandomText
  • Title = Get some random text for fun
  • Description = Gets some random text and images

Under Parameter:

  • Name = cardTitle
  • Title = Card title
  • Description = Card title to use

You are now done with configuring your messaging extension.

Register your app in Teams

You have now completed entering the details of your app, but two steps remain. First you must use the Test and Distribute section of App Studio to install your app in Teams, and second you must update your hosted application with the App ID and password for your bot. Remember that the sample expects to use the same App ID and password for both the bot and the messaging extension.

Click on the Test and distribute item under Finish in the left hand column of App Studio.

In order to upload your app to Teams, click the Install button under Test and Distribute.

Click on the Search box in the Add to a team section and select a team to add the sample app to. Usually you will want to set up a special team for testing.

Click the Install button at the bottom of the dialog.

This finishes the App Studio portion of this walkthrough. You should now see your app running in Teams, however the bot and the messaging extension will not work until you update the hosted applications environment to know what the App IDs and passwords are.

Update the credentials for your hosted app

The sample app requires the following environment variables to be set to the values you made a note of earlier.

Open up the web.config file and find the appSettings section. Update the MicrosoftAppId value with your Bot ID that you saved earlier. Update the MicrosoftAppPassword with the Bot password you saved earlier.

Once these changes are made, rebuild the app. If you are using ngrok, run the app locally, and if you are hosting in Azure redeploy the app.

Configure the app tab

Once you install the app into a team, you will need to configure it to show content. Go to a channel in the team where you installed the sample app and click on the '+' button to add a new tab. You can then choose Hello World from the Add a tab list. You will then be presented with a configuration dialog. This dialog will let you choose which tab to display in this channel. Once you select the tab and click on Save then you can see the Hello World tab loaded with the tab you chose.

Test your bot in Teams

You can now interact with the bot in Teams. Choose a channel in the team where you registered your app, and type @your-bot-name. This is called an **@mention**. Whatever message you send to the bot will be sent back to you as a reply.

Test your messaging extension

To test your messaging extension, you can click on the three dots below the input box in your conversation view. A menu will pop up with the 'Hello World' app in it. When you click it, you will see a bunch of random texts showing up. You can choose any one of them and it will be inserted it into your conversation.

Choose one of the random texts, and you will see a card formatted and ready to send with your own message at the bottom.