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.

Prepare your development environment

The first thing you'll need to do is prepare your development environment. You'll need to make sure custom app uploading is enabled for the Office 365 organization you want to build your app in. If you need a dedicated development tenant, you can sign up for the Office 365 developer program. For additional information see Setup your development environment.

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:


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

Make sure to launch the latest version of Visual Studio 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


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:


If you receive an error like Could not find a part of the path … bin\roslyn\csc.exe, try updating the package with the command Update-Package Microsoft.CodeDom.Providers.DotNetCompilerPlatform -r. See this question on StackOverflow for additional details.

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: or

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 (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 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.


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.


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.

Visual Studio

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.

Finding App Studio in the Store View

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

Installing App Studio

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

App Studio

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 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.

Importing an existing app

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

Importing the app package

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

Newly imported app view

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.

Adding a Teams 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 where 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.

Adding a personal tab dialog

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

  • Change Content URL to
  • Change Website URL to

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


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.

Adding a bot

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.

Adding a bot dialog

Add a bot name such as Contoso bot, and select all three 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, where 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.

Adding a 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.

Select the Use existing bot tab, then Select from one of my existing bots. In the drop-down menu, select the bot you created in the section above. Add a Bot name and click Save to close the dialog.

Under the Command section, click Add. We're adding a search-based command, so choose the Allow users to query your service... option.

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

Once you're entered the information, click Save to close the dialog.

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.

Testing your app

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

Adding a messaging extension dialog

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.

The finished app

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 appsettings.json file. Update the MicrosoftAppId value with your Bot ID that you saved earlier. Update the MicrosoftAppPassword with the Bot password you saved earlier.

Setting the keys

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.

Screenshot of configure

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.

Bot responses

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.

Messaging extension menu Messaging extension result

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

Messaging extension send